Skip to main content

First Look: InterSystems Products in Containers

This First Look guide introduces you to the fundamentals of using Docker containers with InterSystems IRIS® data platform by giving you a focused overview and a basic, hands-on example. You will learn the purpose, importance, and benefits of Docker containers, as well as the specifics of how InterSystems implements them.

For the full documentation on Docker containers and InterSystems IRIS, see Running InterSystems Products in Containers, as well as the “ICM Overview” chapter of the InterSystems Cloud Manager Guide. The section Learn More About InterSystems IRIS and Docker Containers provides links to additional sources.

To browse all of the First Looks, including those that can be performed on a free evaluation instance of InterSystems IRIS, see InterSystems First Looks.

Why Containers?

Containers package applications into platform-independent, fully portable runtime solutions, with all dependencies satisfied and isolated. Docker containers, specifically, are ubiquitous. Because all major public cloud Infrastructure as a Service (IaaS) providers support Docker, organizations can reduce costs and complexity by using Docker containers and letting the cloud provider handle the infrastructure.

Containers bring all of the following benefits:

  • Containers cleanly partition code and data, providing full separation of concerns and allowing applications to be easily deployed and upgraded.

  • Containers are very efficient; an application within a container is packaged with only the elements needed to run it and make it accessible to the required connections, services, and interfaces, and the container runs as a single process that takes no more memory than any other executable.

  • Containers support clean movement of an application between environments — for example, from development to test and then to production — thereby reducing the process and management conflicts typical of departments with different objectives. Developers can focus on the latest code and libraries, quality developers on testing and defect description, and operations engineers on the overall solution infrastructure including networking, high availability, data durability, and so on.

  • Containers provide the agility, flexibility, and repeatability needed to revolutionize the way many organizations respond to business and technology needs. Containers clearly separate the application provisioning process, including the build phase, from the run process, and allow an organization to adopt a uniform application delivery approach, including a more agile delivery methodology (DevOps) and architecture (microservices).

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.

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 systems and OS platforms your Linux-based InterSystems IRIS containers are running on; you interact with them all in the same way, just as you would with traditional InterSystems IRIS instances running on Linux systems.

The following describes different aspects of how InterSystems IRIS uses containers.

  • InterSystems-provided images — A container image is the executable package, while a container is a runtime instance of an image — what the image becomes in memory when executed. InterSystems provides Docker images containing a fully-installed instance of InterSystems IRIS, as well as other associated images. For more information on Docker images from InterSystems, see InterSystems IRIS Docker Images from InterSystems in Running InterSystems Products in Containers.

    In the hands-on experience in this First Look, you will create and start a container from an InterSystems IRIS image provided by InterSystems.

  • The iris-main program — The iris-main program enables InterSystems IRIS and other products to satisfy the requirements of applications running in Docker containers. The entrypoint application, the main process started when a container is started, is required to block (that is, wait) until its work is complete, but the command starting InterSystems IRIS does not run as a blocking process. The iris-main program solves this by starting InterSystems IRIS and then continuing to run as the blocking entrypoint application. For more information about iris-main, see The iris-main Program in Running InterSystems Products in Containers.

    The program also offers a number of options to help tailor the behavior of InterSystems IRIS within a container; you will use some iris-main options in the hands-on experience in this First Look.

  • The durable %SYS feature — Because a containerized application is isolated from the host environment, it does not write persistent data; whatever it writes inside the container is lost when the container is removed and replaced by a new container. Therefore, an important aspect of containerized application deployment is arranging for data to be stored outside of the container and made available to other and future containers.

    The durable %SYS features enables persistent storage of instance-specific data — such as user definitions, audit records, and the log, journal, and WIJ files — when InterSystems IRIS is run in a container, allowing an instance to span multiple containers. For example, if you run an InterSystems IRIS container using durable %SYS, you can upgrade the instance by stopping the original container and running a new one that uses the instance-specific data created by the old one.

    You will explore the durable %SYS feature in the hands-on experience in this First Look. For detailed information on durable %SYS, see Durable %SYS for Persistent Instance Data in Running InterSystems Products in Containers.

Important:

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

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

InterSystems Cloud Manager (ICM) provides automated deployment of InterSystems IRIS containers and others on cloud infrastructure it provisions, as well as existing virtual and physical infrastructure. For more information about using ICM to deploy containerized InterSystems IRIS instances, see First Look: InterSystems Cloud Manager and the InterSystems Cloud Manager Guide.

Try It! Create Your Own InterSystems IRIS-based Container

Now that you have had an introduction to containers, this section will walk you through a simple, hands-on experience with InterSystems IRIS containers, in which you will do the following:

  • Prepare by installing Docker, locating the InterSystems-provided InterSystems IRIS image, and readying a storage location with your InterSystems IRIS license key.

  • Create and start an InterSystems IRIS container using the docker run command and the InterSystems IRIS image.

  • Change the InterSystems IRIS instance running in the container, then use the docker commit command to commit the container as a second InterSystems IRIS-based image that includes the change you made.

  • Run a container from the second imageusing the durable %SYS feature to store instance-specific data, and:

    • Confirm that the change you made to the InterSystems IRIS instance in the first container before committing it as a new image is reflected in the new container.

    • Change a setting in the InterSystems IRIS instance running inside the new container and see it reflected in the durable %SYS directory outside the container.

These instructions assume you have an InterSystems IRIS license and access to InterSystems software downloads.

Because this example is intended to be brief, it does not go into detail about matters such as settings and security considerations. In production systems, there are many things you will need to do differently. The resources in the last section offer a more complete picture of using containers with InterSystems IRIS.

Note:

Some of the commands included here may require root privileges.

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.

Note:

If need be, the instructions can be adapted to Windows or MacOS. On Windows, you can execute the instructions in a Command Prompt or Windows PowerShell window, opened with Run as administrator; do not use PowerShell ISE. For more information about Docker for Windows, see Using InterSystems IRIS Containers with Docker for Windows on InterSystems Developer Community and Getting started with Docker for Windows in the Docker documentation.

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 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 in Running InterSystems Products in Containers.

Download the InterSystems IRIS Docker Image

To make the InterSystems IRIS Docker image from InterSystems available for use in this hands-on, you can do one of the following:

  • Download an InterSystems IRIS Community Edition image from the Docker Store’s InterSystems IRIS data platform page.

    InterSystems IRIS Community Edition comes with a free built-in 13-month license (and some functionality restrictions). For more information, see Deploy InterSystems IRIS Community Edition on Your Own System in Deploy and Explore InterSystems IRIS.

    Note:

    You can also 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.

  • Download the archive from InterSystems and load the image. To use this image, you must have an InterSystems IRIS license.

    InterSystems IRIS images are distributed as Docker tar archive files, available in the InterSystems Worldwide Response Center (WRC) download area. Once you have downloaded the tar file, you can make it available on your system using the docker load command, as follows:

    docker load -i iris-2018.1.1.888.0-docker.tar.gz
    c6dba2103a94: Loading layer [==================================================>]  1.217GB/1.217GB
    1b229d298c03: Loading layer [==================================================>]  1.479MB/1.479MB
    Loaded image: docker.intersystems.com/intersystems/iris:2018.1.1.888.0
    
    $ docker images
    REPOSITORY                                  TAG             IMAGE ID       CREATED       SIZE
    docker.intersystems.com/intersystems/iris   2018.1.1.888.0  e3cd4844771e   13 days ago   1.39GB
    acme/iris                                   stable          e3cd4844771e   13 days ago   1.39GB
    centos                                      7.3.1611        262f7381844c   2 weeks ago   192MB
    hello-world                                 latest          05a3bd381fc2   7 months ago  1.84kB
    
    Copy code to clipboard

    You can tag the image if you want a simpler name:

    $ docker tag docker.intersystems.com/intersystems/iris:2018.1.1.888.0 acme/iris:stable
    Copy code to clipboard
  • Download the image from your organizations’s Docker repository, if it has already been placed there

    If your organization has a Docker repository and the InterSystems IRIS image from InterSystems is already loaded, obtain the location of the repository and the needed credentials plus the image tag to use, then log into the repository. Once you have done so, you can use the docker pull command to download the image from the repository:

    $ docker login docker.acmeinternal.com
    Username: pmartinez@acme.com
    Password: **********
    $ docker pull docker.acmeinternal.com/iris:stable
    5c939e3a4d10: Pull complete
    c63719cdbe7a: Pull complete
    19a861ea6baf: Pull complete
    651c9d2d6c4f: Pull complete
    $ docker images
    REPOSITORY           TAG            IMAGE ID          CREATED       SIZE
    acme/iris            stable         15627fb5cb76      3 days ago    1.39GB
    acme/iris-arm64      stable         15627fb5cb76      3 days ago    1.39GB
    centos               7.3.1611       262f7381844c      2 weeks ago   192MB
    hello-world          latest         05a3bd381fc2      7 months ag   1.84kB
    
    Copy code to clipboard

For simplicity, these instructions assume you are working with the image acme/iris:stable

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 Docker Store (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 Containers 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 Docker 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 reference 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 Docker Containers) come after.

docker run --name iris
  --init
  --detach
  --publish 52773:52773
  --volume /nethome/pmartinez/iris_external:/external
  acme/iris:stable
  --key /external/iris.key
Copy code to clipboard
  • --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.

  • --init

    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.

  • --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 Volumes in the Docker documentation.

    Important:

    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 Docker Image). Use the docker images command to list available images and make sure you are specifying the right one. The instructions here assume the image is iris:stable.

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

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 --init --detach --publish 52773:52773
    --volume /nethome/pmartinez/iris_external:/external
    acme/iris:2018.1.0.583 --key /external/iris.key
426d4a511d6746d89ec2a24cf93b29aa546ea696b479a52210d37da4c6d04883
$ docker ps
CONTAINER ID  IMAGE             COMMAND                 CREATED        STATUS       
426d4a511d67  acme/iris:stable  "/iris-main --key ..."  5 seconds ago  Up 3 seconds 
    PORTS                     NAMES
    0.0.0.0:52773->52773/tcp  iris
Copy code to clipboard
Note:

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

If the image is not yet present locally but is in your organization’s repository (see Download the InterSystems IRIS Docker Image), Docker pulls (downloads) the image before creating and starting the container.

As shown in the example, after creating the container, Docker outputs the UUID long identifier; the first 12 characters make up the UUID short identifier, which is used to identify the container in other output, for example from the docker ps command.

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 number 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 Users Accounts in the “Users” chapter of the Security Administration Guide). 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 Passwords in Running InterSystems Products in Docker 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
    acme/iris            stable         15627fb5cb76      3 days ago     1.39GB
    centos               7.3.1611       262f7381844c      2 weeks ago    192MB
    hello-world          latest         05a3bd381fc2      7 months ag    1.84kB
    
    Copy code to clipboard
  5. Finally, remove the container created from the original iris image.

    $ docker rm iris
    iris
    
    Copy code to clipboard

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 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 Data 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 InterSystem 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 acme/iris:stable, 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 --init --detach --publish 52773:52773
        --volume /nethome/pmartinez/iris_external:/external
        --env ISC_DATA_DIRECTORY=/external/durable
        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
    Copy code to clipboard
    Note:

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

    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, see Running an InterSystems IRIS Container: Docker Compose Example in Running InterSystems Products in Containers and Overview of Docker Compose in the Docker documentation.

Confirm the Change You Committed from the Altered InterSystems Container

In Change the Instance and Commit the Container as a New Image, you added a namespace to the InterSystems IRIS instance in the container you created from the InterSystems-provided image intersystems/iris:stable and then committed that container as a new image, acme/iris2:test. The namespace you added should therefore exist in the InterSystems IRIS instance running inside the iris2 container, which was created from acme/iris2:test.

To confirm this, do the following:

  1. Open the Management Portal and log in, as described in Change the Instance and Commit the Container as a New Image.

  2. From the home page, select System Administration > Configuration > System Configuration > Namespaces to display the Namespaces page; the USER2 namespace you created in the iris container is listed.

Explore and Alter the Durable %SYS Directory

To explore the durable %SYS feature of InterSystems IRIS containers, do the following:

  1. To see the instance-specific data written outside the container by InterSystems IRIS because you included the durable %SYS environment variable in your docker run command, display the contents of the directory you specified in that variable in the storage location you specified using the --volume option as the external volume to be mounted. For example, if that directory was specified as /nethome/pmartinez/iris_external/durable, as shown in the sample docker run, you’d do the following

    $ cd /nethome/pmartinez/iris_external
    $ ls
    durable iris.key
    $ ls durable
    csp  dist  httpd  iris.cpf  iris.cpf_20180417  _LastGood_.cpf  mgr
    $ ls durable/mgr
    alerts.log    irisaudit          iris.ids      irislocaldata  iristemp  IRIS.WIJ  journal.log   
    startup.last  SystemMonitor.log  user          ilock          IRIS.DAT  iris.lck  iris.shid      
    iris.use      journal            messages.log  stream         Temp
    
    Copy code to clipboard
  2. Return the Management Portal for the InterSystems IRIS instance in the container and select System Administration > Configuration > System Configuration > Journal Settings to display the Journal Settings page. Change the Secondary journal directory setting from /external/durable/mgr/journal/ to /external/durable/mgr/journal2/ and click Save.

  3. Return to the command line and list the mgr subdirectory of the durable %SYS directory again:

    $ ls /nethome/pmartinez/iris_external/durable/mgr
    alerts.log         irisaudit     iris.ids   iris.lck    iris.shid        iris.use      journal 
    journal.log        messages.log  stream     Temp        ilock            IRIS.DAT      iris.key  
    irislocaldata      iristemp      IRIS.WIJ   journal2    licmanager.port  startup.last  
    SystemMonitor.log  user
    
    Copy code to clipboard

    The journal2 subdirectory has been added outside of the container because of the change you made to the InterSystems IRIS instance inside the container.

This example shows how durable %SYS enables you to upgrade a containerized InterSystems IRIS instance by creating a container from a new image. All persistent changes you make to the instance are stored outside the container in the durable %SYS directory; if you create and start a new container from any InterSystems IRIS image using the needed options — that is, the --volume option mounting the external storage location for durable %SYS and the --env ISC_DATA_DIRECTORY option specifying the durable %SYS location on that mounted volume, which must exist and contain a /mgr subdirectory — those changes are inherited by the instance because it uses the same data as the instance in the previous container.

Learn More About InterSystems IRIS and Docker Containers

At this point, you are ready to continue exploring what Docker has to offer. Use the documentation and resources below to dive deeper into containers and InterSystems IRIS.