docs.intersystems.com
InterSystems IRIS Data Platform 2019.2  /  First Look: InterSystems Products in Docker Containers  /  Try It! Create Your Own InterSystems IRIS-based Container

InterSystems: The power behind what matters   
Search:  


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 Products 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 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.)
  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 --init --detach --publish 52773:52773 \
      --volume /nethome/pmartinez/iris_external:/external \
      --env ISC_DATA_DIRECTORY=/external/durable \
      iris3:test
      --key /external/iris.key \
    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:
    The --key option is not needed with the InterSystems IRIS Community Edition image (see Download the InterSystems IRIS Docker Image), which comes with a free built-in license.
    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 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: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 and log in, as described in Change the Instance and Commit the Container as a New Image.
  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
    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, 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.
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 --init --detach --publish 52773:52773 \
  --volume /nethome/pmartinez/iris_external:/external \
  --env ISC_DATA_DIRECTORY=/external/durable \
  --create "cat demo.txt" --key /external/iris.key \
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] .
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] 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


Send us comments on this page
View this article as PDF   |  Download all PDFs
Copyright © 1997-2019 InterSystems Corporation, Cambridge, MA
Content Date/Time: 2019-09-19 06:44:29