IRIS-CI: A docker image for running InterSystems IRIS in CI environments

Hello all!

As we ObjectScript developers have been experiencing, preparing an environment to run CI related tasks can be quite the chore.
This is why I have been thinking about how we could improve this workflow and the result of that effort is IRIS-CI.

See how it works here.

Quickstart

1.Download the image from the Docker Hub registry:

docker pull rfns/iris-ci:0.5.3

2. Run the container (with the default settings):

docker run --rm --name ci -t -v /path/to/your/app:/opt/ci/app rfns/iris-ci:0.5.3

Notice that volume mounting to /path/to/your/app? This is where the app should be.
And that's it: the only thing required to start running the test suites is the path of the application.

Also, since this is supposed to be a ephemeral and run-once container, there's no need to keep it listed after executing it, that's why there's the --rm flag.

TL;DR;

If you want an example on how to how use it:

Check the usage with my another project dotenv.

Advanced setup

Some projects might need sophisticated setups in order to run the test suites, for such circunstances there's two customization levels:

1. Environment variables
2. Volume overwrite

Environment variables

Environment variables are the most simple customization format and should suffice for most situations.

There's two ways to provide an environment variable:

• -e VAR_NAME="var value" while using docker run.
• By providing a .env file by mounting an extra volume for docker run like this: -v /my/app/.env:/opt/ci/.env.

NOTE: In case a variable is defined in both formats, using the -e format takes precedence over using a .env file.

Types of environment variables

• Variables prefixed with CI_{NAME} are passed down as name to the installer manifest.
• Variables prefixed with TESPARAM_{NAME}are passed down as NAME to the unit test manager's UserFields property.
• TEST_SUITEand TEST_CASE to control where to locate and which test case to target.

Every variable is available to read from the configuration.Envs list, which is passed down through Run and OnAfterRun class methods.

If TEST_CASE is not specified then the recursive flag will be set.

In a project with many classes it might be interesting to at least define the TEST_SUITE and reduce the search scope due to performance concerns.

Volume overwrite

This image ships with a default installer that's focused on running test suites. But it's possbile to overwrite the following files in order to make it execute different tasks like: generating a XML file for old Caché versions.

• /opt/ci/App/Installer.cls
• /opt/ci/Runner.cls

For more details on how to implement them, please check the default implementations:

Installer.cls
Runner.cls

TIP: Before overwriting the default Installer.cls check if you really need to, because the current implementation also allows to create configurated web applications.

EDIT: Link added.