Cold upgrade of the docker container from a new image

Overview

When updating via the API is impossible, an upgrade must be performed with docker image replacement and container recreation.

All data stored in the DB, as well as files and directories in host volumes, remain untouched and are preserved and used after the new system version starts.

Upgrade procedure

Step 1. Find the current platform container name.

This is a name of the format "era<Postfix>" specified during system installation or the previous upgrade.

You can find it by running:

docker ps -a

and finding the active container with the specified name format.

Step 2. Generate the container start string.

To do this, run the script from the installer — gen_container_cmd_ssh.sh

bash gen_container_cmd_ssh.sh --user=user --host=192.168.10.127 --port=22

The script asks for the missing connection parameters, copies the installer to /tmp/era_installer on the server, and runs container inspection there. Nothing on the server is changed: the command is recovered via docker inspect.

It then displays the container list — the row shows both the data directory and the name:

Which container?
   1) directory: /opt/era_11, container: era_11
   2) directory: /opt/era_11/postgresql, container: postgres_11

you must specify the container number for which to generate the command (in the example: 1), after which the command is generated, for example:

1
Recovering the start command for era_11
docker run --name=era_11 \
           --volume=/opt/era_11/syncroot:/var/lib/era_files/syncroot:rslave \
           --volume=/opt/era_11/era_recpath:/var/lib/era_files/recpath:rslave \
           --volume=/opt/era_11/era_siteshare:/var/lib/era_files/siteshare:rslave \
           --volume=/opt/era_11/c:/var/lib/era_files/c:rslave \
           --volume=/opt/era_11/lib:/var/lib/era:rslave \
           --volume=/opt/era_11/local:/var/lib/era_files/local:rslave \
           --volume=/opt/era_11/era_globalshare:/var/lib/era_files/globalshare:rslave \
           --volume=/opt/era_11/a:/var/lib/era_files/a:rslave \
           --volume=/opt/era_11/b:/var/lib/era_files/b:rslave \
           --volume=/opt/era_11/log:/var/log/era:rslave \
           --volume=/opt/era_11/rectemp:/var/lib/era_files/rectemp:rslave \
           --volume=/opt/era_11/logstore:/var/lib/era_files/logstore:rslave \
           --cap-add=CAP_NET_ADMIN \
           --cap-add=CAP_NET_BIND_SERVICE \
           --cap-add=CAP_NET_RAW \
           --network=host \
           --restart=unless-stopped \
           --env=STARTTYPE=firstinit \
           --env=SRVIP=192.168.10.127 \
           --env=SRVNAME=testsrv \
           --env=PSK=123456 \
           --env=SQLSTR=host:192.168.10.127,port:5451,login:platformpgadmin,pwd:Era_User_pwd,database:postgres \
           --env=GENDOMAIN=tester.ru \
           --tty \
           --detach=true \
           era:v.1

The command is needed in step 5. No need to memorize it: the installer saves it as a file next to its log — /tmp/era_installer/logs/<container name>.run.sh on the server, permissions 0700. When run via gen_container_cmd_ssh.sh, this file along with the log is returned to your machine, to logs/remote/<server address>/.

IMPORTANT! Check that the resulting command contains the "--restart unless-stopped" parameter. Without it the container will not start after a future update.

IMPORTANT! Before applying, remove from the string the volume specification for localtime and timezone, since starting from version 1.9.0 the time zone is configured inside the container via the master domain settings.timezone parameter

Example of lines to remove:

  --volume=/etc/localtime:/etc/localtime:rprivate \
  --volume=/etc/timezone:/etc/timezone:rprivate \

Step 3. Load the new image

docker load -i <ImageFileName>

replacing "<ImageFileName>" with the name of the docker image with the new version. The image has a name of the format "era_<VERSION>_docker.tar.gz".

The docker load command prints the name under which the image was loaded, for example Loaded image: era:v.1. This name is the last line in the command from step 2. If the new image loaded under the same name, the command will start the new version — nothing needs to be replaced in it; the old container will keep running on the previous image because it is bound to its identifier, not to the name. If the name is different — substitute it at the end of the command instead of the previous one.

Step 4. Stop the current container

docker container stop <CurrentContainerName>

Stopping is mandatory, not desirable: the platform container runs with --network=host, i.e., it occupies host ports directly. Two containers with this setting will not start simultaneously — the new one will hit occupied ports. Do not delete the old container at this step: stopped, it does not interfere and remains the rollback method.

Step 4a. Back up the database

Recommended before any upgrade. For transitions marked as irreversible in the release notes (for example, from a version below 1.13 to 1.13 and above), it is mandatory, together with a copy of the mic directory or the entire working directory: Rollback after an irreversible upgrade.

Step 5. Start the new container

Execute the command from step 2, replacing the container name with the new one. For example, if the original command was:

docker run --name era<Postfix1> ...

then it becomes:

docker run --name era<Postfix2> ...

The new container name is necessary for a quick rollback to the previous version. In the variant with a working directory copy, the /var/lib/era volume is also replaced in the command (more). A second container with the same name cannot be created and started. After startup and state verification the previous container can be deleted.

Step 6. Verify that the new version started

docker ps

The new container must be in the Up state, and the old one must be absent from this list (it is stopped).

Next, check what the platform reported at startup:

docker logs <NewContainerName> --tail 50

The platform reports successful initialization with a line like:

EraInstallResult: <<success<>Install server success!>>

This exact line is what the installer waits for during a normal installation. If an error came instead of success, the new container can be stopped and the old one started. The exception is an upgrade to 1.12 and newer: rollback only to 1.11.9 and newer, more.

Step 7. Check the time zone inside the container

To do this, check the master domain timezone setting (domain.settings.timezone) and, if necessary, specify the required time zone, then restart the system (or container)