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
- 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:
- Environment variables
- 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 usingdocker 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 asname
to the installer manifest. - Variables prefixed with
TESPARAM_{NAME}
are passed down asNAME
to the unit test manager's UserFields property. TEST_SUITE
andTEST_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:
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.