Upgrading InterSystems IRIS Containers

Upgrading InterSystems IRIS Containers

When a containerized application is upgraded or otherwise modified, the existing container is removed or renamed, and a new container is created and started by instantiating a different image with the docker run command. Although the purpose is to modify the application, as one might with a traditional application by running an upgrade script or adding a plug-in, the new application instance actually has no inherent association with the previous one. Rather, it is the interactions established with the environment outside the container — for example, the container ports you publish to the host with the --publish option of the docker run command, the network you connect the container to with the --network option, and the external storage locations you mount inside the container with the --volume option in order to persist application data — that maintain continuity between separate containers, created from separate images, that represent versions of the same application.

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,

For InterSystems IRIS, the durable %SYS feature for persisting instance-specific data is used to enable upgrades. As long as the instance in the upgraded container uses the original instance’s durable %SYS storage location and has the same network location, it effectively replaces the original instance, upgrading InterSystems IRIS. 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. (For more information about Durable %SYS, see Durable %SYS for Persistent Instance Data.)

Before starting the new container, you must either remove or stop and rename the original container.

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

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:

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

2. Execute the command docker exec -it container_name bash to open a shell inside the container.

3. Follow the procedures outlined in Starting InterSystems IRIS Without Automatic WIJ and Journal Recovery.

4. 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.)

5. Start your original container. Because it uses the durable %SYS data that you safely recovered in the duplicate container, normal startup is safe.