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.

Simple installation

  1. Stop the container to be upgraded:

docker stop mayan-edms
  1. Remove the container:

docker rm mayan-edms
  1. 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.

  1. Start the container again with the new image version:

    docker run \
    -d \
    --name mayan-edms \
    --restart=always \
    -p 80:8000 \
    -e MAYAN_CELERY_BROKER_URL="redis://:mayanredispassword@172.17.0.1:6379/0" \
    -e MAYAN_CELERY_RESULT_BACKEND="redis://:mayanredispassword@172.17.0.1:6379/1" \
    -e MAYAN_DATABASES="{'default':{'ENGINE':'django.db.backends.postgresql','NAME':'mayan','PASSWORD':'mayanuserpass','USER':'mayan','HOST':'172.17.0.1'}}" \
    -e MAYAN_LOCK_MANAGER_BACKEND="mayan.apps.lock_manager.backends.redis_lock.RedisLock" \
    -e MAYAN_LOCK_MANAGER_BACKEND_ARGUMENTS="{'redis_url':'redis://:mayanredispassword@172.17.0.1:6379/2'}" \
    -v /docker-volumes/mayan-edms/media:/var/lib/mayan \
    mayanedms/mayanedms:s4
    

    Note

    Ensure any customized environment variables used when launching the old version of the container match the variables used to launch the new version (e.g database password). If Mayan loads but login fails post upgrade, this could be a cause.

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

  1. Stop and delete the container stack:

    docker-compose --file docker-compose.yml --project-name mayan down
    
  2. Rename the Docker Compose file and keep it for future reference:

    mv docker-compose.yml docker-compose.yml.bck
    
  3. 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
    
  4. Edit and the adjust the new Docker Compose file, copying over all relevant values like username, password, etc.

  5. 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.

  1. 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
    
  2. Verify the SQL file:

    cat mayan.sql | more
    
  3. Stop and delete the container stack:

    docker-compose --file docker-compose.yml --project-name mayan down
    
  4. 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
    
  5. 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.

  6. Rename the Docker Compose file and keep it for future reference:

    mv docker-compose.yml docker-compose.yml.bck
    
  7. 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
    
  8. Edit and the adjust the new Docker Compose file, copying over all relevant values like username, password, etc.

  9. Launch the database container alone:

    docker-compose --file docker-compose.yml --project-name mayan up --detach postgresql
    
  10. 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 --username="$POSTGRES_USER"'
    
  11. 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.