docs.intersystems.com
InterSystems IRIS Data Platform 2019.2

Running InterSystems Products in Containers
InterSystems: The power behind what matters   
Search:  


This article explains the benefits of deploying software using Docker containers and provides the information you need to deploy InterSystems IRIS™ and InterSystems IRIS-based applications in Docker containers, using the Docker images provided by InterSystems. The article covers the following topics:
For an introduction to this topic, including a brief hands-on experience, see First Look: InterSystems IRIS in Docker Containers.
You can get a Docker container image for InterSystems IRIS Community Edition, which comes with a free temporary license, from the Docker Store; see Downloading the InterSystems IRIS Docker Image for details.
Why Containers?
Containers package applications into platform-independent, fully portable runtime solutions, with all dependencies satisfied and isolated, and thereby bring the following benefits:
These advantages make containers a natural building block for applications, promoting application delivery and deployment approaches that are simpler, faster, more repeatable, and more robust.
For an introduction to containers and container images from an InterSystems product manager, see What is a Container? and What is a Container Image? on InterSystems Developer Community.
Docker containers, specifically, are ubiquitous; they can be found in public and private clouds and are supported on virtual machines (VMs) and bare metal. Docker has penetrated to the extent that all major public cloud "infrastructure as a service" (IaaS) providers support specific container services for the benefit of organizations reducing system administration costs by using Docker containers and letting the cloud provider handle the infrastructure.
InterSystems has been supporting InterSystems IRIS™ in Docker containers for some time and is committed to enabling its customers to take advantage of this innovative technology.
For technical information and to learn about Docker technology step-by-step from the beginning, please see the Docker documentation site.
InterSystems IRIS in Docker Containers
Because a Docker container packages only the elements needed to run a containerized application and executes the application natively, it provides standard, well-understood application configuration, behavior, and access. If you are experienced with InterSystems IRIS running on Linux, it doesn’t matter what physical, virtual, or cloud system and distribution your Linux-based InterSystems IRIS container is running on; you interact with it in the same way regardless, just as you would with traditional InterSystems IRIS instances running on different Linux systems.
The following describes different aspects of how InterSystems IRIS uses containers.
Container Basics
This section covers the important basic elements of creating and using Docker containers.
Container Contents
In essence, a Docker container runs a single primary process, which can spawn child processes; anything that can be managed by a single blocking process (one that waits until its work is complete) can be packaged and run in a container.
A containerized application, while remaining wholly within the container, does not run fully on the operating system (OS) on which the container is running, nor does the container hold an entire operating system for the application to run on. Instead, an application in a Docker container runs natively on the kernel of the host system, while the container provides only the elements needed to run it and make it accessible to the required connections, services, and interfaces — a runtime environment (including file system), the code, libraries, environment variables, and configuration files.
Because it packages only these elements and executes the application natively, a Docker container is both very efficient (running as a discrete, manageable operating system process that takes no more memory than any other executable) and fully portable (remaining completely isolated from the host environment by default, accessing local files and ports only if configured to do so), while at the same time providing standard, well-understood application configuration, behavior, and access.
The isolation of the application from the host environment is a very important element of containerization, with many significant implications. Perhaps most important of these is the fact that unless specifically configured to do so, a containerized application does not write persistent data, because whatever it writes inside the container is lost when the container is removed and replaced by a new container. Because data persistence is usually a requirement for applications, arranging for data to be stored outside of the container and made available to other and future containers is an important aspect of containerized application deployment.
The Container Image
A container image is the executable package, while a container is a runtime instance of an image — that is, what the image becomes in memory when actually executed. In this sense an image and a container are like any other software that exists in executable form; the image is the executable and the container is the running software that results from executing the image.
A Docker image is defined in a Dockerfile, which begins with a base image providing the runtime environment for whatever is to be executed in the container. For example, InterSystems uses Ubuntu 18.04 LTS as a base for its InterSystems IRIS images, so the InterSystems IRIS instance in a container created from an InterSystems image is running in an Ubuntu 18.04 LTS environment. Next come specifications for everything needed to prepare for execution of the application — for example, copying or downloading files, setting environment variables, and installing the application. The final step is to define the launch of the application.
The image is created by issuing a docker build command specifying the Dockerfile’s location. The resulting image is placed in the Docker image registry of the local host, from which it can be copied to other Docker image registries.
Running a Container
To execute a container image and create the container — that is, the image instance in memory and the kernel process that runs it — you must execute three separate Docker commands, as follows:
  1. docker pull — Downloads the image from the repository.
  2. docker create — Defines the container instance and its parameters.
  3. docker start — Starts (launches) the container.
For convenience, however, the docker run command combines three separate Docker commands, which it executes in sequence, and is the typical means of creating and starting a container.
The docker run command has a number of options, and it is important to remember that the command that creates the container instance defines its characteristics for its operational lifetime; while a running container can be stopped and then restarted (not a typical practice in production environments), the aspects of its execution determined by the docker run command cannot be changed. For instance, a storage location can be mounted as a volume within the container with an option in the docker run command (for example, --volume /home/storage:/storage3), but the volumes mounted in this fashion in the command are fixed for that instantiation of the image; they cannot be modified or added to.
When a containerized application is modified — for example, it is upgraded, or components are added — the existing container is removed, and a new container is created and started by instantiating a different image with the docker run command. The new container itself has no association with the previous container, but if the command creating and starting it publishes the same ports, connects to the same network, and mounts the same external storage locations, it effectively replaces the previous container. (For information about upgrading InterSystems IRIS containers, see Upgrading InterSystems IRIS Containers.)
Important:
InterSystems does not support mounting NFS locations as external volumes in InterSystems IRIS containers.
Note:
As with other UNIX® and Linux commands, options to docker commands such as docker run can be specified in their long forms, in which case they are preceded by two hyphens, or their short form, preceded by one. In this document, the long forms are used throughout for clarity, for example --volume rather than -v.
Installing Docker
The Docker Engine consists of an open source containerization technology combined with a workflow for building and running containerized applications. Docker images from InterSystems comply with the OCI support specification, and are supported on Docker Enterprise Edition and Community Edition, version 18.03 and later. Docker EE only is supported for production environments.
To install the Docker engine on your servers, see Install Docker in the Docker documentation.
Docker supports a number of different storage drivers to manage images. To run InterSystems IRIS images, you may need to change the default driver, which depends on the host on which the Docker Engine is installed. For more information about supported storage drivers, see Docker Storage Driver.
Creating and Running InterSystems IRIS Docker Containers
This section describes what you need to do to run InterSystems IRIS containers using InterSystems images or images you have created, including the following topics:
Using InterSystems IRIS Docker Images
InterSystems IRIS images provided by InterSystems are available worldwide from repositories, and can be downloaded using the docker pull command. (Pulling an image from a repository can also be done within a Dockerfile.)
The following sections cover several important issues concerning the use of InterSystems IRIS images provided by InterSystems, including:
Docker Platforms and Versions Supported by InterSystems
InterSystems supports use of the InterSystems IRIS Docker images it provides on Linux platforms, and the instructions and procedures in this document are intended to be used on Linux. Rather than executing containers as native processes, as on Linux platforms, Docker for Windows creates a Linux VM running under Hyper-V, the Windows virtualizer, to host containers. These additional layers add complexity that prevents InterSystems from supporting Docker for Windows at this time.
We understand, however, that for testing and other specific purposes, you may want to run InterSystems IRIS-based containers from InterSystems under Docker for Windows. For information about the differences between Docker for Windows and Docker for Linux that InterSystems is aware of as they apply to working with InterSystems-provided container images, see Using InterSystems IRIS Containers with Docker for Windows on InterSystems Developer Community; for general information about using Docker for Windows, see Getting started with Docker for Windows in the Docker documentation.
Docker images from InterSystems comply with the OCI support specification, and are supported on Docker Enterprise Edition and Community Edition, version 18.03 and later. Docker EE only is supported for production environments.
Not all combinations of platform and Docker version are supported by Docker; for detailed information from Docker on compatibility, see the Compatibility Matrix and About Docker CE.
Downloading the InterSystems IRIS Docker Image
To make the InterSystems IRIS Docker image from InterSystems available for use, you can:
For simplicity, these instructions assume you are working with the image acme/iris:stable
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 available from the Docker Store (as described in the previous section) comes with a special free temporary license. Generally, however, license keys are not, and cannot be, 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, provides two options for handling the license key that can be used in a docker start or docker run command starting an InterSystems IRIS container, as follows:
See The iris-main Program for a list of iris-main options, and Running InterSystems IRIS Containers for examples of using the --key and --license-config options.
Changing the Default InterSystems IRIS Password
InterSystems IRIS is installed with several predefined user accounts, including the _SYSTEM account (see Predefined Users Accounts in the “Users” chapter of the Security Administration Guide), The default password for the predefined accounts is SYS. You can use _SYSTEM/SYS as credentials for the first login to an InterSystems IRIS instance deployed in a container, but for security reasons you are immediately prompted to change the password. This is true whether you log in using the iris terminal command or the management portal.
Note:
The iris-main --password-file option can be used to change the default password in scripts and other automation; for more information, see The iris-main Program.
Discovering Defaults in InterSystems Containers
Default values in InterSystems containers are exposed through the standard label mechanism so that needed information can be discovered, as shown in the following example. Users familiar with InterSystems technology will recognize the typical default ports and other useful information.
$ docker inspect -f {{.Config.Labels}} intersystems/iris:2019.1.0S.111.0

  "Labels": {
      "com.intersystems.adhoc-info": "",
      "com.intersystems.platform-version": "2019.1.0S.111.0",
      "com.intersystems.ports.default.arbiter": "2188",
      "com.intersystems.ports.default.license-server": "4002",
      "com.intersystems.ports.default.superserver": "51773",
      "com.intersystems.ports.default.webserver": "52773",
      "com.intersystems.ports.default.xdbc": "53773",
      "com.intersystems.product-name": "IRIS",
      "com.intersystems.product-platform": "dockerubuntux64",
      "com.intersystems.product-timestamp": "Wed Jan 16 2019 00:37:59 EST",
      "com.intersystems.product-timestamp.iso8601": "2019-01-16T05:37:59Z",
      "maintainer": "InterSystems Worldwide Response Center <support@intersystems.com>",
      "org.opencontainers.image.created": "2019-01-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": "2019.1.0S.111.0-0"
      }
Creating InterSystems IRIS Docker Images
There is more than one approach to creating a Docker image for InterSystems IRIS. One approach is to design the Dockerfile (see The Container Image, and in the Docker documentation Best practices for writing Dockerfiles) to do the following in building the image:
Images officially supported by InterSystems contain an internally developed program called iris-main that is used as the entrypoint application to aid in handling InterSystems IRIS inside a container; this means copying the program into the Dockerfile and declaring it as the entrypoint. The iris-main program is described in The iris-main Program.
Given the complexities in the preceding, the most common and recommended approach to building an image that includes your InterSystems IRIS-based application along with InterSystems IRIS is to base it on an existing InterSystems IRIS image provided by InterSystems, adding the dependencies relevant to your own application solution. This means starting with an image in which InterSystems IRIS is already installed with iris-main as the entrypoint; whatever you include in the Dockerfile is executed subsequent to this, which means you can start and issue commands to the InterSystems IRIS instance.
As a simple but instructive example of this approach, the XML file shown here contains ObjectScript code to run the Linux fortune command every 10 seconds, while the sample Dockerfile does the following:
  1. Starts with an InterSystems IRIS image as base.
  2. Copies in the XML code file.
  3. Installs the fortune command in the container.
  4. Starts InterSystems IRIS and uses iris terminal (see Connecting to an InterSystems IRIS Instance in the “Using Multiple Instances of InterSystems IRIS” chapter of the System Administration Guide) to compile the code, then shuts down the instance.
By updating the FROM command in the Dockerfile as needed, then issuing the docker build command in a directory containing both the Dockerfile and the _ZSTART.xml file, you can create an image that, when run interactively with the command docker run -it image, runs the code in the InterSystems IRIS instance and thereby outputs the result of the fortune command every 10 seconds.
#_ZSTART.XML

<Export generator="IRIS" version="26">
<Routine name="%ZSTART" type="MAC" languagemode="0"><![CDATA[
SYSTEM public
    if $d(^IRIS.Temp("%ZSTART","started")) quit
    set ^IRIS.Temp("%ZSTART","started")=1
    job launchapp
    quit
launchapp
    set filename="/usr/irissys/mgr/fortune.txt"
loop
    set exitcode=$zf(-100, "/stdout="""_filename_"""", "/usr/games/fortune")
    if (exitcode'=0) {
        do ##class(%SYS.System).WriteToConsoleLog("Couldn't get fortune, exit code: " _ exitcode)
    } else {
        set file=##class(%Library.File).%New(filename)
        set status=file.Open("R")
        if (status) {
            while 'file.AtEnd {
                set line=file.ReadLine()
                if (line'="") {
                    do ##class(%SYS.System).WriteToConsoleLog("Fortune: "_line)
                }
            }
        } else {
            do ##class(%SYS.System).WriteToConsoleLog("Could not open fortune results, status: " _ status)
        }
    }
    do file.Close()
    hang 10
    goto loop
]]></Routine>
</Export># Code installer example

# DOCKERFILE
#
# building from the InterSystems IRIS image

FROM intersystems/iris:2019.1.0.414.0

COPY _ZSTART.xml /

# Compile the application code
RUN apt-get update \
 && apt-get install -y fortune \
 && rm -rf /var/lib/apt/lists/* \
 && iris start iris \
 && printf '_SYSTEM\nSYS\npass123\npass123\nDo $SYSTEM.OBJ.Load("/_ZSTART.xml", "ck")\n \
    \nKill ^SYS("NODE")\nWrite ##class(SYS.ICM).ForcePasswordChange()\nHalt' | iris terminal IRIS -U %SYS \
 && iris stop iris quietly
Note:
Updating apt-get before running it, as shown in this example, is a best practice that helps avoid errors in building your image.
In exploring this approach, you can use the InterSystems IRIS Community Edition image described in Downloading the InterSystems IRIS Docker Image as a base image. Bear in mind, however, that it includes some functionality restrictions.
Note:
An important consideration when creating Docker images is image size. Larger images take longer to download and require more storage on the target machine. A good example of image size management involves the InterSystems IRIS journal files and write image journal (WIJ). Assuming that these files are relocated to persistent storage outside the container (where they should be), as described in Durable %SYS for Persistent Instance Data, you can reduce the size of an InterSystems IRIS or application image by deleting these files from the installed InterSystems IRIS instance within the container. This can be done by adding a script to the Dockerfile to be run after installation has completed, for example:
D INT^JRNSTOP 
iris stop
rm $ISC_PACKAGE_INSTALLDIR/mgr/IRIS.WIJ
rm $ISC_PACKAGE_INSTALLDIR/mgr/journal/*
The iris-main Program
There are several requirements an application must satisfy in order to run in a Docker container. The iris-main program was developed by InterSystems to enable InterSystems IRIS and its other products to meet these requirements.
The main process started by the docker run command, called the entrypoint, is required to block (that is, wait) until its work is complete. In the case of a long-running entrypoint application, this process should block until it's been intentionally shut down.
InterSystems IRIS is typically started using the iris start command, which spawns a number of InterSystems IRIS processes and returns control to the command line. Because it does not run as a blocking process, iris is unsuitable for use as the Docker entrypoint application.
The iris-main program solves this problem by starting InterSystems IRIS and then continuing to run as the blocking entrypoint application. The program also gracefully shuts down InterSystems IRIS when the container is stopped, and has a number of useful options. To use it, add the iris-main binary to a Dockerfile and specify it as the entrypoint application, for example:
ADD host_path/iris-main /iris-main
ENTRYPOINT ["/iris-main"]
Docker imposes these additional requirements on the entrypoint application:
In addition to addressing the issues discussed in the foregoing, iris-main provides a number of options to help tailor the behavior of InterSystems IRIS within a container. The options provided by iris-main are shown in the list that follows; examples of their use are provided in Running InterSystems IRIS Containers.
Options for iris-main appear after the image name in a docker run command, while the Docker options appear before it. As with the docker command, the options have a long form in which two hyphens are used and a short form using only one.
Note:
The iris-main program is configured to append its logging output to previous output, so that, when the InterSystems IRIS container is restarted, some record of how and why it shut down remains available.
Option Description Default
-i instance,
--instance=instance
Sets the name of the InterSystems IRIS instance to start or stop. (The instance in a container distributed by InterSystems is always named IRIS. IRIS
-d true|false,
--down=true|false
Stops InterSystems IRIS (using iris stop) on container shutdown true
-u true|false,
--up=true|false
Starts InterSystems IRIS (using iris start) on container startup true
-s true|false,
--nostu=true|false
Starts InterSystems IRIS in single-user access mode false
-k key_file,
--key=key_file
Copies the specified InterSystems IRIS license key (see License Keys for InterSystems IRIS Containers) to the mgr/ subdirectory of the install directory. none
-L license_config,
--license-config license_config
Configures the license server and specifies licenses to be served. For an explanation of this option’s arguments, see License Keys for InterSystems IRIS Containers; for examples of its use, see Running InterSystems IRIS Containers. none
-l log_file,
--log=log_file
Specifies a log file to redirect to standard output for monitoring using the docker logs command. none
-b command,
--before command
Sets the executable to run (such as a shell script) before starting InterSystems IRIS none
-a command,
--after command
Sets the executable to run after starting InterSystems IRIS none
-e command,
--exit command
Sets the executable to run after stopping InterSystems IRIS none
-c command
--create=command
Execute a custom shell command before any other arguments are processed
 
-t command
--terminate=command
Execute a custom shell command after any other arguments are processed
 
-p password_file,
--password-file=password_file
Change the default password for the predefined InterSystems IRIS accounts to the string contained in the file, and then delete the file.
This option is primarily for use in scripts and other automation; when using it, bear in mind the risks of committing the password to a file for any significant length of time. The first manual login to InterSystems IRIS after the container starts includes a mandatory default password change; for more information, see Changing the Default InterSystems IRIS Password.
 
--version Prints the iris-main version N/A
-h,
--help
Displays usage information and exits N/A
Durable %SYS for Persistent Instance Data
This section describes the durable %SYS feature of InterSystems IRIS, which enables persistent storage of instance-specific data when InterSystems IRIS is run within a container, and explains how to use it.
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, because all applications and programs generate and maintain operating and historical data — such as configuration and language settings, user records, and log files — containerization typically must address the need to enable persistence of program-related data on durable data storage. In the case of an InterSystems IRIS container, a mechanism that accomplishes the following two things is required:
The durable %SYS feature does this by storing the needed data on an external file system, which is mounted as a volume within the container and identified 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.)
Important:
To maintain separation of code and data, InterSystems recommends creating all InterSystems IRIS databases on the external file system using durable %SYS or another mechanism. If you do create a database within the container for testing or development purposes by defining it in your Dockerfile, the database file (db_name.DAT) is created read-only. To enable InterSystems IRIS to mount it as read-write, you must open a shell inside the container, for example with docker exec -it container_name bash, and use the touch command on the database file before you start the IRIS instance, for example:
$ sudo docker exec -it try-iris bash
# touch /usr/databases/DBTEST.DAT
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:
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:
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.
Running an InterSystems IRIS Container with Durable %SYS
To use durable %SYS, include in the docker run command the following options:
--volume /<external_host>:/<durable_storage>
--env ISC_DATA_DIRECTORY=/<durable_storage>/<durable_dir>
where external_host is the host path to the durable storage location to be mounted by the container, durable_storage is the name for this location inside the container, and durable_dir is the name of the durable %SYS directory to be created in the location. For example:
docker run --detach \
--publish 52773:52773 \
--volume /data/dur:/dur \
--env ISC_DATA_DIRECTORY=/dur/iconfig \
--name iris21 --init intersystems/iris:2019.1.0.633.0
In this example, the durable %SYS directory would be /data/dur/iconfig outside the container, and /dur/iconfig inside the container.
Important:
InterSystems does not support mounting NFS locations as external volumes in InterSystems IRIS containers.
When running InterSystems IRIS containers, always use the --init option to indicate that an init process should be used as PID 1 within the container, ensuring that the usual responsibilities of an init system are performed inside the container. For more information on this option, see the Docker documentation.
Note:
The --publish option publishes the InterSystems IRIS instance’s web server port (52773 by default) to the host, so that the instance’s management portal can be loaded into a browser on any host.
To avoid potential problems with the Docker TCP stack, you can replace the --publish option with the --net host option, which lets the container publish its default socket to the host network layer. The --net host option can be a simpler and faster choice when the InterSystems IRIS container you are running will be the only such on the host. The --publish option may be more secure, however, in that it gives you more control over which container ports are exposed on the host.
When you run an InterSystems IRIS container using these options, the following occurs:
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 (host directory /data/dur/iconfig).
See Running InterSystems IRIS Containers for examples of launching an InterSystems IRIS container with durable %SYS.
The following illustration shows the relationship between the installation directory of a newly installed InterSystems IRIS container and the external durable %SYS directory, with external application databases also depicted.
InterSystems IRIS Installation Directory and Durable %SYS
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:
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 not specified, the InterSystems IRIS instance uses the instance-specific data within the container, and therefore operates as a new 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, 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 iris.cpf file, 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 when launching the container, as described in Running InterSystems IRIS Containers.
Note:
When the durable %SYS directory is in use, the IRIS.WIJ file and some system databases are already separated from the InterSystems IRIS executables, which are inside the container. Under some circumstances, colocating the IRIS.WIJ file with your application databases instead may improve performance.
See File System Recommendations in the "File System and Storage Configuration Recommendations" chapter of the Installation Guide for more information about separation of file systems for InterSystems IRIS.
Running InterSystems IRIS Containers
This section provides some examples of of launching InterSystems IRIS containers with the Docker and iris-main options covered in this document, including:
Note:
The sample docker run commands in this section include only the options relevant to each example and omit options that in practice would be included, as shown (for example) in the sample command in Running an InterSystems IRIS Container with Durable %SYS.
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.
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 IRIS image testing

# Definitions to toggle_________________________________________
container_image="intersystems/iris:2018.1.2.633.0"

# the docker run command
docker run -d \
  -p 9091:51773 \
  -p 9092:52773 \
  -p 9093:53773 \
  -v /isc:/ISC \
  -h iris \
  --name iris \
  --init \
  --cap-add IPC_LOCK \
  $container_image \
  --key /ISC/iris.key \
  --log $ISC_PACKAGE_INSTALLDIR/mgr/messages.log
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 Compose 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:2018.1.2.633.0
    command: --license-config "4691540832 iris,4002,/ISC/licenses" 
    hostname: iris

    ports:
    # 51773 is the superserver default port
    - "9091:51773"
    # 52773 is the webserver/management portal port
    - "9092:52773"

    volumes:
    - isc:/ISC

    environment:
    - ISC_DATA_DIRECTORY=/ISC/iris_conf.d
Upgrading InterSystems IRIS Containers
When a containerized application is upgraded or otherwise modified, the existing container is removed or renamed, and a new container is created and started by instantiating a different image with the docker run command. Although the purpose is to modify the application, as one might with a traditional application by running an upgrade script or adding a plug-in, the new application instance actually has no inherent association with the previous one. Rather, it is the interactions established with the environment outside the container — for example, the container ports you publish to the host with the --publish option of the docker run command, the network you connect the container to with the --network option, and the external storage locations you mount inside the container with the --volume option in order to persist application data — that maintain continuity between separate containers, created from separate images, that represent versions of the same application.
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.
Caution:
Removing the original container is the best practice, because if the original container is started following the upgrade, two instances of InterSystems IRIS will be attempting to use the same durable %SYS data, which will result in unpredictable behavior, including possible data loss.
Typically, the upgrade command is identical to the command used to run the original container, except for the image tag. In the following docker run command, only the version_number portion would change between the docker run command that created the original container and the one that creates the upgraded container:
$ docker stop iris
$ docker rm iris
$ docker run --name iris --publish 9091:51773, 9092:52773, 9093:53773 \
--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. 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.)
  4. Start your original container. Because it uses the durable %SYS data that you safely recovered in the duplicate container, normal startup is safe.
Additional Docker/InterSystems IRIS Considerations
This section describes some additional considerations to bear in mind when creating and running InterSystems IRIS images container images, including the following:
Docker Storage Driver
Docker supports a number of different storage drivers to manage images. As of this writing, InterSystems supports the devicemapper and overlay2 storage drivers for running InterSystems IRIS in production on Linux hosts, and you must configure the Docker daemon to use one of these drivers. If using devicemapper, be sure to read Docker’s explanation of using the storage driver in direct-lvm mode for management of container images. To determine which storage driver your OS uses by default and how to change the driver if need be, see Docker storage driver in the Docker documentation and the Compatibility Matrix.
Locating Image Storage on a Separate Partition
The default storage location for Docker container images is /var/lib/docker. Because this is part of the root file system, you might find it useful to mount it on a separate partition, both to avoid running out of storage quickly and to protect against file system corruption. Both Docker and the OS might have trouble recovering when the above problems emerge. For example, SUSE states: “It is recommended to have /var/lib/docker mounted on a separate partition or volume to not affect the Docker host operating system in case of file system corruption.”
A good approach is to set the Docker Engine storage setting to this alternative volume partition. For example, on Fedora-based distributions, edit the Docker daemon configuration file (see Configure and troubleshoot the Docker daemon in the Docker documentation), locate the ExecStart= command line option for the Docker Engine, and add - as an argument.


Send us comments on this page
View this article as PDF   |  Download all PDFs
Copyright © 1997-2019 InterSystems Corporation, Cambridge, MA
Content Date/Time: 2019-08-16 05:39:09