This section describes the durable %SYS feature of InterSystems IRIS, which enables persistent storage of instance-specific data when InterSystems IRIS is run within a container, and explains how to use it.
Overview of InterSystems IRIS Durable %SYS
Separation of code and data is one of the primary advantages of containerization; a running container represents "pure code" that can work with any appropriate data source. However, because all applications and programs generate and maintain operating and historical data such as configuration and language settings, user records, and log files containerization typically must address the need to enable persistence of program-related data on durable data storage.
When you run an InterSystems IRIS image in a Docker container, the initial state of the InterSystems IRIS instance reflects the instance used to create the image often, for example, a newly-installed instance and every time you run a particular image in a container, the instance starts off the same way. If you want instead to upgrade an operating InterSystems IRIS instance by running an upgraded image in a new container, you need to:
Save a variety of instance-specific data for use by the upgraded instance, including the log, journal and WIJ files and the system databases that contain user definitions and other security information as well as audit records.
Indicate where this data can be found when running the upgraded image in a container.
The durable %SYS feature accomplishes this by storing the needed data on an external file system, which is mounted as a volume within the container and identified in an environment variable specified when the container is started. In effect, while the InterSystems IRIS instance remains containerized, the instance-specific data exists outside the container, just like the databases in which application data is stored. As long as the data’s storage location is mounted as a volume and identified in the environment variable when the container is run, the instance has access to and uses this instance-specific data; as long as the containerized instance has the same network location as the previous version, it effectively replaces that version, upgrading InterSystems IRIS.
Contents of the Durable %SYS Directory
The durable %SYS directory, as created when a container is first started, contains a subset of the InterSystems IRIS install tree, including but not limited to:
directory, containing the following:
directory for temporary files.
Durable %SYS activity is logged in the messages.log
file; if you have any problems in using this feature, examine this log for information that may help. For information about how to read this log from outside the container, see The iris-main Program
The InterSystems IRIS license key file, iris.key
, either at container start if it is included in the InterSystems IRIS image or when a license is activated while the container is running. (Activating a License Key
in the "Managing InterSystems IRIS Licensing" chapter of the System Administration Guide
Several InterSystems IRIS system files.
Locating the Durable %SYS Directory
When selecting the location in which this system-critical instance-specific information is to be stored, bear in mind the following considerations:
There must be at least 200 MB of space available on the specified volume for the durable %SYS directory to initialize. For various reasons, however, including operational files such as journal records and the expansion of system databases, the amount of data in the directory can increase significantly.
Running an InterSystems IRIS Container with Durable %SYS
To use durable %SYS, include in the docker run
command the following options:
is the host path to the durable storage location to be mounted by the container, durable_storage
is the name for this location inside the container, and durable_dir
is the name of the durable %SYS directory to be created in the location. For example:
docker run --detach \
--publish 52773:52773 \
--volume /data/dur:/dur \
--env ISC_DATA_DIRECTORY=/dur/iconfig \
--name iris21 intersystems/iris:2018.1.1.633.0
InterSystems does not support mounting NFS locations as external volumes in InterSystems IRIS containers.
option publishes the InterSystems IRIS instance’s web server port (52773 by default) to the host, so that the instance’s management portal can be loaded into a browser on any host.
When you run an InterSystems IRIS container using these options, the following occurs:
The specified external volume is mounted.
If the durable %SYS directory specified by the ISC_DATA_DIRECTORY
environment variable, iconfig/
in the preceding example, already exists and contains durable %SYS data, all of the instance’s internal pointers are reset to that directory and the instance uses the data it contains.
If the durable %SYS directory specified by the ISC_DATA_DIRECTORY
environment variable already exists but does not contain durable %SYS data, no data is copied and the instance runs using the data in the installation tree inside the container, which means that the instance-specific data is not persistent. For this reason you may want to include in scripts a check for this condition prior to running the container.
The specified durable %SYS directory is created.
All of the instance’s internal pointers are reset to the durable %SYS directory and the instance uses the data it contains.
The following illustration shows the relationship between the installation directory of a newly installed InterSystems IRIS container and the external durable %SYS directory, with external application databases also depicted.
InterSystems IRIS Installation Directory and Durable %SYS
Identifying the Durable %SYS Directory Location
When you want to manually verify the location of the durable %SYS directory or pass this location programmatically, you have three options, as follows:
Ensuring that Durable %SYS is Specified and Mounted
When a container is run with the ISC_DATA_DIRECTORY
environment variable, pointers are set to the durable %SYS files only if the specified volume is successfully mounted.
If ISC_DATA_DIRECTORY is specified but the needed --volume /external_host:/durable_storage
option is omitted from the docker run command, the instance fails to start and an error message is generated.
is not specified, the InterSystems IRIS instance uses the instance-specific data within the container, and therefore operates as a new instance.
To use durable %SYS, you must therefore ensure that all methods by which your InterSystems IRIS containers are run incorporate these two options.
Separating File Systems for Containerized InterSystems IRIS
In the interests of performance and recoverability, InterSystems recommends that you locate the primary and secondary journal directories of each InterSystems IRIS instance on two separate file systems, which should also be separate from those hosting InterSystems IRIS executables, system databases and the IRIS.WIJ
file, with the latter optionally on a fourth file system. Following InterSystems IRIS installation, however, the primary and secondary journal directories are set to the same path, install-dir/mgr/journal
, and thus may both be set to /mgr/journal
in the durable %SYS directory when durable %SYS is in use.
After the container is started, you can reconfigure the external locations of the primary and secondary directories using the Management Portal or by editing the iris.cpf
file, as long as the volumes you relocate them to are always specified when running a new image to upgrade the InterSystems IRIS instance. You can also configure separate file systems when launching the container, as described in Running InterSystems IRIS Containers
When the durable %SYS directory is in use, the IRIS.WIJ
file and some system databases are already separated from the InterSystems IRIS executables, which are inside the container. Under some circumstances, colocating the IRIS.WIJ
file with your application databases instead may improve performance.
See File System Recommendations
in the "File System and Storage Configuration Recommendations" chapter of the Installation Guide for more information about separation of file systems for InterSystems IRIS.
Content Date/Time: 2019-03-17 22:37:05