First Look: InterSystems Products in Containers
This First Look guide introduces you to the fundamentals of using 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 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 in Containers provides links to additional sources.
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 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 Containers
Because a 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 images containing a fully-installed instance of InterSystems IRIS, as well as other associated images. For more information on images from InterSystems, see Using InterSystems IRIS Images 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.
Container images from InterSystems comply with the Open Container Initiative (OCI) specification, and are built using the widely popular container Ubuntu operating system on 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 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 image using 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.
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.
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.
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.
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 Registry. You can also download the 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); 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 Registry 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 Image 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 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 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 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
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.
Runs the container in the background (and displays the container’s unique ID).
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.
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.
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.
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 --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
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.
If the image is not yet present locally but is in your organization’s repository (see Download the InterSystems IRIS 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:
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 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 Passwords in Running InterSystems Products in Containers.
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.
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.
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
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 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:
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.)
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 iris2Note:
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 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:2021.1.0.205.0 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:
Open the Management Portal and log in, as described in Change the Instance and Commit the Container as a New Image.
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:
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
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.
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
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 in Containers
At this point, you are ready to continue exploring what containers and InterSystems IRIS have to offer. Use the documentation and resources below to dive deeper into containers and InterSystems IRIS.
Articles from the InterSystems Developer Community:
InterSystems Cloud Manager Guide — Use InterSystems Cloud Manager (ICM) to easily and intuitively provision infrastructure and deploy containers on it in a variety of ways. ICM brings the benefits of Infrastructure as Code (IaC),nd containerized deployment to InterSystems IRIS without requiring major investments in new technology, training, configuration, and management. This guide contains documentation on both ICM and using InterSystems IRIS with Docker containers.