The iris-main Program
The iris-main Program
There are several requirements an application must satisfy in order to run in a container. The iris-main program was developed by InterSystems to enable InterSystems IRIS and its other products to meet these requirements.
The main process started by the docker run command, called the entrypoint, is required to block (that is, wait) until its work is complete. In the case of a long-running entrypoint application, this process should block until it's been intentionally shut down.
InterSystems IRIS is typically started using the iris start command, which spawns a number of InterSystems IRIS processes and returns control to the command line. Because it does not run as a blocking process, the iris command is unsuitable for use as the Docker entrypoint application.
The iris-main program solves this problem by starting InterSystems IRIS and then continuing to run as the blocking entrypoint application. The program also gracefully shuts down InterSystems IRIS when the container is stopped, and has a number of useful options.
To use it, add the iris-main binary to a Dockerfile and specify it as the entrypoint application, for example:
ADD host_path/iris-main /iris-main ENTRYPOINT ["/iris-main"]
The iris-main program confirms that certain Linux capabilities required by the InterSystems IRIS container — for example, CAP_SETUID and CAP_SETGID — before starting InterSystems IRIS. Those that are always required are typically granted by default in container runtime environments; a few that are required only in some circumstances may not be. If one or more capabilities are not present, iris-main logs an error and exits without starting the instance. This capability check can be disabled by including the iris-main option --check-caps false.
Docker imposes these additional requirements on the entrypoint application:
Graceful shutdown with docker stop
Docker expects the main container process to shut down in response to the docker stop command.
The default behavior of docker stop is to send the SIGTERM signal to the entrypoint application, wait 10 seconds, and then send the SIGKILL signal. Kubernetes operates in a similar fashion. The iris-main program intercepts SIGTERM and SIGINT and executes a graceful shutdown of the instance.Important:
If the instance is particularly busy when the docker stop command is issued, 10 seconds may not be long enough to bring it to a complete stop, which may result in Docker sending a SIGKILL. SIGKILL cannot be trapped or handled, and is similar to powering off a machine in terms of program interruption and potential data loss. If your InterSystems IRIS container receives a SIGKILL, on the next start it will engage in normal InterSystems IRIS crash recovery procedures. To prevent this, use the --time option with your docker stop command, or the terminationGracePeriodSeconds value in your Kubernetes configuration, to specify a wait time longer than 10 seconds.
Graceful startup with docker start
When a container is stopped by means other than the docker stop command, for example when the Docker daemon is restarted or the host is rebooted, the entrypoint application must carry out whatever tasks are required to bring the container back up to a stable running state in response to the docker start command. As of this writing, iris-main does not have any special handling for an InterSystems IRIS instance that was brought down ungracefully, and instead relies on existing InterSystems IRIS functionality; it does, however, execute all operations specified using the --before and --after options (see the table that follows).
Logging to standard output for capture by docker logs
Docker expects the entrypoint application to send output to the container’s standard output so the docker logs command can display it. The iris-main program adheres to this by default, sending all InterSystems IRIS log content to standard output. If you wish, you can instead direct the output of a different file in the container — for example, your application’s log — to container output using the -log option, for example:
docker run iris --log /myapp/logs/myapp.log
When a fatal error occurs, iris-main directs you to the messages log (see Log Files in the install-dir/mgr Directory in the Monitoring Guide) for more information about the error.Note:
The iris-main program is configured to append its logging output to previous output, which ensures that when the InterSystems IRIS container is restarted, some record of how and why it shut down remains available.
In addition to addressing the issues discussed in the foregoing, iris-main provides a number of options to help tailor the behavior of InterSystems IRIS within a container. The options provided by iris-main are shown in the list that follows; examples of their use are provided in Running InterSystems IRIS Containers.
Options for iris-main appear after the image name in a docker run command, while the Docker options appear before it. As with the docker command, the options have a long form in which two hyphens are used and a short form using only one.
|Sets the name of the InterSystems IRIS instance to start or stop. (The instance in a container distributed by InterSystems is always named IRIS.)||IRIS|
|Stops InterSystems IRIS (using iris stop) on container shutdown||true|
|Starts InterSystems IRIS (using iris start) on container startup||true|
|Starts InterSystems IRIS in single-user access mode||false|
|Copies the specified InterSystems IRIS license key (see License Keys for InterSystems IRIS Containers) to the mgr/ subdirectory of the install directory.||none|
|Specifies a log file to redirect to standard output for monitoring using the docker logs command.||none|
|Sets the executable to run (such as a shell script) before starting InterSystems IRIS||none|
|Sets the executable to run after starting InterSystems IRIS||none|
|Sets the executable to run after stopping InterSystems IRIS||none|
Execute a custom shell command before any other arguments are processed
Execute a custom shell command after any other arguments are processed
|Change the default password for the predefined InterSystems IRIS accounts to the string contained in the file, and then delete the file.
This option, which is described in Authentication and Passwords, is useful in scripts and other automation; when using it, bear in mind the risks of committing the password to a file for any significant length of time. Even when the default password has been changed, the first manual login to each predefined account after the container starts includes a mandatory default password change.
Starts the ISCAgent on the default ISCAgent port, 2188, on container startup. If false, the ISCAgent does not start, and the --ISCAgentPort option is ignored.
Specifies the port to start the ISCAgent on. Can be used together with --ISCAgent=true.
|--check-caps=false||Disables automatic Linux capability check before InterSystems IRIS is started.||true|
|--version||Prints the iris-main version||N/A|
|Displays usage information and exits||N/A|