Upgrade

    This document details the process for upgrading an existing ChemLocator docker installation. If you have not installed ChemLocator yet, the installation guide is appropriate.

    Step 1 - Connect to Docker host and find ChemLocator installation

    Connect to the host machine where the ChemLocator installation is located, using ssh. Next, find the folder where ChemLocator is installed.

    {info} We typically recommend /usr/share/chemaxon/chemlocator/ as the default folder. In case there are multiple environments hosted (e.g. production, testing, etc), there may be further subfolders. The folder we are looking for is the one which contains the docker-compose.yml, for the environment we want to upgrade.

    Change into this folder via the cd command.

    All of the following steps assume you are in this folder.

    Step 2 - Docker login to hub.chemaxon.com

    The ChemLocator repository is located at hub.chemaxon.com. By performing a docker login to this repository, you will be able to pull the ChemLocator docker images. To start the login, use the following command:

    docker login hub.chemaxon.com

    You can find a guide on how to login to ChemAxon public repositories here.

    Step 3 - Stop the ChemLocator containers

    Stop the ChemLocator containers using the following command:

    sudo docker-compose stop

    Step 4 - Update version number in .env file

    Note: this step might be optional for development environments.

    Edit the .env file with any text editor. Version number you are currently using will appear assigned to CL_VERSION. As an example, changing form version v0.9.2.0 to v1.0.0.0:

    Before the change:

      CL_VERSION=v0.9.2.0

    After the change:

      CL_VERSION=v1.0.0.0

    Step 5 - Docker-compose pull to update images

    You can use the docker-compose pull command to update the images mentioned in the docker-compose.yml file. 

    sudo docker-compose pull

    Docker will go through each of the images mentioned in the file, and pull the latest version of the images specified.

    Step 6 - Verify ChemLocator versions

    This step is optional, and can be skipped.

    Since we are going to have a lot of console logs output, it is recommended that you clear your console via the clear command.

    Start up the ChemLocator containers as a foreground process as follows:

    sudo docker-compose up

    There are two checks we can make to see that the images have been updated:

    • In the beginning of the console logs (you will probably need to scroll up several screens worth), you should see messages containing the word "recreating", applied to the containers chemlocator and chemlocator-java. This is the first indication that an upgrade of images has been detected by Docker, and has been performed.
    • Open the ChemLocator UI and log in. In the top right, you should see your username. Clicking it brings up a sub-menu - click "Profile" here. One of the labels on this screen contains the version number, which should match what is in your docker-compose.yml file.

    In preparation for starting ChemLocator as a background process in the next step, first stop it by pressing Ctrl+C in the console, and waiting for all the containers to stop.

    Step 7 - Start the ChemLocator images as a background process

    Start docker-compose with the -d flag, to indicate that it should run in the background:

    sudo docker-compose up -d