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.
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. In the case of an InterSystems IRIS container, a mechanism that accomplishes the following two things is required:
Saving a variety of instance-specific data for use by the instance and by the instance in an upgraded container that replaces it, including the log, journal and WIJ files and the system databases that contain user definitions and other security information as well as audit records.
Indicating where this data is stored, and where it can be found when running the upgraded image to create the upgraded container.
The durable %SYS feature does 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. While the InterSystems IRIS instance remains containerized, its instance-specific data exists outside the container, just like the databases in which application data is stored, persisting it across container and instance restarts and making it available for upgrading the instance. (For more information on upgrading, see Upgrading InterSystems IRIS Containers
To maintain separation of code and data, InterSystems recommends creating all InterSystems IRIS databases on the external file system using durable %SYS or another mechanism. If you do create a database within the container for testing or development purposes by defining it in your Dockerfile, the database file (db_name.DAT
) is created read-only. To enable InterSystems IRIS to mount it as read-write, you must open a shell inside the container, for example with docker exec -it container_name bash
, and use the touch
command on the database file before you start the IRIS instance, for example:
$ sudo docker exec -it try-iris bash
# touch /usr/databases/DBTEST.DAT
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:
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.
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 --init intersystems/iris:2019.1.0.633.0
InterSystems does not support mounting NFS locations as external volumes in InterSystems IRIS containers.
When running InterSystems IRIS containers, always use the --init
option to indicate that an init process should be used as PID 1 within the container, ensuring that the usual responsibilities of an init system are performed inside the container. For more information on this option, see the Docker documentation
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 a /mgr
subdirectory, all of the instance’s internal pointers are reset to that directory and the instance uses the data it contains. If the InterSystems IRIS version of the data does not match the version of the instance, an upgrade is assumed and the data is upgraded to the instance’s version as needed. (For information on upgrading, see Upgrading InterSystems IRIS Containers
If the durable %SYS directory specified by ISC_DATA_DIRECTORY
does not exist, or exists and is empty:
If for any reason the process of copying the durable %SYS data and resetting internal pointers fails, the durable %SYS directory is marked as incomplete; if you try again with the same directory, the data in it is deleted before the durable %SYS process starts.
If the durable %SYS directory specified by the ISC_DATA_DIRECTORY
environment variable already exists and contains data (file or subdirectories) but does not contain a /mgr
subdirectory, no data is copied; the container does not start, and the reason (data other than durable %SYS in the directory) is logged to standard output by the iris-main
program, as described in The iris-main Program
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
When you want to manually verify the location of the durable %SYS directory or pass this location programmatically, you have three options, as follows:
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.
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-06-14 04:01:01