docs.intersystems.com
Home  /  First Look: InterSystems Products in Docker Containers


Articles
First Look: InterSystems Products in Docker Containers
InterSystems: The power behind what matters   
Search:  


This First Look guide introduces you to the fundamentals of using Docker containers with InterSystems IRIS™ 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 IRIS 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.
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:
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.
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:
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.
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 provides such as Google Cloud Platform, Amazon Web Services, or Microsoft Azure and provision a CentOS VM with Docker installed.
Note:
Some of the commands included here may require root privileges.
If you prefer to use this hands-on on a Windows system, consult Using InterSystems IRIS Containers with Docker for Windows on InterSystems Developer Community for information about steps you must take before using the instructions with Docker for Windows and differences in the procedure; for general information about using Docker for Windows, see Getting started with Docker for Windows in the Docker documentation.
Install Docker
InterSystems IRIS is provided as a Docker image that includes everything you need. Therefore the only requirements for system on which you launch the InterSystems IRIS container are that Docker CE 17.06+ is installed, with the Docker daemon running, and that the system is connected to the Internet.
Prepare the InterSystems IRIS Docker Image
To make the InterSystems IRIS Docker image from InterSystems available for use in this hands-on, you can:
For simplicity, these instructions assume you are working with the image acme/iris:stable
Add the Password File and License Key to the External Storage Location
There are two files you need to make available to the container and the containerized InterSystems IRIS instance. To make this possible, you must mount a storage location as an external volume when running the container. Instructions for doing this are provided in the following section.
The following two files must be available in the storage location you choose before you run the container:
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 a password file and 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:
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 \
--detach \
--publish 52773:52773 \
--volume /nethome/pmartinez/iris_external:/external \
--env ICM_SENTINEL_DIR=/external \
acme/iris:stable \
--key /external/iris.key \
--before "/usr/irissys/dev/Cloud/ICM/changePassword.sh /external/password.txt"
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 --env ICM_SENTINEL_DIR=/external \
  acme/iris:2018.1.0.583 --key /external/iris.key \
  --before "/usr/irissys/dev/Cloud/ICM/changePassword.sh /external/password.txt"
029818771b7c190916121c0728fc9f779c47b8ee0d651e0eea43f3d9d98f1209
$ docker ps
CONTAINER ID  IMAGE             COMMAND                 CREATED        STATUS        \
f3d9d98f1209  acme/iris:stable  "/iris-main --key ..."  5 seconds ago  Up 3 seconds  \
  PORTS                     NAMES
  0.0.0.0:52773->52773/tcp  iris
Note:
If the image is not yet present locally but is in your organization’s repository (see Prepare the InterSystems IRIS Docker Image), Docker pulls (downloads) the image before creating and starting the container.
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 by loading the following URL in your browser:
    http://<host>:52773/csp/sys/%25CSP.Portal.Home.zen
    where host is the DNS name or IP address of the system on which the docker container is running.
  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 Make this an interoperability-enabled namespace 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
    
  5. Finally, remove the container created from the original iris image.
    $ docker rm iris
    iris
    
Build an InterSystems IRIS-based Image Using a Dockerfile
Committing a running container is a convenient way to save changes for testing purposes or as a minor delta. But the preferred method for creating a production image is to define the image in a Dockerfile and then build it using the docker build command, which
In this section you will create a Dockerfile based on your modified InterSystems IRIS image and use it to build a new image that installs an application with InterSystems IRIS, In the next, Run and Investigate the InterSystems IRIS-based Container, you will run a container from this image that uses durable %SYS, a feature of InterSystems IRIS containers that lets you save instance-specific data outside the container, and investigate it.
Each Dockerfile specifies an existing base image which provides (at a minimum) the runtime environment for whatever is to be executed in the container; if the base image contains installed software, that software is also included in the image built from the Dockerfile. For example, if you use the InterSystems IRIS image from InterSystems as a base, the resulting image inherits the Ubuntu 16.04 LTS runtime environment on which the InterSystems image is based and includes an installed InterSystems IRIS instance. To this you can add specifications for everything needed to add your application — for example, copying or downloading files, setting environment variables, installing the application, and launching the application.
Before creating your Dockerfile, choose or create a very simple application to install in the container and identify or create an installer to be copied into the Dockerfile. To make it easy, you can use the example that follows — a command to create a file. In the Dockerfile for a production image, you might install your InterSystems IRIS-based application instead.
To build your InterSystems-IRIS image, follow these steps:
  1. Using your favorite text editor, create a file named Dockerfile containing the following contents. The image you specify in the FROM statement should be iris2, the one you created by committing the container you modified in Change the Instance and Commit the Container as a New Image. If you have a simple application to install, replace the RUN command shown with one installing that application.
    # Build from the modified IRIS image
    FROM acme/iris2:test
    
    # create a demo file
    RUN echo "This is the file added to the image" > /demo.txt 
  2. Issue the docker build command, specifying the build context (the location of the Dockerfile) and naming and tagging the resulting image (you may need to run this command with root privileges):
    $ docker build /nethome/pmartinez --tag acme/iris3:test
    Sending build context to Docker daemon  478.1MB
    Step 1/2 : FROM intersystems/iris:stable
     ---> 15627fb5cb76
    Step 2/2 : RUN echo "This is the file added to the image" > /demo.txt
     ---> Running in 000b94705814
     ---> 64350c828716
    Removing intermediate container 000b94705814
    Successfully built 64350c828716
    Successfully tagged iris3:test
    
  3. When the image has built successfully, list the available images
    $ docker images
    REPOSITORY           TAG            IMAGE ID          CREATED        SIZE
    acme/iris3           test           64350c828716      9 seconds ago  1.44
    acme/iris2           test           421f6ca16b40      1 hour 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
    
Note:
In addition to the base specified by FROM, you can always use a RUN statement to install additional Linux packages using the apt-get command. For example, to include in the image the fortune command with the fortune-debian-hints package to display hints about using Debian distributions, you could include:
RUN apt-get update -y && apt-get install -y fortunes-debian-hints && rm -rf /var/lib/apt/lists/*
Run and Investigate the 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 built, 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 IRIS in Containers.)
When you have started the new container, you will do the following:
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 Password File and License Key to the External Storage Location or select a new one. The license key should still be in place in the previous location, but the ICM password script has replaced the password.txt file with a file called change_password.done. Remove the latter and recreate the former; the password can be the same as or different from the last one. (If you use a new location, ensure that both the license key and the password.txt file are 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.
    Call the container iris3. 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 iris3 --detach --publish 52773:52773 \
      --volume /nethome/pmartinez/iris_external:/external \
      --env ISC_DATA_DIRECTORY=/external/durable \
      --env ICM_SENTINEL_DIR=/external iris3:test --key /external/iris.key \
      --before "/usr/irissys/dev/Cloud/ICM/changePassword.sh /external/password.txt"
    bdfe214ef76a34290a8308cddce92162aae14df1ba1bc244e692af3c8d911a3e
    $ docker ps
    CONTAINER ID  IMAGE            COMMAND                 CREATED        STATUS        \
    af3c8d911a3e  acme/iris3:test  "/iris-main --key ..."  5 seconds ago  Up 3 seconds  \
      PORTS                     NAMES
      0.0.0.0:52773->52773/tcp  iris3
    Note:
    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 IRIS 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. In Build an InterSystems IRIS-based Image Using a Dockerfile, you created a Dockerfile based on acme/iris2:test and used it to build the image acme/iris3:test. The namespace you added should therefore exist in the InterSystems IRIS instance running inside the iris3 container, which was created from acme/iris3:test. These steps are illustrated in the following list and illustration:
Steps in this Hands-on
To confirm this, do the following:
  1. Open the management portal for the instance in the container by loading the following URL in your browser:
    http://<host>:52773/csp/sys/%25CSP.Portal.Home.zen
    where host is the DNS name or IP address of the system on which the docker container is running.
  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
    change_password.done 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
    
  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
    
    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—those changes are inherited by the instance because it uses the same data as the instance in the previous container.
Confirm the File in the Container
In Build an InterSystems IRIS-based Image Using a Dockerfile, you created a Dockerfile that added a demo file to an InterSystems IRIS-based image (acme/iris2:test) and used it to build the image acme/iris3:test. To verify that the file was created, use the docker exec command to display the file in the iris3 container from outside the container, as follows::
$ docker exec iris3 cat /demo.txt
This is the file added to the image

$
You could also do this interactively by using the docker exec command to open a Bash shell inside the container, as follows:
$ docker exec -it iris3 bash
root@af3c8d911a3e:/# ls
bin       dev      external   iris-main.log  media  proc  sbin  tmp  waitISC.log
boot      durable  home       lib            mnt    root  srv   usr
demo.txt  etc      iris-main  lib64          opt    run   sys   var
root@af3c8d911a3e:/# cat /demo.txt
This is the file added to the image
root@af3c8d911a3e:/#
While in the Bash shell, list the durable %SYS directory, which you listed from outside the container in Explore and Alter the Durable %SYS Directory, from inside the container instead:
root@af3c8d911a3e:/# ls /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
Another way to confirm the demo.txt file is to add the iris-main --create option, which executes the specified shell command before any other iris-main arguments are processed, to the docker run command you executed in Run and Investigate the InterSystems IRIS-based Container and displaying the log after the container has started, as follows:
$ docker run --name iris3 --detach --publish 52773:52773 \
  --volume /nethome/pmartinez/iris_external:/external \
  --env ISC_DATA_DIRECTORY=/external/durable \
  --env ICM_SENTINEL_DIR=/external iris3:test --create "cat demo.txt" --key /external/iris.key \
  --before "/usr/irissys/dev/Cloud/ICM/changePassword.sh /external/password.txt"
bdfe214ef76a34290a8308cddce92162aae14df1ba1bc244e692af3c8d911a3e
$ docker logs -f iris3
[INFO] Executing command cat demo.txt...
[INFO] This is the file added to the image

[INFO] ...executed command cat demo.txt
[INFO] Executing command /usr/irissys/dev/Cloud/ICM/changePassword.sh /external/password.txt...
[INFO] .
Waited 0 seconds for InterSystems IRIS to start
This copy of InterSystems IRIS has been licensed for use exclusively by:
License missing or unreadable.
Copyright (c) 1986-2018 by InterSystems Corporation
Any other use is a violation of your license agreement

[INFO] ...executed command /usr/irissys/dev/Cloud/ICM/changePassword.sh /external/password.txt
[INFO] Copying InterSystems IRIS license key from /external/iris.key to /usr/irissys/mgr...
[INFO] ...copied key
[INFO] Starting InterSystems IRIS instance IRIS...
[INFO] This copy of InterSystems IRIS has been licensed for use exclusively by:
Acme Corp.
Copyright (c) 1986-2018 by InterSystems Corporation
Any other use is a violation of your license agreement
Starting IRIS
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.