Topic outline

• Deploying and Customizing InterSystems IRIS Containers

  Deploying and Customizing InterSystems IRIS Containers

  Get an overview of InterSystems IRIS® data platform containers in this quick, hands-on exercise. Discover the purpose and benefits of containers, and see how they are implemented. Learn how to add a license key, save an image, and create a durable data directory.

  In this exercise, you will take on the role of a developer who needs to create a custom containerized deployment of InterSystems IRIS. You will first acquire an InterSystems IRIS image and a license key. From there, you can create and start a container. You will use Docker as your containerization platform.

  In the second part of the exercise, you will change the InterSystems IRIS instance running in the container, then commit the changed container as a new image. Finally, you will run a container from the second image using the durable %SYS feature to store instance-specific data external to the container.

  Watch the video to learn about the benefits of containers, then try the exercise below!
• Collapse allExpand all
  Set up your environment and run an InterSystems IRIS container

  Set up your environment and run an InterSystems IRIS container

  Start by creating an environment capable of running InterSystems containers. You will pull an image from the InterSystems Container Repository, identify a license key, and run a container.

  • Launch a virtual machine

    For this activity, you will be provided with an Ubuntu 20.04 virtual machine (VM) as your server. This VM contains a fresh Ubuntu installation, as well as tools such as VS Code and a Google Chrome browser.

    Docker Engine has already been installed for you on the VM; it is an open-source containerization technology combined with a workflow for building and running containerized applications. A platform like this is needed to run any container.

    Note:

    You can use your own server to complete this exercise rather than the VM provided. One of the benefits of containers is the ability to deploy on any server with a containerization engine, regardless of operating system.
    
    If you follow along with this exercise on your own server, you will need to adapt the instructions and terminal commands for your operating system. On Windows, you can execute the instructions in the command line or Windows PowerShell window, opened with Run as administrator. Do not use PowerShell ISE.

    To install Docker Engine on your own server, refer to the Docker Engine installation overview.

    1. Click the button below to launch the VM.
    2. Once the VM has launched, click the link; it will open in a new tab.
    3. Log in with the following credentials:
       • Username: Student
       • Password: LearningServices7
    4. Click the Fit to Window icon in the toolbar at the top to enlarge the default display for your VM. This also ensures your full screen is visible and nothing is cut off.

    
    

  • You must be logged in to launch this VM.

    • Log in with your existing account.
    • Don't have an InterSystems account? Create a new account.
  • Open the file of Terminal commands

    Throughout this exercise, you may want to use the terminal-commands.txt file on the VM desktop instead of typing Terminal commands.

    1. Open terminal-commands.txt on the VM desktop.

    
    

    When following the exercise steps below, highlight a command in the file, then right-click the command and select Copy. Paste commands in the Terminal by right-clicking and then clicking Paste.

    
    

  • Download the InterSystems IRIS image

    To make the InterSystems IRIS image available to Docker Engine, you must download it to the system you are working on. In this step, you will download an image from the InterSystems Container Repository.

    1. Locate the latest version of InterSystems IRIS Community Edition:
       1. Go to the InterSystems Container Repository.
       2. On the left, expand InterSystems IRIS Community Edition > iris-community.
       3. Find the latest version string not labeled linux-amd or linux-arm and write it down.
    2. Download an InterSystems IRIS image by running the following command, replacing <version string> with the string you wrote down in the previous step:
       Begin code.
       sudo docker pull containers.intersystems.com/intersystems/iris-community:<version string>
       End code.
    3. Since you are running a sudo command, you will be prompted for the password. Enter LearningServices7, the password for the Student user.
    Note:
    If your docker pull command fails with an unauthorized error message, verify you are pulling the latest version from the InterSystems Container Repository.
    4. To view the images on your system available to Docker Engine, run this command:
       sudo docker images

    
    

    

  • Add the license key to the external storage location

    Any InterSystems IRIS instance requires a license key, even when running in a container. A license key cannot be included in an InterSystems IRIS container image, so it must be copied into a container after it is started.

    The image you are using in this exercise is the InterSystems IRIS Community Edition, which comes with a free temporary license key. While you do not need to add a license key to this image, you can familiarize yourself with the process of adding a license key by following the steps below.

    1. Return to the Ubuntu command line.
    2. To create an external storage location, run the following command:
       Begin code.
       sudo mkdir -vp /usr/local/etc/iris/external
       End code.
    
    

    

    3. Add the license key in the external storage location. Use the command below to copy the license key from its current location—the downloads folder in the VM—and put it in the external storage location you just made.
       Begin code.
       sudo cp /home/student/Downloads/iris.key /usr/local/etc/iris/external/iris.key
       End code.

    The InterSystems Container Repository (ICR) includes repositories for all available images. Customers can pull released images of InterSystems IRIS from the ICR after authenticating, then follow the steps above to prepare a license key.

  • Run a container from the InterSystems IRIS image

    Now that you have made the InterSystems IRIS image available on your local machine, created an external storage location, and put your license key in place, you are ready to create and start a container.

    1. Return to the Ubuntu command line.
    2. To create and start the container, run the following command, replacing <version string> with your version:
       Begin code.

       sudo docker run --name iris --detach --publish 52773:52773
       --volume /usr/local/etc/iris/external:/external
       containers.intersystems.com/intersystems/iris-community:<version string>
       --key /external/iris.key

       End code. The --volume option creates a mounted volume in the container that represents a location on the host file system, so that both the host and the container can access it. With this option, the InterSystems IRIS instance in the container can access and use the license key from the host system.
       
       After creating the container, Docker outputs the UUID long identifier. The first 12 characters make up the UUID short identifier, which can be used to identify the container in the following step.
    
    
    3. To view the status of your container, run the following command:
       sudo docker ps -a

    Your iris container should appear in the printed list with a status of Up or Up N seconds (health: starting).

    
    

• Create a custom InterSystems IRIS container image

  Create a custom InterSystems IRIS container image

  In this section, you will make a change in the running container. Then, you will commit the container as a new image and run a new container from it. You will verify that the change you made and committed to your new image is reflected in the new container.

  You will also use durable %SYS, a useful feature for persisting instance-specific data and any changes you have made to an instance. Because this data is saved outside the container, it can be used in another InterSystems IRIS container. To practice using this feature, you will change a setting in the InterSystems IRIS instance in your container and see it reflected in the durable data outside the container.
  

  • Change the instance and commit the container as a new image

    When you make changes 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 from which you created the container, but it 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 opening Chrome and going to ubuntu:52773/csp/sys/UtilHome.csp.
    2. Log in with these credentials:
       • Username: SuperUser
       • Password: SYS
    3. You will be prompted to change the password for the default user. Set a new password and make a note of it.
    4. From the home page, navigate to the Namespaces page by going to System Administration > Configuration > System Configuration > Namespaces, then click Create New Namespace.
    5. Create a new namespace:
       • Name of the namespace: USER2
       • Copy from: USER
       • Enable namespace for interoperability productions: cleared
    
    

    

    6. Click Save and confirm that you want to copy all properties and mappings, then click Close on the Copy Namespace Mappings page to return to the Namespaces page. The USER2 namespace is now listed. You have altered the instance in the container.
    7. In the Ubuntu terminal, use the following commands to stop the container and commit it as a new image called custom/iris2:test: Begin code.

       sudo docker stop iris
       sudo docker commit iris custom/iris2:test

       End code.
    
    

    

    8. List the available images, including the new one:
       Begin code.
       sudo docker images
       End code.
    
    

    

    9. Remove the container created from the original InterSystems IRIS image: Begin code.
       sudo docker rm iris
       End code.
  • Run and investigate the second InterSystems IRIS-based container

    To run the newly created image as a container, follow these steps:

    1. Create a new external storage location for this container, which also contains the license key, by copying the old one using the following command:
       Begin code.
       sudo cp -r /usr/local/etc/iris /usr/local/etc/iris2
       End code.
    2. Create a durable data directory within the external storage location. Set the permissions on the new directory so that when the irisowner user within the container edits the mounted volume within the container, the edits can be made on the host system as well. Use the following commands:
       Begin code.

       sudo mkdir /usr/local/etc/iris2/external/durable

       End code. Begin code.

       sudo chown -R 51773:51773 /usr/local/etc/iris2/external/durable

       End code.
    3. Execute the following docker run command to create and run the new iris2 container.Begin code.

       sudo docker run --name iris2 --detach --publish 52773:52773
       --volume /usr/local/etc/iris2/external:/external
       --env ISC_DATA_DIRECTORY=/external/durable
       custom/iris2:test
       --key /external/iris.key

       End code. Note that this command has a few differences from the previous one:
       • The option –env ISC_DATA_DIRECTORY=pathname identifies the durable %SYS directory, the location in which the persistent data of the InterSystems IRIS instance is written. The durable %SYS directory should be in a subdirectory of a mounted volume.
       • The custom image you created is specified instead of the one you pulled from the ICR.
       • The name of this container is now iris2.
    4. When the docker run command has completed, list the container and check its status by running sudo docker ps -a.

    
    

    The "docker run" command creates and starts a container and prints the container ID to the terminal. The "docker ps" command prints information about active containers.

  • Confirm the change you committed from the altered InterSystems container

    In a previous step, you added a namespace to the containerized InterSystems IRIS Community Edition instance and committed the container as a new image, custom/iris2:test. The namespace you added, USER2, should therefore exist in the instance running in iris2, which was created from custom/iris2:test. To confirm this, do the following:

    1. Open the Management Portal, at ubuntu:52773/csp/sys/UtilHome.csp and log in as SuperUser, using the updated password you set in the first container.
    2. From the home page, navigate to 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. Back in the Ubuntu terminal, display the contents of the external storage directory to see the instance-specific data written outside the container: Begin code.
       sudo ls /usr/local/etc/iris2/external
       End code. Begin code.
       sudo ls /usr/local/etc/iris2/external/durable
       End code. Begin code.
       sudo ls /usr/local/etc/iris2/external/durable/mgr
       End code.
    2. Return to the Management Portal for the InterSystems IRIS instance in the container and go to the Journal Settings page by clicking System Administration > Configuration > System Configuration > Journal Settings.
    3. Change the Secondary journal directory setting and click Save.
       • Current setting: /external/durable/mgr/journal/
       • Change the setting to: /external/durable/mgr/journal2/
    4. Return to the command line and list the mgr subdirectory of the durable %SYS directory again: Begin code.
       ls /usr/local/etc/iris2/external/durable/mgr
       End code. 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 same volume mount and ISC_DATA_DIRECTORY options, those changes will be inherited by the new instance.

• What's next?

  What's next?

  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.

  • Review options for deploying InterSystems IRIS, including containers, ICM, and Kubernetes (learning path, 3h 15m).
  • Learn more about using InterSystems Cloud Manager to deploy containerized InterSystems IRIS instances in the InterSystems Cloud Manager Guide (documentation).
  • Find more information about running InterSystems products in containers, including the use of license keys (documentation, 1h).
  • Learn how to find available InterSystems IRIS images in the InterSystems Container Repository, and see how to use your WRC credentials to authenticate to the repository so you can download an image (documentation, 5m).
  • Read more about saving and using custom container images Docker Documentation.
  • Read Using InterSystems IRIS Containers with Docker for Windows (InterSystems Developer Community, 5m) and the Quick Start Guide in Docker documentation.

  • Share Your Feedback!