Upgrading InterSystems IRIS Containers

There is a fundamental difference between the procedure for upgrading or modifying the containerized deployment of an application and the procedure for upgrading or modifying its non-containerized counterpart. This difference is due to the fact that containers are ephemeral by design: whereas you update a non-containerized application by running a script or installing a plug-in which changes the code of an existing deployment in place, updates to a containerized application are implemented within the application’s container image, and not the container itself. Therefore, to deploy the new version of a containerized application, the existing container based on the old image must be entirely replaced by a new container based on the new image.

The durable %SYS feature allows for the persistence of instance-specific application data from the old InterSystems IRIS container to the new one. After ensuring that you have taken all applicable pre-upgrade steps, you can remove (or rename) the existing container and then invoke the docker run command to create and start a new container based on the updated image, using the original container name and specifying the same relationships to the container’s external environment. Specifically, you must ensure that:

the same ports are exposed (using the docker run command’s --publish option)
the same networks are configured (using the --network option)
the same external storage locations are mounted, including the durable %SYS volume (using the --volume option).
Important:

Before upgrading an InterSystems IRIS container that uses durable %SYS to version 2021.2 or later, you must make the existing durable directory writable by user 51773—for example, with this command:
```
chown -R 51773:51773 root-of-durable-%SYS-directory
```
You will most likely need root privileges to make this change.

Upon completion of all applicable post-upgrade steps (recompiling classes, for example), the new container can act upon the application data which persists in the durable %SYS volume and interact with its external environment, just as the old one did. In other words, the application maintains an effective continuity across versions from an outside perspective, even though those versions are provided by separate containers, created from separate images. If the version of the instance-specific data does not match the version of the new instance, durable %SYS upgrades it to the instance’s version as needed. (Refer to Durable %SYS for Persistent Instance Data for further details.)

Caution:

Before starting the new container, you must either remove or stop and rename the original container. Removing the original container is the best practice, because if the original container is started following the upgrade, two instances of InterSystems IRIS will be attempting to use the same durable %SYS data, which will result in unpredictable behavior, including possible data loss.

Typically, the upgrade command is identical to the command used to run the original container, except for the image tag. In the following docker run command, only the version_number portion would change between the docker run command that created the original container and the one that creates the upgraded container:

$ docker stop iris
$ docker rm iris
$ docker run --name iris --detach --publish 9091:1972 \
  --volume /data/durable:/dur --env ISC_DATA_DIRECTORY=/dur/iconfig \
  intersystems/iris:<version_number> --key /dur/key/iris.key

Note:

For information about upgrading a Web Gateway container with a durable data directory, see Options for Running Web Gateway Containers.

Common Upgrade Issue: Troubled Shutdown Prevents Upgrade

When durable %SYS detects that an instance being upgraded did not shut down cleanly, it prevents the upgrade from continuing. This is because WIJ and journal recovery must be done manually when starting such an instance to ensure data integrity. To correct this, you must use the procedures outlined in Starting InterSystems IRIS Without Automatic WIJ and Journal Recovery to start the instance and then shut it down cleanly. If the container is running, you can do this by executing the command docker exec -it container_name bash to open a shell inside the container and following the outlined procedures. If the container is stopped, however, you cannot start it without automatically restarting the instance, which could damage data integrity, and you cannot open a shell. In this situation, use the following procedure to achieve a clean shutdown before restarting the container:

Create a duplicate container using the same command you used to create the original, including specifying the same durable %SYS location and the same image, but adding the iris-main -up false option (see The iris-main Program). This option prevents automatic startup of the instance when the container starts.
Execute the command docker exec -it container_name bash to open a shell inside the container.
Follow the procedures outlined in Starting InterSystems IRIS Without Automatic WIJ and Journal Recovery.
When recovery and startup are complete, shut down the instance using iris stop instance_name. (The instance in a container provided by InterSystems is always named IRIS.)
Start your original container. Because it uses the durable %SYS data that you safely recovered in the duplicate container, normal startup is safe.