Configuration Merge in Deployment

Deploying an InterSystems IRIS Container with a Merge File

When deploying an InterSystems IRIS container, the environment variable and merge file can be included in the following ways:

• Include them in the script or docker-compose.yml file you are using for deployment.

  In the following sample deployment script, the merge file specified by ISC_CPF_MERGE_FILE, as well as the license key, are staged on the external volume specified for durable %SYS by ISC_DATA_DIRECTORY so they are accessible inside the container.

  #!/bin/bash
  # script for quick demo and quick InterSystems IRIS image testing
  
  # Definitions to toggle_________________________________________
  container_image="intersystems/iris:latest-em"
  
  # the docker run command
  
  docker run -d 
    -p 9091:1972 
    -v /data/durable263:/durable 
    -h iris 
    --name iris 
    --cap-add IPC_LOCK 
    --env ISC_DATA_DIRECTORY=/durable/irisdata
    --env ISC_CPF_MERGE_FILE=/durable/merge/CMF.cpf
    $container_image 
    --key /durable/key/iris.key 
  

  
  Note:

  The image tags shown in this document are examples only. Please go to the InterSystems Container RegistryOpens in a new tab (ICR) to browse current repositories and tags.

  This sample docker-compose.yaml file contains the same elements as the deployment script.

  version: '3.2'
  
  services:
    iris:
      image: intersystems/iris:latest-em
      command: --key /durable/key/iris.key
      hostname: iris
  
      ports:
      # 1972 is the superserver default port
      - "9091:1972"
  
      volumes:
      - /data/durable263:/durable
  
      environment:
      - ISC_DATA_DIRECTORY=/durable/irisdata
      - ISC_CPF_MERGE_FILE=/durable/merge/CMF.cpf
  
  

  

• Include the merge file in the container image and the environment variable in the script or Docker compose file used in deployment.

  When creating a custom InterSystems IRIS container image by starting with an InterSystems IRIS image from InterSystems and adding your own code and dependencies, you can execute the iris merge command in the Dockerfile to reconfigure the InterSystems IRIS instance contained in the image. For example, you can run the iris merge command with a merge file with [Actions] parameters to add namespaces and databases to the instance, which will then be present on the instance in every container created from your custom image. This method is explained and illustrated in Creating InterSystems IRIS Images in Running InterSystems Products in Containers.

  If you want the containerized instances to continue to use the merge file you placed in the container, you can set ISC_CPF_MERGE_FILE in your script or compose file to the location of this file. You can also run an additional, separate merge during deployment using a merge file positioned on the durable SYS volume, as illustrated above; if you plan to do this, add a command in the Dockerfile to remove the included merge file after it has been applied to the instance.

For examples of use cases for automated deployment using configuration merge, see Useful Update parameters in automated deployment and Useful Action parameters in automated deployment.

Installing InterSystems IRIS from a Kit with a Merge File

To apply a merge file when installing InterSystems IRIS from a kit, manually or in a script, you must separate installation from startup, using the steps below.

On UNIX® or Linux system:

1. Install the instance without starting it by preceding the irisinstall or irisinstall_silent script with the ISC_PACKAGE_STARTIRIS parameter, as follows:

   ISC_PACKAGE_INSTANCENAME="IRIS27" ISC_PACKAGE_STARTIRIS="N" /tmp/iriskit/irisinstall
   

   

2. Start the instance with the iris start command, preceding it with the ISC_CPF_MERGE_FILE variable, as follows:

   ISC_CPF_MERGE_FILE=/tmp/iriskit/CMF/merge.cpf iris start IRIS27
   

   

On a Windows system:

1. Install and start the instance, for example:

   IRIS-2023.2.0.227.0-win_x64.exe /instance IRIS27 INSTALLDIR=C:\InterSystems\IRIS27
   

   

2. When the instance is fully started, use the iris merge command (as described in Reconfigure an existing instance using configuration merge) to apply your merge file:

   iris merge IRIS27 C:\InterSystems\IRIS27\merge.cpf
   

   

Using a Merge File when Deploying with the InterSystems Kubernetes Operator

KubernetesOpens in a new tab is an open-source orchestration engine for automating deployment, scaling, and management of containerized workloads and services. The InterSystems Kubernetes OperatorOpens in a new tab (IKO) extends the Kubernetes API with the IrisCluster custom resource, which can be deployed as an InterSystems IRIS sharded cluster, distributed cache cluster, or standalone instance (all optionally mirrored) on any Kubernetes platform. The IKO also adds InterSystems IRIS-specific cluster management capabilities to Kubernetes, enabling automation of tasks like adding nodes to a cluster, which you would otherwise have to do manually by interacting directly with the instances.

When deploying with the IKO, you use a Kubernetes ConfigMapOpens in a new tab to integrate one or more merge files into the deployment process. For detailed information, see Create configuration files and provide a config map for themOpens in a new tab in Using the InterSystems Kubernetes Operator.

See Also

• Best Practices for Configuration Merge

• Useful Update Parameters in Automated Deployment

• Useful Action Parameters in Automated Deployment