Running InterSystems Products in Containers

Container images from InterSystems comply with the Open Container Initiative (OCIOpens in a new tab) specification and are therefore supported on any OCI-compliant runtime engine on Linux-based operating systems, both on premises and in public clouds.

Install the container runtime engine(s) on which you intend to deploy InterSystems containers, such as Docker or Podman, on your servers.

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:latest-em
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.2.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

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:latest-em
  "Labels": {
      "com.intersystems.adhoc-info": "",
      "com.intersystems.platform-version": ":2023.2.0.299.0",
      "com.intersystems.ports.default.arbiter": "2188",
      "com.intersystems.ports.default.license-server": "4002",
      "com.intersystems.ports.default.superserver": "1972",
      "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": "2023-08-16T05:37:59Z",
      "maintainer": "InterSystems Worldwide Response Center <support@intersystems.com>",
      "org.opencontainers.image.created": "2023-08-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.2.0.299.0"
      }

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 Managing InterSystems IRIS Licensing.

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.

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 nonroot, 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 authentication 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 Install on UNIX®, Linux, and macOS.

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.

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 Mirroring. However, there are a few points to bear in mind:

• The arbiter 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 kit.

• 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 Addresses.

• 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 Communication, Sample Mirroring Architecture and Network Configurations, and Locating the Arbiter to Optimize Mirror Availability to ensure that your deployment addresses all of the needed networking considerations.

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

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 Merge, Configuration Parameter File Reference)

• The /csp directory, containing the Web Gateway configuration and log files. (Web Gateway Guide)

  Note:

  Web Gateway containers have a similar durable storage feature, and when this is in use (see Options for Running Web Gateway Containers) the directory is located on its own persistent storage.

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

• The file /httpd/httpd.conf, the configuration file for the instance web server. (See Supported Web Servers)

• 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). (Write Image Journaling and Recovery)

  • The /journal directory containing journal files (which may be relocated to achieve file system separation). (See Journaling; see also Separating File Systems for Containerized InterSystems IRIS)

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

    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. For information about accessing the Management Portal of a containerized InterSystems IRIS instance, see Web Access Using the Web Gateway Container.

  • 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)

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

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

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

• Available storage space and room for expansion (Maintaining Local Databases).

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 first be made writable by irisowner, for example with this command:

chown 51773:51773 root-of-durable-%SYS-directory

(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

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 
  --volume /data/dur:/dur 
  --env ISC_DATA_DIRECTORY=/dur/iconfig 
  --name iris21 intersystems/iris:latest-em

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

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

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.

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.

You can configure separate file systems in deployment using a configuration merge file, as described in Automating Configuration of InterSystems IRIS with Configuration Merge. After the container is started, you can reconfigure the external locations of the primary and secondary directories using the Management Portal (see the following section) 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.

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

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

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

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). The Web Gateway is installed with a minimal default version of the CSP.ini file containing some basic settings. In Web Gateway containers only, the CSP.conf file, which configures the web server to interact with the Web Gateway, is added to the web server’s configuration. For more information about the contents of the CSP.ini file, see Web Gateway Configuration File (CSP.ini) Parameter Reference; for information about the contents of the CSP.conf files provided in Web Gateway containers, see Recommended Option: Apache API Module without NSD and Using the NSD with Nginx.

All three webgateway images contain minimal default versions of both the CSP.ini file and an Apache or Nginx-specific CSP.conf file (in the appropriate directory as indicated in the preceding list). However, you can provide your own version of one or both files to overwrite these. There are multiple ways to prepare your initial version of the CSP.ini 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. The Web Gateway Guide provides comprehensive information on Web Gateway configuration.

A Web Gateway 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 (see Options for Running Web Gateway Containers). If you use this option, the CSP.ini and CSP.conf files (default or user-provided) are copied to that directory, as is the CSP.log log file; this enables you to upgrade the container without losing the existing configuration, and to simultaneously update multiple Web Gateway configurations, as described in the following section.

In the case of a dedicated Web Gateway container, the Web Gateway’s configuration is relatively simple, including as it does a single server access profile for the InterSystems IRIS instance it is dedicated to and application access profiles for only the applications that instance is serving. Therefore reconfiguring a dedicated Web Gateway can be as simple as accessing its management pages and making the needed changes.

However, when you deploy multiple Web Gateway containers as part of the same cluster, as in a web server tier and for shared Management Portal access, you will likely need a method for simultaneously updating their configurations, in particular their server access profiles and application access profiles, for example when you add an InterSystems IRIS node or change an application path. 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 the durable data directory if it exists. Following that, if the staged file remains in its original location and accessible to the Web Gateway containers, updates to the file are automatically merged to each Web Gateway instance’s active CSP.ini file (in either location), along with the setting [SYSTEM]/RELOAD=1, 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. This approach works equally well for reconfiguring a dedicated Web Gateway, a single Web Gateway distributing application connections to multiple InterSystems IRIS containers, or a shared Web Gateway for management portal access.

When using this merge update approach, whatever the number of Web Gateway containers involved, 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 test the changes you want to make on one instance and then apply them to the rest through a merge update.

Externally staging your own CSP.conf file allows you to keep the web servers in multiple Web Gateway contains updated in the same fashion as described for CSP.ini, above. As long as the file remains in its original staged location and accessible to the Web Gateway containers, it is monitored by each Web Gateway container for changes, and when these are detected it is recopied to the appropriate directory and the web server reloads the configuration and restarts. This is especially helpful when you update the Web Gateway server access profiles in the staged CSP.ini and need to update the application paths configured on the web servers accordingly.

Securing a Web Gateway instance involves two primary tasks:

• Securing the Web Gateway’s connections to the InterSystems IRIS instances configured in its server access profiles, which entails, at a minimum, requiring authentication to InterSystems IRIS using an existing user account on the target instance. However, InterSystems strongly recommends adding TLS encryption. This topic is covered in detail in Protecting Web Gateway Connections to InterSystems IRIS and Configuring the Web Gateway to Connect to InterSystems IRIS Using TLS.

  Note:

  InterSystems also strongly recommends securing connections between web clients and the web server with TLS.

• Securing access to the Web Gateway’s management pages, which involves requiring authentication to the Web Gateway, as well as limiting the hosts from which the management pages can be accessed. For information on this topic, see Overview of the Web Gateway Management Pages and “Security” in Configuring the Default Parameters for the Web Gateway.

In the default CSP.ini in the Web Gateway container (and by default in locally installed Web Gateways), the CSPSystem predefined user account is used for both purposes. You can, however, use any credentials you want for either purpose. When securing connections to InterSystems IRIS instances, the credentials you configure in each server access profile must be valid on that particular instance; otherwise there are no restrictions on either set of credentials, and using a purpose-made account rather than CSPSystem allows you to more closely restrict information about the credentials.

When deploying a clustered configuration involving multiple Web Gateways interacting with multiple InterSystems IRIS instances, as discussed in Synchronized Reconfiguration of Multiple Web Gateway Containers, using one set of credentials for all connections to InterSystems IRIS and another set for management access to all Web Gateways is more convenient (although using different sets enhances security by reducing credentials reuse). A reasonably convenient and (if other precautions are followed) reasonably secure approach to implementing this is as follows:

• Deploy the InterSystems IRIS containers using configuration merge [Actions] parameters (as described in Create, Modify and Delete Security Objects in Automating Configuration of InterSystems IRIS with Configuration Merge) to create an account specifically for Web Gateway authentication, with the password encrypted using the PasswordHash parameter). Stage the merge file on a mounted external volume, as required for continuous monitoring and merging.

• Deploy the Web Gateway containers with a custom CSP.ini file that specifies:

  • In the server access profiles, the Web Gateway access credentials created during InterSystems IRIS deployment.

  • A different set of credentials for management pages access.

  • A restricted set of IP addresses from which the management pages can be accessed.

  Stage the CSP.ini file on a mounted external volumes, as required for continuous monitoring and merging.

Continuous monitoring and merging of the CPF merge and CSP.ini files enables you to use the CSP.ini merge feature for later synchronized reconfiguration of the Web Gateway containers, including the security best practice of regular password changes for both the server access credentials (in both the InterSystems IRIS containers and Web Gateway containers) and the Web Gateway management credentials, or even regularly creating a new account on the InterSystems IRIS instances and updating the CSP.ini accordingly.

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. The example shown below does the following:

  • Publishes the instance’s default superserver port (1972) 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:1972
    --volume /data/durable:/dur 
    --env ISC_DATA_DIRECTORY=/dur/iris_conf.d
    intersystems/iris:latest-em --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:1972 
    --volume /data/durable:/dur 
    --env ISC_DATA_DIRECTORY=/dur/iris_conf.d
    --env ISC_CPF_MERGE_FILE=/dur/merge/merge.cpf intersystems/iris:latest-em 
    --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.

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:latest-em"

# the docker run command
docker run -d 
  --name iris 
  --hostname iris 
# expose default superserver port 
  -p 9091:1972 
# mount durable %SYS volume
  -v /data/durable:/dur 
# specify durable %SYS directory and CPF merge file
  --env ISC_DATA_DIRECTORY=/dur/iris_conf.d
  --env ISC_CPF_MERGE_FILE=/dur/merge/merge.cpf
# enable allocation of huge pages
  --cap-add IPC_LOCK 
  $container_image 
  --key /dur/key/iris.key 

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:latest-em
    command:  --key /dur/key/iris.key
    hostname: iris
    ports:
    # the default superserver port
    - "9091:1972"
    volumes:
    # the durable %SYS volume
    - /data/durable:/dur
    environment:
    # the durable %SYS directory
    - ISC_DATA_DIRECTORY=/dur/iris_conf.d
    # the CPF merge file
    - ISC_CPF_MERGE_FILE=/dur/merge/merge.cpf

In production, the recommended method for deploying multicontainer InterSystems IRIS clusters including multiple Web Gateway containers is the InterSystems Kubernetes Operator (IKO), described in Automated Deployment of InterSystems IRIS Containers. Version 3.6 of the IKO deploys dedicated Web Gateway containers for Management Portal access (the many-to-many approach) by including one as a sidecar container in each InterSystems IRIS pod; for more information, see Using the InterSystems Kubernetes OperatorOpens in a new tab.

For development and testing purposes, there are three basic methods for deploying InterSystems IRIS containers together with Web Gateway containers, as follows:

• Docker Compose and other scripting tools

• Kubernetes

• A user-created InterSystems IRIS image containing a Web Gateway instance and a web server in addition to the InterSystems IRIS instance. (For a general discussion of user-created InterSystems IRIS images, see Creating InterSystems IRIS Images.)

You can find examples of these methods, including all the needed files and some useful scripts, at https://github.com/intersystems-community/webgateway-examples/tree/masterOpens in a new tab. The remainder of this section discusses only the options available when running Web Gateway containers on the command line.

The only required option when creating and starting a Web Gateway container is publishing container ports 80 and 443 to host ports so that other entities can contact the Web Gateway and the web server, as in the following command:

docker run -d --publish 8080:80 --publish 4443:443 
  containers.intersystems.com/intersystems/webgateway:latest-em

The following are optional:

• Durable data directory — To create a durable data directory called webgateway within the container, in which the Web Gateway’s configuration files are stored, as discussed in Configuring the Web Gateway, 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 at/nethome/user21/dur/webgateway on the host’s file system.

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

  

  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 option, 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 data directory volume specified by ISC_DATA_DIRECTORY (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/user21/dur:/dur --env ISC_DATA_DIRECTORY=/dur 
    --volume /nethome/user21/config:/config --env ISC_CSP_INI_FILE=/config/CSP.ini 
    --env ISC_CSP_CONF_FILE=/config/CSP.conf 
    containers.intersystems.com/intersystems/webgateway:latest-em
  

  

  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 --publish 443:443
  --volume /nethome/user21/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:latest-em
  --ssl --server webgateway11

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

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 Pages); 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 Identity) remain enabled.

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

  Enables OS-based authentication for the instance (see About Operating-System–Based Authentication).

• 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 Using System Monitor.

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 command 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