Running InterSystems IRIS Containers

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

  • Publishes the instance’s 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.

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

# the docker run command
docker run -d 
  --name iris 
  --hostname iris 
# expose 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 

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:latest-em
    command:  --key /dur/key/iris.key
    hostname: iris
    ports:
    # the 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

Options for Running Web Gateway Containers

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