Running InterSystems Products in Containers

Container Deployment Platforms Supported by InterSystems

Container images from InterSystems comply with the Open Container Initiative (OCIOpens in a new tab) specification, and are built using the Docker Enterprise Edition engine, which fully supports the OCI standard and allows for the images to be certifiedOpens in a new tab and featured in the Docker Hub registry.

InterSystems images are built and tested using the widely popular container Ubuntu operating system, and are therefore supported on any OCI-compliant runtime engine on Linux-based operating systems, both on premises and in public clouds.

Installing Docker

The Docker Engine consists of an open source containerization technology combined with a workflow for building and running containerized applications. To install the Docker engine on your servers, see Install DockerOpens in a new tab in the Docker documentation.

Downloading the InterSystems IRIS Image

The InterSystems Container Registry (ICR) at https://containers.intersystems.com/Opens in a new tab includes repositories for all images available from InterSystems, including InterSystems IRIS images. Using the InterSystems Container RegistryOpens in a new tab describes the images available from the ICR and explains how to use your WRC credentials to authenticate to the registry so you can download them.

Your organization may already have an InterSystems IRIS image available for your use in its own private image registry; if so, obtain the location and the credentials needed to authenticate from the responsible administrator. Once you are logged in to either the ICR or your organization’s registry, you can use the docker pull command to download the image; the following example shows a pull from the ICR.

$ docker login containers.intersystems.com
Username: pmartinez
Password: **********
$ docker pull containers.intersystems.com/intersystems/iris:2023.1.0.299.0
5c939e3a4d10: Pull complete
c63719cdbe7a: Pull complete
19a861ea6baf: Pull complete
651c9d2d6c4f: Pull complete
$ docker images
REPOSITORY                                    TAG            IMAGE ID      CREATED      SIZE
containers.intersystems.com/intersystems/iris 2023.1.0.299.0 15627fb5cb76  1 minute ago 1.39GB
containers.intersystems.com/intersystems/sam  1.0.0.115      15627fb5cb76  3 days ago   1.33GB
acme/centos                                   7.3.1611       262f7381844c  2 weeks ago  192MB
acme/hello-world                              latest         05a3bd381fc2  2 months ag  1.84kB

License Keys for InterSystems IRIS Containers

Like any InterSystems IRIS instance, an instance running in a container requires a license key (typically called iris.key). For general information about InterSystems IRIS license keys, see the “Managing InterSystems IRIS Licensing” chapter of the System Administration Guide.

The InterSystems IRIS Community Edition image described in the previous section comes with a special free temporary license. Generally, however, license keys are not included in an InterSystems IRIS container image. Instead, you must stage a license key in a storage location accessible to the container, typically a mounted volume, and provide some mechanism for copying it into the container, where it can be activated for the InterSystems IRIS instance running there.

The iris-main program, which runs as the blocking entrypoint application of an InterSystems IRIS container, offers an option for handling the license key that can be used in a docker start or docker run command starting an InterSystems IRIS container. The --key option copies the license key from the location you specify to the mgr/ directory of the InterSystems IRIS instance, which means that it is automatically activated when the instance starts. The license key must not be located on the local file system inside the container; typically, it is on a storage location mounted as a volume by the container with the --volume option of the docker run command, often the durable %SYS volume. The syntax of the option is as follows:

--key <key_path>

where key_path is the path to the license key from within the container. For example, if you mount as /external an external storage location that includes a license key in a directory called license/, the --key option would look like this:

--key /external/license/iris.key

The --key option allows you to update an instance’s license without having to upgrade the container. When the option is used in a docker run or docker start command with an InterSystems IRIS image, iris-main continuously monitors the staged license key for changes (assuming it remains in its original location); if any change in the file is detected, it is copied to the current mgr/ directory and a %SYSTEM.License.Upgrade()Opens in a new tab API call is made.

See The iris-main Program for a list of iris-main options, and Running InterSystems IRIS Containers for examples of using the --key option.

Security for InterSystems IRIS Containers

When working with InterSystems IRIS images from InterSystems it is important to understand the security-related mechanisms and options, including:

• Ownership and directories

• Authentication and passwords

• Locked down InterSystems IRIS container

Ownership and Directories

The InterSystems IRIS instance in a container created from an InterSystems image is always named IRIS and is nonrootOpens in a new tab, meaning it was installed and is owned by a user account, irisowner (UID 51773), which does not have root privileges. All file system entities comprising the instance are owned by irisowner, and nothing is therefore owned by root. Operating system-based authenticationOpens in a new tab is enabled on the instance, which means that an irisowner process or client authenticated on another system can connect to the instance without authentication. Because commands issued from outside the container using docker execOpens in a new tab are executed inside the container as irisowner, you can use this command to conveniently connect to the instance without authentication. For example, to open the InterSystems TerminalOpens in a new tab for an instance in a container named iris273 without being prompted for credentials, you could use the following command:

docker exec -it iris273 iris terminal IRIS 

The installation directory (containing the mgr/ subdirectory) within the container is /usr/irissys/. The working directory (containing files such as iris-main.log) is /home/irisowner/, while the registry directory is /home/irisowner/irissys/.

For information about the installation parameters used to specify these configuration details, see Required Environment Variables. For more information on these general installation-related topics, see InterSystems IRIS InstallationOpens in a new tab in the “Installing on UNIX®, Linux, and macOS” chapter of the Installation Guide.

InterSystems provides tools that allow you to determine these configuration details for InterSystems IRIS-based images that you create, as described in InterSystems IRIS Containerization Tools.

Important:

When using the durable %SYS feature to provide a containerized InterSystems IRIS instance with persistent storage, the host file system location mounted and specified for this purpose must be writable by user 51773. (You will most likely need root privileges to effect this.)

When using durable %SYS with an InterSystems IRIS container deployed with the Pod Manager tool (podman), you must do the following:

• Issue the following command before starting the container:

  podman unshare chown 51773:51773 $INSTANCEDIR
  

  

  where $INSTANCEDIR is the host file system location that will contain the durable %SYS directory.

• If Red Hat Security-Enhanced Linux (SELinux) is active, include the --privileged=true flag when creating the container.

When using durable %SYS on Kubernetes without the InterSystems Kubernetes OperatorOpens in a new tab, you must include the following security contextOpens in a new tab setting in the pod specification:

securityContext:
  fsGroup: 51773

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.

Note:

If the irisowner user account is not defined in the /etc/passwd file on the system hosting the container, it is represented by its UID (51773) on that system.

Mirroring with InterSystems IRIS Containers

InterSystems IRIS instances deployed in containers can be configured as mirrors the same way you would configure those deployed from a kit, using the procedures described in Configuring MirroringOpens in a new tab in the High Availability Guide. However, there are a few points to bear in mind:

• The arbiterOpens in a new tab configured for the mirror (as strongly recommended by InterSystems) can be deployed from the arbiter image provided by InterSystems, which you can download using the same procedures described for the InterSystems IRIS image. (Note that this is a nonroot image, as described in Security for InterSystems IRIS Containers.) You can also use a noncontainerized InterSystems IRIS instance or an arbiter installed from a kitOpens in a new tab.

• When you deploy the InterSystems IRIS and arbiter containers, you must ensure that you publish the ports used by the mirror members, their ISCAgents, and the arbiter to communicate with each other, as described in Mirror Member Network AddressesOpens in a new tab in the High Availability Guide.

• The ISCAgent on each failover and DR async mirror member must be configured to start automatically before InterSystems IRIS starts. This is the default behavior for InterSystems IRIS images. When running an InterSystems IRIS container, you can use the following iris-main ISCAgent options:

  --ISCAgent true|false
  

  If true, the ISCAgent starts when the container starts on the on the default ISCAgent port, 2188. (This is the default behavior if the option is omitted.) If false, the ISCAgent does not start, and the --ISCAgentPort option is ignored.

  --ISCAgentPort NNNN 
  

  Specifies the port to start the ISCAgent on. (The default, if the option is omitted, is 2188.) This option can be used together with --ISCAgent true. If the value provided isn’t a valid port number (for example, if it is not an integer), or the indicated port is in use, the ISCAgent fails to start.

• Be sure to review Mirroring CommunicationOpens in a new tab, Sample Mirroring Architecture and Network ConfigurationsOpens in a new tab, and Locating the Arbiter to Optimize Mirror AvailabilityOpens in a new tab in the High Availability Guide to ensure that your deployment addresses all of the needed networking considerations.

Discovering Defaults in InterSystems Images

Default values in InterSystems containers are exposed through the standard label mechanism so that needed information can be discovered using the docker inspect command, as shown in the following example. Users familiar with InterSystems technology will recognize the typical default ports and other useful information. (For information about formatting the output of this command, see Format command and log outputOpens in a new tab in the Docker documentation.)

$ docker inspect -f {{json .Config.Labels}} intersystems/iris:2023.1.0.299.0
  "Labels": {
      "com.intersystems.adhoc-info": "",
      "com.intersystems.platform-version": ":2023.1.0.299.0",
      "com.intersystems.ports.default.arbiter": "2188",
      "com.intersystems.ports.default.license-server": "4002",
      "com.intersystems.ports.default.superserver": "1972",
      "com.intersystems.ports.default.webserver": "52773",
      "com.intersystems.ports.default.xdbc": "52773",
      "com.intersystems.product-name": "IRIS",
      "com.intersystems.product-platform": "dockerubuntux64",
      "com.intersystems.product-timestamp": "Wed May 16 2022 00:37:59 EST",
      "com.intersystems.product-timestamp.iso8601": "2022-05-16T05:37:59Z",
      "maintainer": "InterSystems Worldwide Response Center <support@intersystems.com>",
      "org.opencontainers.image.created": "2022-05-16T07:57:10Z",
      "org.opencontainers.image.documentation": "https://docs.intersystems.com/",
      "org.opencontainers.image.title": "intersystems/iris",
      "org.opencontainers.image.vendor": "InterSystems",
      "org.opencontainers.image.version": "2023.1.0.299.0"
      }

Overview of InterSystems IRIS Durable %SYS

Separation of code and data is one of the primary advantages of containerization; a running container represents "pure code" that can work with any appropriate data source. However, all applications and programs generate and maintain operating and historical data — such as configuration and language settings, user records, and log files — which must be retained beyond the life of a single container to enable upgrades. For this reason, containerization typically must address the need to persist program-related data, including application databases, on durable data storage. This requires a mechanism that identifies the data to be retained and its persistent location, and can direct the new container to it following an upgrade or a failure of the previous container.

The durable %SYS feature does this for an InterSystems IRIS container by cloning the needed instance-specific data (such as log, journal, and WIJ files and system databases such as IRISSYS) to a chosen location on the file system of the container’s host and resetting the instance to use the data in the new (cloned) location. To use durable %SYS, you must mount the chosen location as a volume within the container and identify it in an environment variable specified when the container is started. While the InterSystems IRIS instance remains containerized, its instance-specific data exists outside the container, just like the databases in which application data is stored, persisting it across container and instance restarts and making it available for upgrading the instance. (For more information on upgrading, see Upgrading InterSystems IRIS Containers.)

Contents of the Durable %SYS Directory

The durable %SYS directory, as created when a container is first started, contains a subset of the InterSystems IRIS install tree, including but not limited to:

• The configuration parameter file (CPF), which is named iris.cpf. Additional versions of the file (older versions and _LastGood_.cpf) are created as with any InterSystems IRIS instance. (Automating Configuration of InterSystems IRIS with Configuration MergeOpens in a new tab, Configuration Parameter File Reference)

• The /csp directory, containing the Web Gateway configuration and log files. (Web Gateway GuideOpens in a new tab)

  Note:

  Web Gateway containers also have a durable %SYS feature, and when one is in use (see Using the InterSystems Web Gateway Container), this directory is located on its own persistent storage.

• The file /dist/install/misc/buildver, which contains the instance’s version, for example 2023.1.0.299.0.

• The file /httpd/httpd.conf, the configuration file for the instance’s private web server. (“Supported Web ServersOpens in a new tab” in the “Supported Technologies” chapter of the online InterSystems Supported Platform document for this release)

• The /mgr directory, containing the following:

  • The IRISSYS system database, comprising the IRIS.DAT and iris.lck files and the stream directory, and the iristemp, irisaudit, iris and user directories containing the IRISTEMP, IRISAUDIT, IRIS and USER system databases. (System-Supplied Databases and Custom Items in IRISSYS)

  • The write image journaling file, IRIS.WIJ (which may be relocated to achieve file system separation). (The "Write Image Journaling and Recovery" chapter of the Data Integrity Guide)

  • The /journal directory containing journal files (which may be relocated to achieve file system separation). (The "Journaling" chapter of the Data Integrity Guide; see also Separating File Systems for Containerized InterSystems IRIS in this document)

  • The /temp directory for temporary files.

  • Log files including messages.log, journal.log, and SystemMonitor.log. Additional logs may be present initially and some are created as needed, for example backup and mirror journal logs. (Monitoring InterSystems IRIS Logs in the "Monitoring InterSystems IRIS Using the Management Portal" chapter of the Monitoring Guide.)

    Note:

    Durable %SYS activity is logged in the messages.log file; if you have any problems in using this feature, examine this log for information that may help. For information about how to read this log from outside the container, see The iris-main Program.

  • The InterSystems IRIS license key file, iris.key, either at container start if it is included in the InterSystems IRIS image or when a license is activated while the container is running. (Activating a License Key in the "Managing InterSystems IRIS Licensing" chapter of the System Administration Guide)

  • Several InterSystems IRIS system files.

• All databases defined on the instance, beyond the standard InterSystems IRIS databases listed in the first bullet above, that are not read-only. This is to ensure that databases added to the instance in a user-created image based on an InterSystems-supplied image, as described in Creating InterSystems IRIS Images, are included in the durable data. If a database directory is underneath the install directory in the container, for example if it is under /usr/irissys/mgr, it is copied to the corresponding location in the durable %SYS directory. If one or more database directories are not underneath the install directory, a new folder db is created in the install directory and they are copied there.

Locating the Durable %SYS Directory

When selecting the location in which this system-critical instance-specific information is to be stored, bear in mind the following considerations:

• The availability of appropriate backup and restore procedures ("Backup and Restore" chapter of the Data Integrity Guide).

• Any high availability mechanisms you have in place (High Availability Guide) .

• Available storage space and room for expansion (Maintaining Local Databases in the "Managing InterSystems IRIS" chapter of the System Administration Guide).

There must be at least 200 MB of space available on the specified volume for the durable %SYS directory to initialize. For various reasons, however, including operational files such as journal records and the expansion of system databases, the amount of data in the directory can increase significantly.

InterSystems recommends specifying a subdirectory of a mounted volume, rather than the top level, as the durable %SYS location. For example, if an external file system location is mounted as the volume /external in the container, /external should not be specified as the durable %SYS location, but rather a directory on /external such as /external/durable.

Important:

Because the instances in the iris and iris-lockeddown images were installed and are owned by user irisowner (UID 51773), as described in Security for InterSystems IRIS Containers, the file system location you specify for durable %SYS must be writable by irisowner. (You will probably need root privileges to effect this.) When using durable %SYS on Kubernetes without the InterSystems Kubernetes OperatorOpens in a new tab, you must include the following security contextOpens in a new tab setting in the pod specification:

securityContext:
  fsGroup: 51773

Running an InterSystems IRIS Container with Durable %SYS

To use durable %SYS, include in the docker run command the following options:

--volume /volume-path-on-host:/volume-name-in-container
--env ISC_DATA_DIRECTORY=/volume-name-in-container/durable-directory

where volume-path-on-host is the pathname of the durable storage location to be mounted by the container, volume-name-in-container is the name for the mounted volume inside the container, and durable_directory is the name of the durable %SYS directory to be created on the mounted volume. For example:

docker run --detach 
  --publish 52773:52773 
  --volume /data/dur:/dur 
  --env ISC_DATA_DIRECTORY=/dur/iconfig 
  --name iris21 intersystems/iris:2023.1.0.299.0

In this example, the durable %SYS directory would be /data/dur/iconfig outside the container, and /dur/iconfig inside the container.

When you run an InterSystems IRIS container using these options, the following occurs:

• The specified external volume is mounted.

• The InterSystems IRIS installation directory inside the container is set to read-only.

• If the durable %SYS directory specified by the ISC_DATA_DIRECTORY environment variable, iconfig/ in the preceding example, already exists and contains a /mgr subdirectory, all of the instance’s internal pointers are reset to that directory and the instance uses the data it contains. If the InterSystems IRIS version of the data does not match the version of the instance, an upgrade is assumed and the data is upgraded to the instance’s version as needed. (For information on upgrading, see Upgrading InterSystems IRIS Containers.)

• If the durable %SYS directory specified by ISC_DATA_DIRECTORY does not exist, or exists and is empty:

  • The specified durable %SYS directory is created if necessary.

  • The directories and files listed in Contents of the Durable %SYS Directory are copied from their installed locations to the durable %SYS directory (the originals remain in place).

  • All of the instance’s internal pointers are reset to the durable %SYS directory and the instance uses the data it contains.

  If for any reason the process of copying the durable %SYS data and resetting internal pointers fails, the durable %SYS directory is marked as incomplete; if you try again with the same directory, the data in it is deleted before the durable %SYS process starts.

• If the durable %SYS directory specified by the ISC_DATA_DIRECTORY environment variable already exists and contains data (file or subdirectories) but does not contain a /mgr subdirectory, no data is copied; the container does not start, and the reason (data other than durable %SYS in the directory) is logged to standard output by iris-main, as described in The iris-main Program.

In the case of the example provided, the InterSystems IRIS instance running in container iris21 is configured to use the host path /data/dur/iconfig (which is the path /dur/iconfig inside the container) as the directory for persistent storage of all the files listed in Contents of the Durable %SYS Directory. If durable %SYS data does not already exist in the host directory /data/dur/iconfig (container directory /dur/iconfig) it is copied there from the installation directory. Either way, the instance’s internal pointers are set to container directory /dur/iconfig.

See Running InterSystems IRIS Containers for various examples of launching an InterSystems IRIS container with durable %SYS.

The following illustration shows the relationship between the InterSystems IRIS installation directory and user databases within a container and on the mounted external storage to which they were cloned by durable %SYS (as specified by the options shown). Note that the three application databases outside of the install directory have been cloned to /data/dur/iconfig/db, whereas the LOCALDB database, which is within the install directory under /mgr, is cloned to the same location (/data/dur/iconfig/mgr/localdb).

Identifying the Durable %SYS Directory Location

When you want to manually verify the location of the durable %SYS directory or pass this location programmatically, you have three options, as follows:

• Open a shell inside the container, for example with docker exec -it container_name bash, and do either of the following:

  echo $ISC_DATA_DIRECTORY
  
  iris list
  

  
  Note:

  For detailed information on the iris command, see Controlling InterSystems IRIS Instances.

• Within InterSystems IRIS, call $SYSTEM.Util.InstallDirectory() or $SYSTEM.Util.GetEnviron(‘ISC_DATA_DIRECTORY’).

Ensuring that Durable %SYS is Specified and Mounted

When a container is run with the ISC_DATA_DIRECTORY environment variable, pointers are set to the durable %SYS files only if the specified volume is successfully mounted.

• If ISC_DATA_DIRECTORY is specified but the needed --volume /external_host:/durable_storage option is omitted from the docker run command, the instance fails to start and an error message is generated.

• If the --volume option is included but Docker cannot successfully mount the specified volume, it creates the external storage directory and the volume within the container; in this case, the instance data is copied to the durable %SYS directory, as described under "If the durable %SYS directory specified by ISC_DATA_DIRECTORY does not exist" in Running an InterSystems IRIS Container with Durable %SYS.

If ISC_DATA_DIRECTORY is not specified, the InterSystems IRIS instance uses the instance-specific data within the container, and therefore cannot operate as an upgrade of the previous instance.

To use durable %SYS, you must therefore ensure that all methods by which your InterSystems IRIS containers are run incorporate these two options.

Separating File Systems for Containerized InterSystems IRIS

In the interests of performance and recoverability, InterSystems recommends that you locate the primary and secondary journal directories of each InterSystems IRIS instance on two separate file systems, which should also be separate from those hosting InterSystems IRIS executables, the instance’s system databases, and the IRIS.WIJ file, with the latter optionally on a fourth file system. Following InterSystems IRIS installation, however, the primary and secondary journal directories are set to the same path, install-dir/mgr/journal, and thus may both be set to /mgr/journal in the durable %SYS directory when durable %SYS is in use.

After the container is started, you can reconfigure the external locations of the primary and secondary directories using the Management Portal or by editing the CPF (iris.cpf), as long as the volumes you relocate them to are always specified when running a new image to upgrade the InterSystems IRIS instance. You can also configure separate file systems using a configuration merge file, as described in Automating Configuration of InterSystems IRIS with Configuration MergeOpens in a new tab.

For more information about separation of file systems for InterSystems IRIS, see File System Separation.

Required Environment Variables

There are a number of installation parameters available for use in configuring unattended installation of InterSystems IRIS instances on UNIX and Linux; their use is described and they are listed in Unattended InterSystems IRIS Installation in the Installation Guide. If you install InterSystems IRIS instance from a kit in your Dockerfile, rather than using an InterSystems image as a base as described in Creating InterSystems IRIS Images, the installation parameters that are required as environment variables in the container runtime environment must also be built into the image; without them, container creation from the image will fail. These variables are included in all images from InterSystems and are shown, with the values set by InterSystems, in the following table:

SYS.Container API

In building its InterSystems IRIS images, InterSystems uses the SYS.Container API to bring the installed InterSystems IRIS instance into a state in which it can safely be serialized into a container image. The class contains several methods that can be used individually, but one of these, SYS.Container.QuiesceForBundling()Opens in a new tab, calls all of the needed methods in a single operation, and is used by InterSystems in creating its images. Using this approach is the recommended best practice, because error-checking across the Linux shell/ObjectScript boundary is difficult and involves the risk of silent errors from InterSystems IRIS; the fewer calls you make, the lower this risk is.

The SYS.Container code is included and fully visible in any InterSystems IRIS instance installed on Linux platforms; see the class reference for documentation. The methods include the following:

• SYS.Container.QuiesceForBundling()Opens in a new tab

  Calls all of the ObjectScript code necessary to get InterSystems IRIS into a state in which it can safely be serialized into a container image.

• SYS.Container.ChangePassword()Opens in a new tab

  Changes the password of all enabled user accounts with at least one role; called by the iris-main --password-file option and the password change script, as described in Authentication and Passwords.

• SYS.Container.ChangeGatewayMgrPassword()Opens in a new tab

  Changes the Web Gateway management password (see Overview of the Web Gateway Management PagesOpens in a new tab in the Web Gateway Guide); called by the iris-main --password-file option and the password change script, as described in Authentication and Passwords.

• SYS.Container.ForcePasswordChange()Opens in a new tab

  Sets Change password on next login on user enabled accounts with at least one role (see User Account Properties).

• SYS.Container.KillPassword()Opens in a new tab

  Disables password-based login for a specified user; other forms of authentication (see Authentication: Establishing IdentityOpens in a new tab) remain enabled.

• SYS.Container.EnableOSAuthentication()Opens in a new tab

  Enables OS-based authentication for the instance (see About Operating-System–Based AuthenticationOpens in a new tab).

• SYS.Container.SetNeverExpires()Opens in a new tab

  Sets Account Never Expires for the specified user account; without this, user accounts will expire in images that are more than 90 days old (see Properties of Users).

• SYS.Container.PreventFailoverMessage()Opens in a new tab

  Prevents journal rollover messages from the instance in a newly started container.

• SYS.Container.PreventJournalRolloverMessage()Opens in a new tab

  Prevents the instance from posting a warning because the name of the host it is running on is not the same as the hostname stored from the last time it was running.

• SYS.Container.SetMonitorStateOK()Opens in a new tab

  Clears level 1 and level 2 alerts from the System Monitor, generating an error if a level 3 is present (see the “Using System Monitor” chapter of the Monitoring Guide).

A common approach is to include these methods in a Dockerfile based on an InterSystems IRIS image from InterSystems (as described in Creating InterSystems IRIS Images) by calling them through the iris terminal commandOpens in a new tab at instance startup, for example:

RUN iris start $ISC_PACKAGE_INSTANCENAME \
    && iris terminal $ISC_PACKAGE_INSTANCENAME -U %SYS "##class(SYS.Container).PreventJournalRolloverMessage()" 
    && iris terminal $ISC_PACKAGE_INSTANCENAME -U %SYS "##class(SYS.Container).SetMonitorStateOK()" 
    && iris terminal $ISC_PACKAGE_INSTANCENAME -U %SYS "##class(SYS.Container).QuiesceForBundling()"
    && iris terminal $ISC_PACKAGE_INSTANCENAME quietly

Running an InterSystems IRIS Container: docker run Examples

The following are examples of docker run commands for launching InterSystems IRIS containers using iris-main options.

• As described in License Keys for InterSystems IRIS Containers, the required InterSystems IRIS license key must be brought into the container so that the instance can operate. In the example that follows

  • Publishes the instance’s web server port to port 9092 on the host.

  • Includes the needed options for durable %SYS (see Ensuring that Durable %SYS is Specified and Mounted).

  • Uses the iris-main -key option, in which the license key is staged in the key/ directory on the volume mounted for the durable %SYS directory — that is, /data/durable/key/ on the external storage, /dur/key/ inside the container — and is copied to the mgr/ directory within the durable %SYS directory ( /data/durable/iconfig/mgr/ on the external storage, /dur/iconfig/mgr/ in the container) before the InterSystems IRIS instance is started. Because it is in the mgr/ directory, it is automatically activated when the instance starts.

  docker run --name iris11 --detach --publish 9092:52773 --volume /data/durable:/dur 
    --env ISC_DATA_DIRECTORY=/dur/iris_conf.d
    intersystems/iris:2023.1.0.299.0 --key /dur/key/iris.key
  

  

• This example adds a configuration merge file staged on the durable data volume, containing settings to be merged into the InterSystems IRIS instance’s CPF (see Automated Deployment of InterSystems IRIS Containers) before it is first started. You might use this, for example, to reconfigure the instance’s primary and alternate journal directories ([Journal]/CurrentDirectory and AlternateDirectory in the CPF), which by default are the same directory within the durable %SYS tree, to be on separate file systems, as described in Separating File Systems for Containerized InterSystems IRIS

  docker run --name iris17 --detach --publish 9092:52773h --volume /data/durable:/dur 
    --env ISC_DATA_DIRECTORY=/dur/iris_conf.d
    --env ISC_CPF_MERGE_FILE=/dur/merge/merge.cpf intersystems/iris:2023.1.0.299.0 
    --key /dur/key/iris.key 
  

  

  The staging directories, in this case both located on the volume mounted for durable %SYS, should be the same, or contain the same licenses.

• Once container iris17 and the instance inside it are running, you can start another InterSystems IRIS container with a different license to be served to the instance inside it, using the license server configured on iris17:4002 by the first command, as well as a different configuration merge file, as follows:

  docker run --name iris99 --detach --publish 9092:52773 --volume /data/durable:/dur
    --env ISC_DATA_DIRECTORY=/dur/iris2_conf.d 
    --env ISC_CPF_MERGE_FILE=/dur/merge2/merge99.cpf intersystems/iris:2023.1.0.299.0 
    --key /dur/key/iri99s.key
  

  

Running an InterSystems IRIS Container: Script Example

The following script was written to quickly create and start an InterSystems IRIS container for testing purposes. The script incorporates the iris-main --key option to copy in the license key, as described in License Keys for InterSystems IRIS Containers.

#!/bin/bash
# script for quick demo and quick InterSystems IRIS image testing

# Definitions to toggle_________________________________________
container_image="intersystems/iris-arm64:2023.1.0.299.0"

# the docker run command
docker run -d 
# expose superserver, webserver, and JDBC Gateway ports
  -p 9091:1972 
  -p 9092:52773 
  -p 9093:52773 
  -v /data/durable:/dur 
  -h iris 
  --name iris 
# enable allocation of huge pages
  --cap-add IPC_LOCK 
  --env ISC_DATA_DIRECTORY=/dur/iris_conf.d
  --env ISC_CPF_MERGE_FILE=/dur/merge/merge.cpf
  $container_image 
  --key /dur/key/iris.key 

Running an InterSystems IRIS Container: Docker Compose Example

Docker Compose, a tool for defining and running multicontainer Docker applications, offers an alternative to command-line interaction with Docker. To use Compose, you create a docker-compose.yml containing specifications for the containers you want to create, start, and manage, then use the docker-compose command. For more information, start with Overview of Docker ComposeOpens in a new tab in the Docker documentation.

The following is an example of a compose.yml file. Like the preceding script, it incorporates only elements discussed in this document.

version: '3.2'

services:
  iris:
    image: intersystems/iris:2023.1.0.299.0
    command:  --key /dur/key/iris.key
    hostname: iris

    ports:
    # 1972 is the superserver default port
    - "9091:1972"
    # 52773 is the webserver/management portal port
    - "9092:52773"
    # 52773 is the JDBC Gateway port
    - "9093:52773"
    volumes:
    - /data/durable:/dur

    environment:
    - ISC_DATA_DIRECTORY=/dur/iris_conf.d
    - ISC_CPF_MERGE_FILE=/dur/merge/merge.cpf

Upgrading InterSystems IRIS Containers with Durable %SYS

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, 9092:52773, 9093:52773 
  --volume /data/durable:/dur --env ISC_DATA_DIRECTORY=/dur/iconfig 
  intersystems/iris:<version_number> --key /dur/key/iris.key

Upgrading When Manual Startup is Required

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 in the “Backup and Restore” chapter of the Data Integrity Guide 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.

InterSystems Web Gateway Images

There are three types of webgateway images available from InterSystems, each of which provides a web server component for containerized deployments of InterSystems IRIS-based applications:

• The webgateway image contains the following components, installed by root in the indicated locations within the container:

  • An InterSystems Web Gateway in /opt/webgateway.

  • An Apache web server in /etc/apache2.

• The webgateway-nginx image contains the following components, installed by root:

  • An InterSystems Web Gateway in /opt/webgateway.

  • An Nginx web server in /opt/nginx.

• The webgateway-lockeddown image, designed to meet the strictest security requirements, contains the following nonroot components installed, owned, and run by irisowner (UID 51773) :

  • An InterSystems Web Gateway installed in /home/irisowner/webgateway with locked-down security.

  • An Apache web server installed in /home/irisowner/apache and configured to use port 52773 instead of the standard port 80.

  Note:

  For details about nonroot installation and locked-down security, see Security for InterSystems IRIS Containers.

Configuring the Web Gateway

As described in Configuring the Default Parameters for the Web GatewayOpens in a new tab in the Web Gateway Guide, the Web Gateway is configured using the Web Gateway management pages, but the configuration is contained in the CSP.ini file (much as an InterSystems IRIS instance’s configuration is contained in the iris.cpf file). As installed, the Web Gateway is configured to communicate with the local InterSystems IRIS instance.

For testing purposes, all three webgateway images contain basic versions of the CSP.ini file (which contains the Web Gateway configuration) and the CSP.conf file (which contains the Web Gateway’s Apache or Nginx-specific configuration), in the directories indicated in the preceding list. However, you can provide your own version of one or both files to overwrite these.

All three types of container can optionally be run with a version of the durable %SYS feature, which creates a durable data directory called webgateway within the container in which the Web Gateway’s configuration is stored, enabling you to upgrade the container without losing the existing configurations. If you use this feature, the CSP.ini and CSP.conf files (default or user-provided) are copied to that directory, as is the CSP.log log file.

There are multiple ways to prepare your initial version of the configuration file. For example, you might modify a file from an existing or previous Web Gateway deployment and use that for one or more Web Gateway containers, or perhaps start in one container with either your own file or the basic default version provided, use the management pages to modify the configuration as needed, then copy the updated file and use it with additional containers.

Synchronized Reconfiguration of Multiple Web Gateway Containers

When you deploy multiple Web Gateway containers as part of the same cluster (as in a web server tier), you will likely need a method for simultaneously updating their configurations, especially their server access configurations. The CSP.ini merge feature provides a convenient means of doing this. If you provide your own CSP.ini file at container creation, staged on a mounted external volume as described in Options for Running Web Gateway Containers, it is copied once to either the container’s file system, or to the durable %SYS directory if the latter exists. If the staged file remains in its original location, however, updates to the file are automatically merged to the instance’s active CSP.ini file (in either location), along with the setting [SYSTEM]/RELOAD=1Opens in a new tab, which causes the configuration to be reloaded by the Web Gateway within a minute. Therefore, if you deploy multiple Web Gateway containers by mounting the same staged CSP.ini file on the same external volume for all of them, you can reconfigure them all identically and simultaneously by updating the staged file.

When using this merge update approach, whether for a single Web Gateway container or multiple containers, it is important to takes steps to avoid changing the instances’ CSP.ini files by other means (such as through the Web Gateway management pages) or, if you do make such changes, do one of the following:

• Remove fields from the staged CSP.ini file that you have changed by other means, possibly by deleting everything other than the fields you want to update.

• Apply updates you have made by other means to the staged file. For example, you might change the file using the management pages, then copy the modified file to the staging location, overwriting the original staged file. If you are using the staged file for multiple containers, this would allow you to make the changes you want on one instance and then apply them to the rest through a merge update.

Web Gateway Security

The predefined CSPSystem account on an InterSystems IRIS instance is used for communication between an InterSystems IRIS instance and the local InterSystems Web Gateway instance installed with it, and by default is used for access to the local Web Gateway’s configuration through its management pages. For effective security, you must change the default password for this account (along with the other predefined accounts) on both an InterSystems IRIS instance and its local Web Gateway instance either as part of deployment or immediately after; Authentication and Passwords provides details on this topic and instructions for making these changes in an InterSystems IRIS container. In the case of a Web Gateway container, you must independently secure management access; the steps required to do this differ depending on whether you are using the provided basic CSP.ini configuration file or replacing it with your own, as follows:

• The default CSP.ini file provided in the container does not require authentication for management access, which is not secure. If you start with this file and plan to modify the basic Web Gateway configuration it provides through the management pages, do the following immediately after deployment::

  1. In your browser, load the Web Gateway’s management pages URL, which is http://container-host:host-port/csp/bin/Systems/Module.cxw, where host-port is the host port that was published for container port 80 when the container was created.

  2. Select Default Parameters in the menu on the left and, in the Security section of the page, enter a username and password. Once you save your changes, those credentials will be required for access to the management pages following the end of your current session.

• If you provide your own CSP.ini file, as described earlier in this section:

  1. Prior to deployment, verify that the password specified for the management access account, if any, is encrypted, not in plain text, so that the password is not vulnerable on disk or on the network.

  2. Immediately after deployment, access the Security section of the Web Gateway’s management pages, as described in the previous item, and verify that if CSPSystem (or any other predefined accountOpens in a new tab) is specified as the management access account, the password is not SYS; if it is, change it. You can also change the access credentials to any username and password you choose.

When securing connections between a containerized Web Gateway and InterSystems IRIS instances with TLS (as described in Configuring Server AccessOpens in a new tab and “Overriding the Library Path If You Use SSL/TLSOpens in a new tab” in the Web Gateway Guide and Configuring the Web Gateway to Connect to InterSystems IRIS Using TLSOpens in a new tab in the TLS Guide) or using SSL mode to secure the Apache web server, the best practice for providing a certificate is to generate a passwordless server key and mount both the key and the certificate as Docker secretsOpens in a new tab (or Kubernetes secretsOpens in a new tab if applicable). When you need to update the certificate, you can simply update the secrets. This practice avoids having to manually provide a server key password, which compromises resiliency, or recording the password so it can be automatically retrieved, which compromises security.

Options for Running Web Gateway Containers

The only required option when creating and starting a webgateway container is publishing container ports 80 (or 52773 if webgateway-lockeddown) and 443 to host ports so that other entities can contact the Web Gateway and the web server, as in the following commands:

docker run -d --publish 80:80 --publish 443:443 
  containers.intersystems.com/intersystems/webgateway:2023.1.0.299.0

docker run -d --publish 52773:52773 --publish 443:443 
  containers.intersystems.com/intersystems/webgateway-lockeddown:2023.1.0.299.0

The following additional options are optional:

• Durable data directory — To create a durable data directory called webgateway within the container, in which the Web Gateway’s configuration is stored, use the --volume option to mount a persistent data volume and the ISC_DATA_DIRECTORY environment variable to specify a location on it for the directory. For example, the following command would create a durable data directory at /dur/webgateway inside the container and /nethome/rrodriguez/dur/webgateway on the host’s file system.

  docker run -d --name wg11 --publish 80:80 --publish 443:443
    --volume /nethome/rrodriguez/dur:/dur --env ISC_DATA_DIRECTORY=/dur 
     containers.intersystems.com/intersystems/webgateway:2023.1.0.299.0
  

  

  This is equivalent to the procedure for enabling the durable %SYS feature for InterSystems IRIS containers; for detailed information about using these options and durable %SYS generally, see Durable %SYS for Persistent Instance Data.

  Important:

  Because the webgateway-lockeddown image contains a Web Gateway instance and web server installed and owned by user irisowner (UID 51773), the host file system location you specify for the durable data directory of a locked down container must be writable by irisowner. (You will most likely need root privileges to effect this.)

  When you run a webgateway container with the durable data options, the following occurs:

  • The specified external volume is mounted.

  • If the webgateway directory does not exist in the location specified by ISC_DATA_DIRECTORY, it is created and the configuration files are copied there for use by the Web Gateway, as follows:

    • Configuration files you provide are copied to the webgateway directory, with links to their default locations in the container.

    • Configuration files you do not provide are copied from the default locations within the container, with links to those locations.

  • If the webgateway directory already exists in the location specified by ISC_DATA_DIRECTORY, it is assumed to be the data directory for a previous webgateway container, and

    • If it contains the expected Web Gateway configuration files, these are linked to their locations in the container and are used by the Web Gateway; options specifying user-provided configuration files (as described below) are ignored.

      Important:

      Because you cannot provide your own configuration files (as described below) when deploying a webgateway container using an existing durable webgateway directory, you cannot upgrade and reconfigure a containerized Web Gateway in the same operation. Instead, start by deploying a new version of the container using the previous container’s durable webgateway directory, then reconfigure the Web Gateway as needed.

    • If one or more of the expected Web Gateway configuration files are not present, the webgateway is assumed to be corrupted; an error is logged and the container fails to start.

    Important:

    When upgrading a webgateway container that uses a durable data directory to version 2021.2 or later using a webgateway-lockeddown image, you must make the existing durable directory writable by user irisowner.

  The default, if you do not use the ISC_DATA_DIRECTORY variable to specify a location on writeable persistent storage accessible to the Web Gateway within the container, is to not create a durable data directory and maintain the configuration files in their default locations (as previously described).

• User-defined configuration files — To provide your own CSP.ini file, use the --volume option to mount a persistent data volume (Separate from the durable %SYS volume, if in use), stage the file on that volume, and use the ISC_CSP_INI_FILE environment variable to indicate its location. If you also create a durable webgateway directory, as described in the preceding, the file is copied to that directory and linked to its original location within the container; if not, it is copied to the original location, overwriting the default file.

  Important:

  If you want to use the merge update approach, as described in Configuring the Web Gateway, the staged CSP.ini file must remain in place and accessible to the container.

  To supply your own CSP.conf file, do the same and use the ISC_CSP_CONF_FILE environment variable to specify its location. For example, to create a durable webgateway directory and provide your own CSP.ini and CSP.conf files to be used for the Web Gateway’s configuration, you would use a command like the following:

  docker run -d --name wg11 --publish 80:80 --publish 443:443
    --volume /nethome/rrodriguez/dur:/dur --env ISC_DATA_DIRECTORY=/dur 
    --volume /nethome/rrodriguez/config:/config --env ISC_CSP_INI_FILE=/config/CSP.ini 
    --env ISC_CSP_CONF_FILE=/config/CSP.conf 
    containers.intersystems.com/intersystems/webgateway:2023.1.0.299.0
  

  

  The default, if one of these variable is not specified, is to use the basic default file located within the container.

• To enable the Apache web server’s SSL module, add the --ssl entrypoint option (following the image specification). The default, if the option is omitted, is not to enable the Apache SSL module.

• To identify the Web Gateway’s server to Apache, use the --server server-name entrypoint option. The default, if the option is omitted, is to use the container’s ID (unless the Docker --hostname option is included, in which case the value provided is used).

The following is an example of a docker run command using all the options described:

docker run -d --name wg11 --publish 80:80 
  --volume /nethome/rrodriguez/dur:/dur --env ISC_DATA_DIRECTORY=/dur 
  --env ISC_CSP_INI_FILE=/dur/CSP.ini --env ISC_CSP_CONF_FILE=/dur/CSP.conf 
  containers.intersystems.com/intersystems/webgateway:2023.1.0.299.0
  --ssl --server webgateway11