Skip to main content

Creating InterSystems IRIS Images

Creating InterSystems IRIS Images

For most use cases, the simplest and least error-prone approach to creating a custom Docker image for InterSystems IRIS is to base the Dockerfile on an existing image from InterSystems, in which InterSystems IRIS is already installed with the iris-main program as the entrypoint. You can then add the dependencies relevant to your own application solution and start the InterSystems IRIS instance, optionally use the configuration merge featureOpens in a new tab to modify its configuration, and issue other commands to it.

For example, suppose you want to create an InterSystems IRIS image that includes your application and the two predefined databases it requires. You can create a Dockerfile to do the following (as illustrated in the example following the steps):

  1. Start with an InterSystems IRIS image as base.

  2. Switch to user root and upgrade the base’s third-party dependencies.

    Important:

    Upgrading the packages in the base is a best practice that helps avoid security vulnerabilities.

  3. Switch back to the instance owner user, irisuser/51773 (see Ownership and Directories).

  4. Copy in a file containing the application code.

  5. Copy in a configuration merge file to create the needed namespaces and application databases on the instance, change the default password using the PasswordHashOpens in a new tab parameter as described in Authentication and Passwords, and make any other desired configuration changes. Such a merge file might look like this:

    [Startup]
PasswordHash=dd0874dc346d23679ed1b49dd9f48baae82b9062,10000,SHA512
[Actions]
CreateDatabase:Name=DB-A,Directory=/usr/irissys/mgr/DB=A,Size=5368,MaxSize=536871,ResourceName=%DB_%DB-A
CreateDatabase:Name=DB-B,Directory=/usr/irissys/mgr/DB=B,Size=5368,MaxSize=536871,ResourceName=%DB_%DB-B
CreateNamespace:Name=DB-A,Globals=DB-A,Routines=SYS
CreateNamespace:Name=DB-B,Globals=DB-B,Routines=SYS

  6. Start the InterSystems IRIS instance.

  7. Execute the iris merge command with the configuration merge file to reconfigure the instance, including creating the databases.

  8. Shut down the instance.

  9. Copy in prepared IRIS.DAT database files, overwriting those created in the previous step.

  10. Remove the merge file, unless you plan to specify it as the instance’s merge file going forwardusing the ISC_CPF_MERGE_FILE

The following sample Dockerfile illustrates the above steps:

FROM intersystems/iris:latest-em

USER root

RUN apt-get update && apt-get -y upgrade \ 
 && apt-get -y install unattended-upgrades

USER 51773 

COPY application.xml /

COPY merge.cpf /tmp/

RUN iris start IRIS \
 && iris merge IRIS /tmp/merge.cpf \
 && iris stop IRIS quietly

COPY DB-A.DAT /usr/irissys/mgr/DB-A
COPY DB-B.DAT /usr/irissys/mgr/DB-B

RUN rm /tmp/merge.cpf
Important:

Before attempting to build your own InterSystems IRIS image as described in this section, be sure to familiarize yourself with the information in the three sections covering the iris-main program, the durable %SYS feature, and the containerization tools provided with InterSystems IRIS.

Note:

An important consideration when creating Docker images is image size. Larger images take longer to download and require more storage on the target machine. A good example of image size management involves the InterSystems IRIS journal files and write image journal (WIJ). Assuming that these files are relocated to persistent storage outside the container (where they should be), as described in Durable %SYS for Persistent Instance Data, you can reduce the size of an InterSystems IRIS or application image by deleting these files from the installed InterSystems IRIS instance within the container.

To clone user-defined databases like those included in the example to the durable data location created by durable %SYS, the database files you copy in must be writable.

If for any reason you want to remove the contents of the messages.log or console.log files after InterSystems IRIS is installed, so that when the instance starts in the container one or both of these files is empty, do not delete the file(s), because the iris-main program treats a missing log file as a fatal error. Instead, you can empty them, reducing their size to zero.

In exploring this approach, you can use the InterSystems IRIS Community Edition image described in Downloading the InterSystems IRIS Docker Image as a base image. Bear in mind, however, that it includes some functionality restrictions.

For an example of using this approach to create an InterSystems IRIS image that includes a Web Gateway instance and a web server, go to https://github.com/intersystems-community/webgateway-examples/tree/master/demo-dockerfileOpens in a new tab

FeedbackOpens in a new tab