Upgrading¶

Upgrading a Mayan EDMS Docker container is actually a matter of stopping and deleting the container, downloading the most recent version of the image and starting a container again. The container will take care of updating the database structure to the newest version if necessary.

Important

Do not delete the volume storing the data, only the container. Deleting the volume will delete all the document files.

Important

To upgrade the database container, follow the database container upgrade procedure. In some cases, the existing database files may not be compatible with the new database container version. A manual database full dump and subsequent restore may be required.

Docker Compose installation¶

Note

If you are invoking the docker-compose command in the same directory where the file docker-compose.yml resides, there is no need to add the --file docker-compose.yml option.

Note

Use the same project name as your did during installation. This example follows the installation shown in Docker Compose installation which specifies a project name of mayan.

Upgrade between minor versions¶

Stop and delete the container stack:

Important

Do not skip this step. If the stack is not taken down, important internal upgrades processes like database migrations will not be executed.
```
docker-compose --file docker-compose.yml --project-name mayan down
```
Pull the new image version:
```
docker pull mayanedms/mayanedms:s4
```
Note

Do not use the latest tag, it does not point to the latest version.
Rename the Docker Compose file and keep it for future reference:
```
mv docker-compose.yml docker-compose.yml.bck
```

Download the new Docker Compose files:

curl https://gitlab.com/mayan-edms/mayan-edms/-/raw/master/docker/docker-compose.yml -O
curl https://gitlab.com/mayan-edms/mayan-edms/-/raw/master/docker/env_file -O
curl https://gitlab.com/mayan-edms/mayan-edms/-/raw/master/docker/.env -O

Edit and the adjust the new Docker Compose file, copying over all relevant values like username, password, etc.
Launch the rest of container stack:
```
docker-compose --file docker-compose.yml --project-name mayan up --detach
```
Note

The app container will perform all the necessary migrations to the existing data.

Upgrade between major versions¶

Note

The additional steps in this process are required to move the database content from one version of PostgreSQL to a new version of PostgreSQL. If the upgrade is between major versions of Mayan EDMS but the major version of the database manager remains the same, this process is not necessary and the simpler upgrade process can be used.

Dump the existing database into an SQL file.

docker-compose --file docker-compose.yml --project-name mayan exec postgresql /bin/bash -c 'pg_dumpall --username="$POSTGRES_USER"' > mayan.sql

Verify the SQL file:
```
cat mayan.sql | more
```

Stop and delete the container stack:

docker-compose --file docker-compose.yml --project-name mayan down

Pull the new image version:
```
docker pull mayanedms/mayanedms:s4
```
Note

Do not use the latest tag, it does not point to the latest version.

Make a backup of the database binary files:

docker volume inspect mayan_postgres

> [
>     {
>         "CreatedAt": "2021-06-17T05:32:28Z",
>         "Driver": "local",
>         "Labels": {
>             "com.docker.compose.project": "mayan",
>             "com.docker.compose.version": "1.29.1",
>             "com.docker.compose.volume": "postgres"
>         },
>         "Mountpoint": "/var/lib/docker/volumes/mayan_postgres/_data",
>         "Name": "mayan_postgres",
>         "Options": null,
>         "Scope": "local"
>     }
> ]

sudo cp --recursive /var/lib/docker/volumes/mayan_postgres/_data ~/mayan_binary_backup

Delete the database volume:
```
docker volume rm mayan_postgres
```
Important

Only delete the database volume after dumping the data into SQL, backing up the volume binary content, and verifying that both files were created successfully. Do not delete the app volume. This is where the actual document files are stored.
Rename the Docker Compose file and keep it for future reference:
```
mv docker-compose.yml docker-compose.yml.bck
```

Download the new Docker Compose files:

curl https://gitlab.com/mayan-edms/mayan-edms/-/raw/master/docker/docker-compose.yml -O
curl https://gitlab.com/mayan-edms/mayan-edms/-/raw/master/docker/env_file -O
curl https://gitlab.com/mayan-edms/mayan-edms/-/raw/master/docker/.env -O

Edit and the adjust the new Docker Compose file, copying over all relevant values like username, password, etc.

Launch the database container alone:

docker-compose --file docker-compose.yml --project-name mayan up --detach postgresql

Load the database data from the SQL file:

cat mayan.sql | docker-compose --file docker-compose.yml --project-name mayan exec -T postgresql /bin/bash -c 'psql --dbname="$POSTGRES_DB --username="$POSTGRES_USER"'

Launch the rest of container stack:
```
docker-compose --file docker-compose.yml --project-name mayan up --detach
```
Note

The app container will perform all the necessary migrations to the existing data.