Launching IRIS Using Docker
Tags: beginners, iris, best, practices
Published: 2021-02-26 18:15:27

<p align="center" style="text-align:center">
  <span style="font-size:12pt"><span style="font-family:Calibri,sans-serif"><span style="font-size:16.0pt">Launching IRIS Using Docker</span></span></span>
</p>

 

 

<span style="font-size:12pt"><span style="font-family:Calibri,sans-serif">This brief document will walk through the steps to launch IRIS community edition using Docker on the MAC. For those new to Docker, the first two pages explain how to install Docker, and run some basic commands that will be needed to get the IRIS community edition running. Experienced Docker users can skip directly to page three.</span></span>

 

<p style="text-indent:-13.5pt">
   
</p>

  1. <span style="font-size:12pt"><span style="font-family:Calibri,sans-serif">Get Docker Desktop for MAC. This can be downloaded at Docker Hub, but one should look at the requirements before downloading it to ensure it works smoothly. The directions and download link are at: <span class="MsoHyperlink" style="color:#0563c1"><span style="text-decoration:underline"><a href="https://docs.docker.com/docker-for-mac/install/">https://docs.docker.com/docker-for-mac/install/</a></span></span>  Windows installations of Docker require Docker Toolbox, because Docker cannot run natively on Windows. Docker Toolbox creates a virtual machine that Docker runs in for Windows users. Windows users should follow the directions on the Docker website: <span class="MsoHyperlink" style="color:#0563c1"><span style="text-decoration:underline"><a href="https://hub.docker.com/editions/community/docker-ce-desktop-windows">https://hub.docker.com/editions/community/docker-ce-desktop-windows</a></span></span></span></span>

<p style="margin-left:24px; text-indent:-13.5pt">
   
</p>

<ol start="2">
  <li>
    <span style="font-size:12pt"><span style="font-family:Calibri,sans-serif">Experiment with Docker. The first logical command is to determine what docker images are in the local repository. Using the Mac terminal type: <b>docker images</b>. At this stage nothing will be found, but one will see the following headers: Repository, Tag, Image ID, Created, and Size. Now, run a test container by specifying the following at the command line: <b>docker run busybox:1.24 echo “hello world”</b>. Since the busybox image was not found in the docker repository it was “pulled” from docker hub, and the echo command was executed in the container, printing out “hello world” at the command line. Now try executing <b>docker images</b> again, you should now see the busybox image in the local repository. It is important when using Docker to specify both the name of the image and the tag, separating them by a colon. This lets docker know which version of the image to run (e.g. <b>busybox:1.24</b>). When a container is present locally, it will not be downloaded again.</span></span>
  </li>
</ol>

<p style="margin-left:48px">
   
</p>

<p style="margin-left:48px">
   
</p>

<ol start="3">
  <li>
    <span style="font-size:12pt"><span style="font-family:Calibri,sans-serif">Try running another command on the Docker image. Type <b>docker run busybox:1.24 ls /</b>.  One should see a directory listing of directories and files at the root of the container.</span></span>
  </li>
</ol>

 

<ol start="4">
  <li>
    <span style="font-size:12pt"><span style="font-family:Calibri,sans-serif">There are two important options when running a container. The -I flag starts an interactive container, and the -t flag creates a pseudo-TTY that attaches stdin and stdout. Type this: <b>docker run -i -t busybox:1.24</b>. One can now run commands in the container shell, including adding files. Typing <b>exit</b>, will exit the container and shut it down. Any files created while in the container will be lost.</span></span>
  </li>
</ol>

<p style="margin-left:48px">
   
</p>

<ol start="5">
  <li>
    <span style="font-size:12pt"><span style="font-family:Calibri,sans-serif">Containers are normally run in the background (not interactively). The -d flag, which stands for detach runs the container in “detached” mode. Type this command: <b>docker run -d busybox:1.24 sleep 1000</b>. Docker returns immediately the container id, and the container is running. To verify this type <b>docker ps</b>. This will show what containers are running, which in our case is this single container. To see containers that are running and have previously run type <b>docker ps -a</b>. To remove a container when it exits type <b>docker run –rm busybox:1.23 sleep 1</b>. The container will execute but will not be found in the history list using docker ps -a. </span></span>
  </li>
</ol>

<p style="margin-left:48px">
   
</p>

<ol start="6">
  <li>
    <span style="font-size:12pt"><span style="font-family:Calibri,sans-serif">Docker generates funny container “names” when running containers, we can specify the name we want Docker to generate using the –name option. Type <b>docker run –-name mycontainer busybox:1.24</b>. Now when using <b>docker ps -a</b>, one will see then name of the container is mycontainer.</span></span>
  </li>
</ol>

<p style="margin-left:48px">
   
</p>

<ol start="7">
  <li>
    <span style="font-size:12pt"><span style="font-family:Calibri,sans-serif">Docker provides a handy function for getting details on low level information on containers such as IPAddress and Ports. Type <b>docker inspect containerId</b> (replace containerId with one the container ids from docker ps -a). </span></span>
  </li>
</ol>

<p style="margin-left:48px">
   
</p>

<ol start="8">
  <li>
    <span style="font-size:12pt"><span style="font-family:Calibri,sans-serif">Frequently containers run processes that “listen” on a specific port. In order to communicate to the container port from the host, one must map the host port to the container. The format of the command is -p host_port: container_port. If a docker container is running locally, the container IP address is “localhost”. On windows it may be 127.0.0.1. A useful command for troubleshooting is it to check the logfile of the container. This can be easily done using the command <b>docker logs containerId</b> (replace containerId with one the container ids from docker ps -a)</span></span>
  </li>
</ol>

<p style="margin-left:48px">
   
</p>

<ol start="9">
  <li>
    <span style="font-size:12pt"><span style="font-family:Calibri,sans-serif">Containers are actually made up of layers. Starting with the base layer, additional layers are added. Docker provides the <b>history</b> command to list the layers in a container. Type <b>docker history busybox:1.24</b></span></span>
  </li>
</ol>

<p style="margin-left:48px">
   
</p>

<ol start="10">
  <li>
    <span style="font-size:12pt"><span style="font-family:Calibri,sans-serif">There is much more that docker can do, including building more complex images using the commit command or a Dockerfile (refer to: <span class="MsoHyperlink" style="color:#0563c1"><span style="text-decoration:underline"><a href="https://docs.docker.com/">https://docs.docker.com/</a></span></span> ). This brief intro on Docker provides the basics for getting the IRIS community container up and running.</span></span>
  </li>
</ol>

<p style="margin-left:48px">
   
</p>

 

 

 

<p align="center" style="margin-left:54px; text-align:center">
  <span style="font-size:12pt"><span style="font-family:Calibri,sans-serif">Launching the IRIS Container</span></span>
</p>

<p style="margin-left:54px">
   
</p>

  1. <span style="font-size:12pt"><span style="font-family:Calibri,sans-serif">The instructions for using the Docker container for the IRIS Community Edition are found at: <span class="MsoHyperlink" style="color:#0563c1"><span style="text-decoration:underline"><a href="https://hub.docker.com/_/intersystems-iris-data-platform/plans/222f869e-567c-4928-b572-eb6a29706fbd?tab=instructions">https://hub.docker.com/_/intersystems-iris-data-platform/plans/222f869e-567c-4928-b572-eb6a29706fbd?tab=instructions</a></span></span></span></span>

 

<ol start="2">
  <li>
    <span style="font-size:12pt"><span style="font-family:Calibri,sans-serif">One additional Docker command must be explained to configure the password file. Docker containers cannot access the host file system directly. The container must mount a directory made available to it from the host. Initially, Docker for Mac makes the following directories available to be bind/mount into Docker containers: /Users, /Volumes, /private, /tmp.   To store passwords outside the container (remember all files written in the container will disappear on exit), we need to create a file in /Users/yourUserName/external/password.txt. Mounting a volume uses the flag -v and then the hostname followed by a colon and then the container directory.</span></span>
  </li>
</ol>

<p style="margin-left:48px">
   
</p>

<ol start="3">
  <li>
    <span style="font-size:12pt"><span style="font-family:Calibri,sans-serif">Now run the container we the following command: <b>docker run --name irisdb -v ~/external:/external -d store/intersystems/iris:2019.1.0.511.0-community --password-file /external/password.txt.</b> After running this command and checking the status with the command <b>docker ps -a</b>, you should see the following after a couple of minutes:</span></span>
  </li>
</ol>

<p style="margin-left:48px">
   
</p>

<p style="margin-left:48px">
  <span style="font-size:12pt"><span style="font-family:Calibri,sans-serif">CONTAINER ID        IMAGE                                              COMMAND                  CREATED             STATUS                   PORTS               NAMES</span></span>
</p>

<p style="margin-left:48px">
  <span style="font-size:12pt"><span style="font-family:Calibri,sans-serif">d74f2b7a48d5        store/intersystems/iris:2019.1.0.511.0-community   "/iris-main --passwo…"   2 minutes ago       Up 2 minutes (healthy)                  irisdb</span></span>
</p>

<p style="margin-left:48px">
   
</p>

<ol start="4">
  <li>
    <span style="font-size:12pt"><span style="font-family:Calibri,sans-serif">Connect to the container just launched with the command: docker exec -it irisdb iris session iris. This connection will allow us to login to an iris session. The Username is <b>SuperUser</b> and the Password is <b>SYS</b>. IRIS will now ask that the password be changed, as shown below:</span></span>
  </li>
</ol>

<p style="margin-left:48px">
   
</p>

<p style="margin-left:48px">
  <span style="font-size:12pt"><span style="font-family:Calibri,sans-serif">Node: d74f2b7a48d5, Instance: IRIS</span></span>
</p>

<p style="margin-left:48px">
  <span style="font-size:12pt"><span style="font-family:Calibri,sans-serif">Username: SuperUser</span></span>
</p>

<p style="margin-left:48px">
  <span style="font-size:12pt"><span style="font-family:Calibri,sans-serif">Password: ***</span></span>
</p>

<p style="margin-left:48px">
  <span style="font-size:12pt"><span style="font-family:Calibri,sans-serif">Password change required</span></span>
</p>

<p style="margin-left:48px">
  <span style="font-size:12pt"><span style="font-family:Calibri,sans-serif">Please enter a new password</span></span>
</p>

<p style="margin-left:48px">
  <span style="font-size:12pt"><span style="font-family:Calibri,sans-serif">Password: *********</span></span>
</p>

<p style="margin-left:48px">
  <span style="font-size:12pt"><span style="font-family:Calibri,sans-serif">Please retype your new password</span></span>
</p>

<p style="margin-left:48px">
  <span style="font-size:12pt"><span style="font-family:Calibri,sans-serif">Password: *********</span></span>
</p>

<p style="margin-left:48px">
  <span style="font-size:12pt"><span style="font-family:Calibri,sans-serif">USER></span></span>
</p>

<p style="margin-left:48px">
   
</p>

<span style="font-size:12pt"><span style="font-family:Calibri,sans-serif">            Now we can type commands directly at the IRIS terminal command prompt. Such as:</span></span>

 

<span style="font-size:12pt"><span style="font-family:Calibri,sans-serif">            USER>set firstname = "Peter"</span></span>

 

<p style="text-indent:.5in">
  <span style="font-size:12pt"><span style="font-family:Calibri,sans-serif">USER>write firstname</span></span>
</p>

<p style="text-indent:.5in">
  <span style="font-size:12pt"><span style="font-family:Calibri,sans-serif">Peter</span></span>
</p>

<p style="text-indent:.5in">
  <span style="font-size:12pt"><span style="font-family:Calibri,sans-serif">USER></span></span><br /> 
</p>

<p style="margin-left:48px">
  <span style="font-size:12pt"><span style="font-family:Calibri,sans-serif">We can type interactive commands, but what about launching the management portal?<br /><br />Normally, to do this we would open a browser and typing the link: <span class="MsoHyperlink" style="color:#0563c1"><span style="text-decoration:underline"><a href="http://localhost:52773/csp/sys/UtilHome.csp">http://localhost:52773/csp/sys/UtilHome.csp</a></span></span> , but when we do this an error message is displayed, and the localhost site refuses to connect.  Remember the section on port mapping and how containers are isolated from the external network without them? We must map two ports, the IRIS superserver default port at 51773, and the management portal port at 52773.</span></span>
</p>

<p style="margin-left:48px">
   
</p>

<p style="margin-left:48px">
  <span style="font-size:12pt"><span style="font-family:Calibri,sans-serif">In the above case, first stop the command line process by typing <b>Halt</b>. Next stop the container by typing: <b>docker stop [containerid]</b></span></span>
</p>

<p style="margin-left:48px">
   
</p>

<ol start="5">
  <li>
    <span style="font-size:12pt"><span style="tab-stops:28.0pt 56.0pt 84.0pt 112.0pt 140.0pt 168.0pt 196.0pt 224.0pt 3.5in 280.0pt 308.0pt 336.0pt"><span style="text-autospace:none"><span style="font-family:Calibri,sans-serif">Let’s start up this container again with port mapping: <b><span style="font-size:11.0pt"><span style="color:black">docker run -p 51773:51773 -p 52773:52773 -v ~/external:/external -d store/intersystems/iris:2019.1.0.511.0-community --password-file /external/password.txt</span></span></b></span></span></span></span>  
  </li>
</ol>

<p style="margin-left:54px">
  <span style="font-size:12pt"><span style="tab-stops:28.0pt 56.0pt 84.0pt 112.0pt 140.0pt 168.0pt 196.0pt 224.0pt 3.5in 280.0pt 308.0pt 336.0pt"><span style="text-autospace:none"><span style="font-family:Calibri,sans-serif">Now opening a browser window should with the link <span class="MsoHyperlink" style="color:#0563c1"><span style="text-decoration:underline"><a href="http://localhost:52773/csp/sys/UtilHome.csp">http://localhost:52773/csp/sys/UtilHome.csp</a></span></span> , should reveal the management portal.</span></span></span></span>
</p>

<p style="margin-left:54px">
   
</p>

<p style="margin-left:54px">
   
</p>

<ol start="6">
  <li>
    <span style="font-size:12pt"><span style="tab-stops:28.0pt 56.0pt 84.0pt 112.0pt 140.0pt 168.0pt 196.0pt 224.0pt 3.5in 280.0pt 308.0pt 336.0pt"><span style="text-autospace:none"><span style="font-family:Calibri,sans-serif"><span style="font-size:11.0pt"><span style="color:black">Even though we managed to use the password file on the host system, we were not able to persist the password change we made earlier. Why not? IRIS must be must be made aware of the directory of where to store it persistent configuration settings. We must add a flag --env ISC_DATA_DIRECTORY=/external/iconfig. </span></span></span></span></span></span>
  </li>
</ol>

 

<p style="margin-left:48px">
  <span style="font-size:12pt"><span style="tab-stops:28.0pt 56.0pt 84.0pt 112.0pt 140.0pt 168.0pt 196.0pt 224.0pt 3.5in 280.0pt 308.0pt 336.0pt"><span style="text-autospace:none"><span style="font-family:Calibri,sans-serif"><span style="font-size:11.0pt"><span style="color:black">Thus, the full command reads: <b>docker run -p 51773:51773 -p 52773:52773 -v ~/external:/external --env ISC_DATA_DIRECTORY=/external/ifconfig -d store/intersystems/iris:2019.1.0.511.0-community --password-file /external/password.txt</b></span></span></span></span></span></span>
</p>

 

 

<ol start="7">
  <li>
    <span style="font-size:12pt"><span style="tab-stops:28.0pt 56.0pt 84.0pt 112.0pt 140.0pt 168.0pt 196.0pt 224.0pt 3.5in 280.0pt 308.0pt 336.0pt"><span style="text-autospace:none"><span style="font-family:Calibri,sans-serif"><span style="font-size:11.0pt"><span style="color:black">At this point, you should not need to change the password on the management portal that you set initially.</span></span></span></span></span></span>
  </li>
</ol>

 

<ol start="8">
  <li>
    <span style="font-size:12pt"><span style="tab-stops:28.0pt 56.0pt 84.0pt 112.0pt 140.0pt 168.0pt 196.0pt 224.0pt 3.5in 280.0pt 308.0pt 336.0pt"><span style="text-autospace:none"><span style="font-family:Calibri,sans-serif"><span style="font-size:11.0pt"><span style="color:black">The command string is difficult to remember, and another approach is to store it in a file that a related docker utility called docker-compose employs. The file is of type yaml or yml, and must be named docker-compose. The docker-compose file offers numerous ways to configure any number of containers and their dependencies. However, for our purposes a simpler file is all that is necessary. Here are the contents (the file must be labeled <b>docker-compose.yml</b>):</span></span></span></span></span></span>
  </li>
</ol>

<p style="margin-left:48px">
   
</p>

<p style="margin-left:48px">
   
</p>

<p style="margin-left:48px">
   
</p>

<span style="font-size:12pt"><span style="tab-stops:28.0pt 56.0pt 84.0pt 112.0pt 140.0pt 168.0pt 196.0pt 224.0pt 3.5in 280.0pt 308.0pt 336.0pt"><span style="text-autospace:none"><span style="font-family:Calibri,sans-serif"><span style="font-size:11.0pt"><span style="color:black">         version: '3'</span></span></span></span></span></span>

<span style="font-size:12pt"><span style="tab-stops:28.0pt 56.0pt 84.0pt 112.0pt 140.0pt 168.0pt 196.0pt 224.0pt 3.5in 280.0pt 308.0pt 336.0pt"><span style="text-autospace:none"><span style="font-family:Calibri,sans-serif"><span style="font-size:11.0pt"><span style="color:black">         services:</span></span></span></span></span></span>

<span style="font-size:12pt"><span style="tab-stops:28.0pt 56.0pt 84.0pt 112.0pt 140.0pt 168.0pt 196.0pt 224.0pt 3.5in 280.0pt 308.0pt 336.0pt"><span style="text-autospace:none"><span style="font-family:Calibri,sans-serif"><span style="font-size:11.0pt"><span style="color:black">   I      iris:</span></span></span></span></span></span>

<span style="font-size:12pt"><span style="tab-stops:28.0pt 56.0pt 84.0pt 112.0pt 140.0pt 168.0pt 196.0pt 224.0pt 3.5in 280.0pt 308.0pt 336.0pt"><span style="text-autospace:none"><span style="font-family:Calibri,sans-serif"><span style="font-size:11.0pt"><span style="color:black">           image: store/intersystems/iris:2019.1.0.511.0-community</span></span></span></span></span></span>

<span style="font-size:12pt"><span style="tab-stops:28.0pt 56.0pt 84.0pt 112.0pt 140.0pt 168.0pt 196.0pt 224.0pt 3.5in 280.0pt 308.0pt 336.0pt"><span style="text-autospace:none"><span style="font-family:Calibri,sans-serif"><span style="font-size:11.0pt"><span style="color:black">          ports:</span></span></span></span></span></span>

<span style="font-size:12pt"><span style="tab-stops:28.0pt 56.0pt 84.0pt 112.0pt 140.0pt 168.0pt 196.0pt 224.0pt 3.5in 280.0pt 308.0pt 336.0pt"><span style="text-autospace:none"><span style="font-family:Calibri,sans-serif"><span style="font-size:11.0pt"><span style="color:black">       - "51773:51773"</span></span></span></span></span></span>

<span style="font-size:12pt"><span style="tab-stops:28.0pt 56.0pt 84.0pt 112.0pt 140.0pt 168.0pt 196.0pt 224.0pt 3.5in 280.0pt 308.0pt 336.0pt"><span style="text-autospace:none"><span style="font-family:Calibri,sans-serif"><span style="font-size:11.0pt"><span style="color:black">       - "52773:52773"</span></span></span></span></span></span>

<span style="font-size:12pt"><span style="tab-stops:28.0pt 56.0pt 84.0pt 112.0pt 140.0pt 168.0pt 196.0pt 224.0pt 3.5in 280.0pt 308.0pt 336.0pt"><span style="text-autospace:none"><span style="font-family:Calibri,sans-serif"><span style="font-size:11.0pt"><span style="color:black">          volumes:</span></span></span></span></span></span>

<span style="font-size:12pt"><span style="tab-stops:28.0pt 56.0pt 84.0pt 112.0pt 140.0pt 168.0pt 196.0pt 224.0pt 3.5in 280.0pt 308.0pt 336.0pt"><span style="text-autospace:none"><span style="font-family:Calibri,sans-serif"><span style="font-size:11.0pt"><span style="color:black">           - ~/external:/external</span></span></span></span></span></span>

<span style="font-size:12pt"><span style="tab-stops:28.0pt 56.0pt 84.0pt 112.0pt 140.0pt 168.0pt 196.0pt 224.0pt 3.5in 280.0pt 308.0pt 336.0pt"><span style="text-autospace:none"><span style="font-family:Calibri,sans-serif"><span style="font-size:11.0pt"><span style="color:black">          environment:</span></span></span></span></span></span>

<span style="font-size:12pt"><span style="tab-stops:28.0pt 56.0pt 84.0pt 112.0pt 140.0pt 168.0pt 196.0pt 224.0pt 3.5in 280.0pt 308.0pt 336.0pt"><span style="text-autospace:none"><span style="font-family:Calibri,sans-serif"><span style="font-size:11.0pt"><span style="color:black">          - ISC_DATA_DIRECTORY=/external/ifconfig</span></span></span></span></span></span>

<span style="font-size:12pt"><span style="tab-stops:28.0pt 56.0pt 84.0pt 112.0pt 140.0pt 168.0pt 196.0pt 224.0pt 3.5in 280.0pt 308.0pt 336.0pt"><span style="text-autospace:none"><span style="font-family:Calibri,sans-serif"><span style="font-size:11.0pt"><span style="color:black">     entrypoint: /iris-main --password-file /external/password.txt</span></span></span></span></span></span>

 

 

<span style="font-size:12pt"><span style="tab-stops:28.0pt 56.0pt 84.0pt 112.0pt 140.0pt 168.0pt 196.0pt 224.0pt 3.5in 280.0pt 308.0pt 336.0pt"><span style="text-autospace:none"><span style="font-family:Calibri,sans-serif"><span style="font-size:11.0pt"><span style="color:black">         Notice the similarity to the command line with a few additions. First the version of the docker-compose file is version ‘3’. We have one service named ‘iris’ or another name of your choosing. The image, ports, volumes, and environment are self-explanatory. The last line “entrypoint” is the program that is run (including options, in the case the location of the password file). </span></span></span></span></span></span>

 

<span style="font-size:12pt"><span style="font-family:Calibri,sans-serif"><span style="font-size:11.0pt"><span style="color:black">Now if we type <b>docker-compose up -d</b>. The container is spun up the same as before. To stop the container type <b>docker-compose down</b>. More literature on docker-compose options are found on the Docker website. </span></span><span class="MsoHyperlink" style="color:#0563c1"><span style="text-decoration:underline"><a href="https://docs.docker.com/compose/">https://docs.docker.com/compose/</a></span></span></span></span>

 

<p style="margin-left:54px">
   
</p>

<p style="margin-left:48px">
   
</p>