First Look: InterSystems Products in Containers

Select a Platform

The instructions in this hands-on were created for, and are most easily used in, a Linux environment. If you do not have a Linux system available, InterSystems recommends that you create an account on a public cloud provider such as Google Cloud Platform (GCP), Amazon Web Services (AWS), or Microsoft Azure and provision a CentOS VM with Docker installed.

Install Docker

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

Download the InterSystems IRIS Image

To make the InterSystems IRIS image from InterSystems available for use in this hands-on, you must download the image to the system you are working on. The following alternatives describe the InterSystems IRIS images that are or may be available to you.

• You can use an InterSystems IRIS Community Edition image from the InterSystems Container Registry (ICR), which includes repositories for all images available from InterSystems and is described in Using the InterSystems Container RegistryOpens in a new tab. You can also download the Community Edition image from Docker HubOpens in a new tab.

  InterSystems IRIS Community Edition comes with a free built-in 13-month license (and some functionality restrictions); if you use Community Edition in this hands-on, you won’t have to provide a license key as described in the next step (Add the License Key to the External Storage Location). For more information, see Deploy InterSystems IRIS Community Edition on Your Own System in Deploy and Explore InterSystems IRIS.

  Note:

  Another option is to provision a cloud node hosting a running InterSystems IRIS Community Edition container on GCP, AWS, or Azure; for more information, see Deploy InterSystems IRIS Community Edition on a Cloud Node in Deploy and Explore InterSystems IRIS. If you use a Community Edition cloud node in this exercise, you can skip the next two steps and go to Change the Instance and Commit the Container as a New Image.

• If you are an InterSystems customer, you can use a released InterSystems IRIS image from the InterSystems Container Registry (ICR). Using the InterSystems Container RegistryOpens in a new tab lists the InterSystems IRIS images available from the IRC and explains how to use your WRC credentials to authenticate to the registry so you can download one.

• Your organization may have a private image registry that includes one or more InterSystems IRIS images. If so, obtain the location of the registry and the repository and tag for the image you need, as well as the credentials needed for access.

When you have identified the registry you want to download from and the credentials you need (if any), see Downloading the InterSystems IRIS ImageOpens in a new tab in Running InterSystems Products in Containers for instructions for downloading the InterSystems IRIS image.

For simplicity, these instructions assume you are working with the image intersystems/iris:2021.1.0.205.0.

Add the License Key to the External Storage Location

Like any InterSystems IRIS instance, an instance running in a container requires a license key (typically called iris.key).

The InterSystems IRIS Community Edition image available from the ICR or Docker Hub (described in the previous section) comes with a free built-in temporary license. Generally, however, license keys are not and cannot be included in an InterSystems IRIS container image, but instead must be copied into a container after it is started to be activated for the InterSystems IRIS instance running there. The iris-main program provides an option for this, but it requires you to place the license key in a storage location to be mounted as an external volume; instructions for using it are provided in the next section. To learn more about license keys for InterSystems IRIS containers, see License Keys for InterSystems IRIS ContainersOpens in a new tab in Running InterSystems Products in Containers.

Copy your InterSystems IRIS license key file, iris.key, to the external storage location.

Run a Container from the InterSystems IRIS Image

Once you have made the InterSystems IRIS image available on your local machine and have identified the external storage location and placed your license key on it, you are ready to use the docker run command to create and start a container. The docker run command actually combines three separate commands, as follows:

• docker pull — Downloads an image if it is not already present locally.

• docker create — Creates a container from the image.

• docker start — Starts the container.

Each of these commands is useful separately, for various purposes in different contexts. For more information, see Docker run referenceOpens in a new tab in the Docker documentation.

A sample docker run command follows; all of its options are explained in the accompanying text. Note that options to the docker run command appear on the command line before the image specification, while options to the InterSystems iris-main program (see InterSystems IRIS in Containers) come after. (In this case, the pull command that is part of docker run is not needed, as you have already downloaded the iris image you want to use.)

docker run --name iris
  --detach
  --publish 52773:52773
  --volume /nethome/pmartinez/iris_external:/external
    intersystems/iris:2021.1.0.205.0
  --key /external/iris.key

• --name container_name

  Specifies the name of the container, which you can use to refer to the container in other Docker commands, for example docker stop container_name when you want to stop the container.

• --detach

  Runs the container in the background (and displays the container’s unique ID).

• --publish host_port:container_port

  Publishes a port within the container to a port on the host so that entities outside the container (on the host or on other machines) can contact a program in the container. For example, an InterSystems IRIS instance’s Management Portal is reached through the instance’s web server port (52773 by default). If this port inside the container is published to a port on the host, the instance’s Management Portal can be loaded into a browser using the host’s port.

  --volume external_storage_path:internal_volume

  Mounts an external storage location accessible by the container as a storage volume inside the container. For information about which storage locations can be mounted in this way and Docker configuration that may be required, see Use VolumesOpens in a new tab in the Docker documentation.

  Important:

  In this release, the host file system location you mount and specify for this purpose must be writable by user 51773. (You will most likely need root privileges to effect this.)

  InterSystems does not support mounting NFS locations as external volumes in InterSystems IRIS containers.

• repository/image:tag

  Specifies the image to be pulled and used to create a container (see Download the InterSystems IRIS Image). Use the docker images command to list available images and make sure you are specifying the right one.

• --key license_key_path

  An iris-main option that identifies the InterSystems IRIS license key to be installed in the instance in the container; this location must be on a mounted volume. When the container is running, iris-main continuously monitors the staged license key for changes; if any change is detected, it is copied to the current /mgr/ directory and activated.

Use the preceding sample and explanations to construct your own docker run command and execute it on the command line. When the command has completed, use the docker ps command to see your container in the list with a status of Up.

$ docker run --name iris --detach --publish 52773:52773
    --volume /nethome/pmartinez/iris_external:/external
    intersystems/iris:2021.1.0.205.0
    --key /external/iris.key
426d4a511d6746d89ec2a24cf93b29aa546ea696b479a52210d37da4c6d04883
$ docker ps
CONTAINER ID  IMAGE                             COMMAND                 CREATED        STATUS       
426d4a511d67  intersystems/iris:2021.1.0.205.0  "/iris-main --key ..."  5 seconds ago  Up 3 seconds 
    PORTS                     NAMES
    0.0.0.0:52773->52773/tcp  iris

Change the Instance and Commit the Container as a New Image

When you alter the program running inside a container, you can use the docker commit command to create a new image from the container. This new image is the same as the original image from which you created the container, but includes the alterations you made to the container. To see how this works, follow these steps:

1. Open the Management Portal for the InterSystems IRIS instance in the container. The URL for an instance’s Management Portal incorporates both the host identifier and web server port numberOpens in a new tab of the instance.

   • The host identifier is the hostname or IP address of the system the container is running on; if your browser is running on the same system as the container, you can use localhost.

   • The web server port number is the host port number to which you published the instance’s web server port number, which is 52773, when you started the container with docker run. Assuming you included --publish 52773:52773 as provided in the sample command at the end of the previous section, the web server port number is 52773.

   For example, on the container host, with web server port 52773, the Management Portal URL would be http://localhost:52773/csp/sys/%25CSP.Portal.Home.zen.

   Log in using one of the predefined user accounts, for example _SYSTEM, which have the default password SYS (see Predefined User Accounts). For security reasons, you are immediately prompted to change the password on first login (using the Management Portal or the iris terminal command) to any predefined account on a containerized InterSystems IRIS instance.

   Note:

   For more information about changing the default password for the predefined accounts (which is strongly recommend in production), including in scripts and automated deployments, see Authentication and PasswordsOpens in a new tab in Running InterSystems Products in Containers.

2. From the home page, select System Administration > Configuration > System Configuration > Namespaces to display the Namespaces page, then click the Create New Namespace button to display the New Namespace page.

3. Create a namespace named USER2 by entering USER2 in the Name of the namespace box, selecting USER from the Copy from dropdown, clearing the Enable namespace for interoperability productions check-box and confirming that, clicking the Save button, and finally confirming that you want to copy all properties and mappings. Then click Close on the Copy Namespace Mappings page to return to the Namespaces page, on which the USER2 namespace is now listed. You have now altered the instance in the container.

4. Next, stop the container and commit it as a new image called iris2, then list the available images.

   $ docker stop iris
   $ docker commit iris acme/iris2:test
   sha256:7b4adb9f7abf1490a39086665ccd3d255c05163c25cb9a3de8e9421f6ca16b40
   $ docker images
   REPOSITORY          TAG             IMAGE ID      CREATED        SIZE
   acme/iris2          test            421f6ca16b40  8 seconds ago  1.40GB
   intersystems/iris   2020.3.0.221.0  15627fb5cb76  1 hour ago     1.39GB
   centos              7.3.1611        262f7381844c  2 weeks ago    192MB
   hello-world         latest          05a3bd381fc2  7 months ag    1.84kB
   
   

   

5. Finally, remove the container created from the original iris image.

   $ docker rm iris
   iris
   
   

   

Run and Investigate the Second InterSystems IRIS-based Container

To wrap up this experience, you will use the docker run command to create and start a container from the InterSystems-IRIS based image you just committed, including the durable %SYS feature for persisting instance-specific data. Durable %SYS is a much more useful way of saving instance-specific data and any changes you have made to it. Because this data is saved outside the container, it can become the data for a new InterSystems IRIS container, allowing you to upgrade an InterSystems IRIS instance by running a container from a later image while retaining the data from the previous container; this is not possible with internal container changes committed to a new image. (For detailed information on durable %SYS, see Durable %SYS for Persistent Instance DataOpens in a new tab in Running InterSystems Products in Containers.)

When you have started the new container, you will do the following:

• Confirm that the namespace you created in the container you committed as a new image (see Change the Instance and Commit the Container as a New Image) exists in the InterSystems IRIS instance in the new container.

• Change a setting in the InterSystems IRIS instance in the container and see it reflected in the durable %SYS data outside the container.

• Confirm that the demo file you added exists inside the container.

To do this, follow these steps:

1. Identify an external storage location for this container. You can use the one you chose for the previous container in Add the License Key to the External Storage Location or select a new one. The license key should still be in place in the previous location. (If you use a new location, ensure that the license key is in place.)

2. Create a docker run command like the one you executed in Run a Container from the InterSystems IRIS Image, based on the instructions there but with two changes.

   • Add the option --env ISC_DATA_DIRECTORY=pathname

     Identifies the durable %SYS directory, that is, the location in which the InterSystems IRIS instance’s persistent data is written. The durable %SYS directory must be on a mounted volume (see the --volume option and Add the License Key to the External Storage Location).

     Note:

     InterSystems recommends specifying a subdirectory of the mounted volume as the durable %SYS location. This is shown in the docker ps example that follows.

   • Specify the new image with image:tag

     Previously, you created the container from intersystems/iris:2021.1.0.205.0, the InterSystems-provided image; this time, you are using acme/iris2:test, the image you created by committing the altered iris container.

   Call the container iris2. When the docker run command has completed, use the docker ps command to list the container and see its status. For example:

   $ docker run --name iris2 --detach --publish 52773:52773
       --volume /nethome/pmartinez/iris_external:/external
       --env ISC_DATA_DIRECTORY=/external/durable
       acme/iris2:test
       --key /external/iris.key
   bdfe214ef76a34290a8308cddce92162aae14df1ba1bc244e692af3c8d911a3e
   $ docker ps
   CONTAINER ID  IMAGE            COMMAND                 CREATED        STATUS       
   af3c8d911a3e  acme/iris2:test  "/iris-main --key ..."  5 seconds ago  Up 3 seconds 
     PORTS                     NAMES
     0.0.0.0:52773->52773/tcp  iris2
   

   
   Note:

   The --key option is not needed with the InterSystems IRIS Community Edition image (see Download the InterSystems IRIS Image), which comes with a free built-in license.

   Docker Compose, a tool for defining and running multicontainer 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, see Running an InterSystems IRIS Container: Docker Compose ExampleOpens in a new tab in Running InterSystems Products in Containers and Overview of Docker ComposeOpens in a new tab in the Docker documentation.