Updating

Basic notes

Before any update you should create a backup of your data. Also note the version of mongodb that your running installation uses. Read the whole page before doing upgrade.

Note about Mongodb

Contact sync service supports mongo versions from 3.0 to 3.6. Currently we do not support mongo 4.0 and newer.

We know that mongo version 3.0 in docker has problems with running on new Debian systems. In our installation guides we set mongo version to 3.6 in docker-compose.yml file. If you are running contact sync service with mongo 3.0 (version previously in the installation guide) you may want to keep this version.

If you wish to change version to 3.6 (because you are upgrading the underlying system or because you are moving to a new machine), the easiest way to do that is doing backup and restore upgrade: backing up your data, starting new version with empty database and importing data from the backup.

Simple updating

Warning

If you are upgrading from version 1.18 or older (released in 2020)), you need to generate and mount keys into the containers.

If you installed your Contact Synchronization server using our basic installation instructions, use the following steps to upgrade.

Enter contacts directory that you created during the installation procedure. If you removed the directory, you can recreate it again. First download new versions of the services:

docker-compose pull

Then run the following command:

docker-compose up -d

This will recreate all the containers with the newest version.

Note

After the update you may want to clean redis using the command docker exec contacts_redis_1 redis-cli flushdb if you encounter problems.

Updating from versions without keys

If you are running contact sync server released before 2021, you will need to generate the private and public keys. Key generation is described in the bacic installation guide under Key generation.

Then edit your docker compose file and add volumes section under sso:

volumes:
    - /etc/acrobits/sso:/etc/acrobits/sso/:ro

and a similar one under contact_server:

volumes:
    - /etc/acrobits/contact_server:/etc/acrobits/contact_server:ro

See the installation guide to see it in context.

After you perform these steps, you can run upgrade as usual.

Upgrading with advanced installation

Before upgrade do a backup of your data.

If you are upgrading from a version that did not use the private and public keys (check if you have a file /etc/acrobits/sso/private-key.pem) generate a private and public key pair. See section Key generation for for the procedure. You will also need to place public key into the portal. Then check your docker-compose.yml file that you mount the whole directores from /etc/acrobits into your containers and not only single application.yml files.

Check that your configuration files (/etc/acrobits/sso/application.yml, /etc/acrobits/contact_server/application.yml and /etc/acrobits/admin-server/application.yml) are as described in the advanced installation guide. If they are, you probably have a version that is new enough and you can use the simple method of updating as described above.

If your configuration files differ, continue with this method.

Go into your contacts directory (the one that contains docker-compose.yml file) and turn the service off.

docker-compose down

Modify the files in /etc/acrobits/ so that they look like the ones in advanced installation guide.

Then modify your nginx configuration so that it looks like the one in the installation guide. Note especially that proxy_pass directive for /admin/ endpoint does not end with /.

We did only minimal changes in docker-compose.yml. We updated redis and mongodb versions. You may update redis version if you wish but should not update mongodb version if the current one runs without any problem (see note about mongodb above on this page).

After you made changes to appropriate configuration files, go to a directory with docker-compose.yml file and run the following:

docker-compose pull
docker-compose up -d

Backup and restore upgrade

This is a procedure that can be used to move the installation to a different machine. It may also be used when mongodb needs to be upgraded (for example when upgrading underlying operating system, since mongodb version 3.0 is known not to run on on newer Debian systems).

Start with doing a backup of your data using backup guide.

Stop the services.

docker-compose down

Save the backup of data to a safe location and remove directory /data/mongo.

Recreate the files according to the installation guide. Recreate the following files as if you did a clean installation: docker-compose.yml, your nginx configuration and (if using advanced installation) files in /etc/acrobits.

Start the services:

docker-compose down

You now have a clean installation. Do a data restore using backup guide.