Version 4.0.11¶

Released: July 07, 2021

Status: Stable

Changes¶

API¶

The id field was added as a sortable field to all the API endpoints that have ordering enabled.

Docker¶

The wait.sh file was replaced with a Python alternative that can wait on network ports or PostgreSQL directly as a client.

supervisord was upgraded from Debian buster version 3.3.5-1 to Debian bullseye version 4.2.2-2. This version uses Python3 and was the last dependency that required installing Python2 in the Docker image.

Documentation¶

Switch deployment instructions to use venv instead of virtualenv. The direct deployment and the Docker image now use the same Python virtual environment alternative.

Documents¶

Updated the date time copy code from migration document:0063 to work with databases that store time zone information and those that don’t.

GitLab CI¶

Added support for using local or external PIP caches to build Docker images.

The GitLab CI upgrade tests now update a test document to populate the older version install and trigger more migration code paths.

Platform¶

Updated all shell usage from bash to sh. sh symlinks to dash in the Docker image. This also expands the usability of the supervisor file for direct deployments in more operating systems.

Improved the way the user_settings_folder variable was created. It now works correctly with MEDIA_ROOT paths that contain a trailing slash and those that don’t.

Other¶

Added a Vagrant setup for testing. Integrates project https://gitlab.com/mayan-edms/mayan-edms-vagrant.

Removals¶

None

Upgrade process¶

Docker Compose¶

Check the Docker upgrading chapter for the complete upgrade process.

Direct deployment¶

Upgrading from Mayan EDMS 3.5.x¶

Important

Supervisord must be upgraded to version 4.2.2. See troubleshooting section: After upgrade to version 4.1

Stop supervisord:
```
sudo systemctl stop supervisor
```

Make a backup of your supervisord file:

sudo cp /etc/supervisor/conf.d/mayan-edms.conf /etc/supervisor/conf.d/mayan-edms.conf.bck

Make a backup of your database:

Use the respective backup command for the database:
- PostgreSQL: https://www.postgresql.org/docs/current/backup-dump.html
- MySQL: https://dev.mysql.com/doc/refman/5.7/en/mysqldump.html

Upgrade to the latest pip version:

sudo --user=mayan /opt/mayan-edms/bin/pip install --upgrade pip

Remove deprecated requirements:

sudo --user=mayan curl https://gitlab.com/mayan-edms/mayan-edms/raw/master/removals.txt --output /tmp/removals.txt \
&& sudo --user=mayan /opt/mayan-edms/bin/pip uninstall --requirement /tmp/removals.txt --yes

Update the Mayan EDMS Python package:
```
sudo --user=mayan /opt/mayan-edms/bin/pip install mayan-edms==4.4.5
```
the requirements will also be updated automatically.
Update the Redis configuration to serve at least 3 databases:

Replace:
```
databases ...
```
with:
```
databases 3
```
Restart Redis for the changes to take effect:
```
sudo systemctl restart redis
```

Edit the config file at /opt/mayan-edms/media/config.yml:

Replace:

LOCK_MANAGER_BACKEND: ...
LOCK_MANAGER_BACKEND_ARGUMENTS: ...

with:

LOCK_MANAGER_BACKEND: mayan.apps.lock_manager.backends.redis_lock.RedisLock
LOCK_MANAGER_BACKEND_ARGUMENTS: {'redis_url':'redis://:mayanredispassword@<IP address of Redis server>:6379/2'}

Update the supervisord configuration file. Replace the environment variables values shown here with your respective settings. This step will refresh the supervisord configuration file with the new queues and the latest recommended layout:
```
sudo --user=mayan MAYAN_MEDIA_ROOT=/opt/mayan-edms/media/ \
/opt/mayan-edms/bin/mayan-edms.py platformtemplate supervisord | sudo sh -c "cat > /etc/supervisor/conf.d/mayan-edms.conf"
```
Edit the supervisord configuration file and update any setting specific to your installation:
```
sudo vi /etc/supervisor/conf.d/mayan-edms.conf
```

Migrate existing database schema and static media files with:

sudo --user=mayan MAYAN_MEDIA_ROOT=/opt/mayan-edms/media/ \
/opt/mayan-edms/bin/mayan-edms.py performupgrade

Start supervisord:
```
sudo systemctl start supervisor
```
Clear the browser cache to avoid loading old web assets.

The upgrade procedure is now complete.

Troubleshooting¶

If you observe the errors:

mayan.apps.file_caching.models.CachePartitionFile.DoesNotExist: CachePartitionFile matching query does not exist.

or:

FileNotFoundError: [Errno 2] No such file or directory: '/var/lib/mayan/document_file_storage/...

follow the solution outlined in the troubleshooting section: After upgrade to version 4.0

Backward incompatible changes¶

None

Issues closed¶

GitLab issue #937 Direct deployment docs don’t provide an automated setup script
GitLab issue #1013 Supervisor template: variable name substitution fails on direct demployment