sagait/engine repository overview

⁠Table of Contents

• Quick Reference⁠
• What is this image?⁠
• Bundled Plugins⁠
• Supported Images⁠
• Supported Architectures⁠
• How to use this image⁠
  • Start an Engine instance⁠
  • Using docker stack deploy or docker compose⁠
  • Environment Variables⁠
    • Common mirth.properties options⁠
    • Other mirth.properties options⁠
  • Using Docker Secrets⁠
  • Using Volumes⁠
• License⁠

⁠Quick Reference

⁠Where to get help:

• OIE Website: openintegrationengine.org⁠
• OIE Discord: Join the server⁠
• OIE GitHub: github.com/OpenIntegrationEngine/engine⁠
• This image: github.com/SagaHealthcareIT/engine-docker⁠
• Commercial support: Open Integration Engine services from Saga IT⁠

⁠How to file issues:

For issues specific to this Docker image or the bundled plugins, please file them at: https://github.com/SagaHealthcareIT/engine-docker/issues⁠

For issues with the Open Integration Engine itself, please file them at: https://github.com/OpenIntegrationEngine/engine/issues⁠

⁠What is this image?

This is Saga Healthcare IT⁠'s distribution of Open Integration Engine⁠ (OIE) with a curated set of community plugins pre-installed.

Open Integration Engine is an open-source message integration engine focused on healthcare. It is a community-driven project that continues the legacy of Mirth Connect⁠, providing a flexible, open platform for managing healthcare interfaces.

This image is built from the official OIE release and adds plugins that are useful for healthcare integration workflows. The plugins are baked into the image at build time, so they are available immediately without any additional setup.

⁠Bundled Plugins

The following plugins are pre-installed in this image:

You can still install additional plugins at runtime using the custom-extensions volume⁠ or the EXTENSIONS_DOWNLOAD⁠ environment variable.

⁠Supported Images

All images are published to Docker Hub⁠:

• latest, latest-ubuntu, latest-ubuntu-jre
  • 4.6.0-ubuntu, 4.6.0-ubuntu-jre
• latest-ubuntu-jdk
  • 4.6.0-ubuntu-jdk

⁠Supported Architectures

Docker images support linux/amd64. To pull a specific platform explicitly:

docker pull --platform linux/amd64 sagait/engine:latest

⁠How to use this image

⁠Start an OpenIntegrationEngine instance

Quickly start using the embedded Derby database and all configuration defaults. At a minimum you will likely want to use the -p option to expose the 8443 port so that you can log in with the Administrator GUI or CLI:

docker run -p 8443:8443 sagait/engine

You can also use the --name option to give your container a unique name, and the -d option to detach the container and run it in the background:

docker run --name myengine -d -p 8443:8443 sagait/engine

To run a different base image, specify a tag at the end:

docker run --name myengine -d -p 8443:8443 sagait/engine:latest-ubuntu-jdk

Look at the Environment Variables⁠ section for more available configuration options.

⁠Using docker stack deploy⁠ or docker compose⁠

With docker stack or docker compose you can easily set up and launch multiple related containers. For example, you might want to launch both Engine and a PostgreSQL database to run alongside it.

docker compose -f stack.yml up

Here's an example stack.yml file you can use:

services:
  engine:
    image: sagait/engine
    environment:
      - DATABASE=postgres
      - DATABASE_URL=jdbc:postgresql://db:5432/enginedb
      - DATABASE_MAX_CONNECTIONS=20
      - DATABASE_USERNAME=enginedb
      - DATABASE_PASSWORD=enginedb
      - DATABASE_MAX_RETRY=2
      - DATABASE_RETRY_WAIT=10000
      - KEYSTORE_STOREPASS=docker_storepass
      - KEYSTORE_KEYPASS=docker_keypass
      - VMOPTIONS=-Xmx512m
    ports:
      - "8080:8080/tcp"
      - "8443:8443/tcp"
    depends_on:
      - db

  db:
    image: postgres
    environment:
      - POSTGRES_USER=enginedb
      - POSTGRES_PASSWORD=enginedb
      - POSTGRES_DB=enginedb
    ports:
      - "5432:5432/tcp"

⁠Environment Variables

You can use environment variables to configure the mirth.properties⁠ file or to add custom JVM options.

⁠Setting Environment Variables

To set environment variables, use the -e option for each variable on the command line:

docker run -e DATABASE='derby' -p 8443:8443 sagait/engine

You can also use a separate file containing all of your environment variables using the --env-file option. For example let's say you create a file myenvfile.txt:

DATABASE=postgres
DATABASE_URL=jdbc:postgresql://serverip:5432/enginedb
DATABASE_USERNAME=postgres
DATABASE_PASSWORD=postgres
DATABASE_MAX_RETRY=2
DATABASE_RETRY_WAIT=10000
KEYSTORE_STOREPASS=changeme
KEYSTORE_KEYPASS=changeme
VMOPTIONS=-Xmx512m

docker run --env-file=myenvfile.txt -p 8443:8443 sagait/engine

⁠Common mirth.properties options

⁠DATABASE

The database type to use for the Open Integration Engine backend database. Options:

• derby
• mysql
• postgres
• oracle
• sqlserver

⁠DATABASE_URL

The JDBC URL to use when connecting to the database. For example:

• jdbc:postgresql://serverip:5432/enginedb

⁠DATABASE_USERNAME

The username to use when connecting to the database. If you don't want to use an environment variable to store sensitive information like this, look at the Using Docker Secrets⁠ section below.

⁠DATABASE_PASSWORD

The password to use when connecting to the database. If you don't want to use an environment variable to store sensitive information like this, look at the Using Docker Secrets⁠ section below.

⁠DATABASE_MAX_CONNECTIONS

The maximum number of connections to use for the internal messaging engine connection pool.

⁠DATABASE_MAX_RETRY

On startup, if a database connection cannot be made for any reason, Engine will wait and attempt again this number of times. By default, will retry 2 times (so 3 total attempts).

⁠DATABASE_RETRY_WAIT

The amount of time (in milliseconds) to wait between database connection attempts. By default, will wait 10 seconds between attempts.

⁠KEYSTORE_STOREPASS

The password for the keystore file itself. If you don't want to use an environment variable to store sensitive information like this, look at the Using Docker Secrets⁠ section below.

⁠KEYSTORE_KEYPASS

The password for the keys within the keystore, including the server certificate and the secret encryption key. If you don't want to use an environment variable to store sensitive information like this, look at the Using Docker Secrets⁠ section below.

⁠KEYSTORE_TYPE

The type of keystore.

⁠SESSION_STORE

If set to true, the web server sessions are stored in the database. This can be useful in situations where you have multiple Engine servers (connecting to the same database) clustered behind a load balancer.

⁠VMOPTIONS

A comma-separated list of JVM command-line options to place in the .vmoptions file. For example to set the max heap size:

• -Xmx512m

⁠DELAY

The number of seconds to wait before starting Engine. The entrypoint script will sleep for this duration before launching the server. This is useful when the database is being started at the same time as Engine and needs a moment to become ready.

⁠KEYSTORE_DOWNLOAD

A URL location of a Engine keystore file. This file will be downloaded into the container and Engine will use it as its keystore.

⁠EXTENSIONS_DOWNLOAD

A URL location of a zip file containing Engine extension zip files. The extensions will be installed on the Engine server.

⁠CUSTOM_JARS_DOWNLOAD

A URL location of a zip file containing JAR files. The JAR files will be installed into the server-launcher-lib folder on the Engine server, so they will be added to the server's classpath.

⁠ALLOW_INSECURE

Allow insecure SSL connections when downloading files during startup. This applies to keystore downloads, plugin downloads, and server library downloads. By default, insecure connections are disabled, but you can enable this option by setting ALLOW_INSECURE=true.

⁠SERVER_ID

Set the server.id to a specific value. Use this to preserve or set the server ID across restarts and deployments. Using the env-var is preferred over storing appdata persistently

⁠Other mirth.properties options

Other options in the mirth.properties file can also be changed. Any environment variable starting with the _MP_ prefix will set the corresponding value in mirth.properties. Replace . with a single underscore _ and - with two underscores __.

Examples:

• Set the server TLS protocols to only allow TLSv1.2 and 1.3:

  • In the mirth.properties file:
    • https.server.protocols = TLSv1.3,TLSv1.2
  • As a Docker environment variable:
    • _MP_HTTPS_SERVER_PROTOCOLS='TLSv1.3,TLSv1.2'

• Set the max connections for the read-only database connection pool:

  • In the mirth.properties file:
    • database-readonly.max-connections = 20
  • As a Docker environment variable:
    • _MP_DATABASE__READONLY_MAX__CONNECTIONS='20'

⁠Using Docker Secrets

For sensitive information such as the database/keystore credentials, instead of supplying them as environment variables you can use a Docker Secret⁠. There are two secret names this image supports:

⁠mirth_properties

If present, any properties in this secret will be merged into the mirth.properties file.

⁠oieserver_vmoptions

If present, any JVM options in this secret will be appended onto the oieserver.vmoptions file.

Secrets are supported with Docker Swarm⁠, but you can also use them with docker compose⁠.

For example let's say you wanted to set keystore.storepass and keystore.keypass in a secure way. You could create a new file, secret.properties:

keystore.storepass=changeme
keystore.keypass=changeme

Then in your compose.yaml:

services:
  engine:
    image: sagait/engine
    environment:
      - VMOPTIONS=-Xmx512m
    secrets:
      - mirth_properties
    ports:
      - "8080:8080/tcp"
      - "8443:8443/tcp"

secrets:
  mirth_properties:
    file: /local/path/to/secret.properties

The secrets section at the bottom specifies the local file location for each secret. Change /local/path/to/secret.properties to the correct local path and filename.

Inside the configuration for the Engine container there is also a secrets section that lists the secrets you want to include for that container.

⁠Using Volumes

⁠The appdata folder

The application data directory (appdata) stores configuration files and temporary data created by Engine after starting up. This usually includes the keystore file and the server.id file that stores your server ID. If you are launching Engine as part of a stack/swarm, it's possible the container filesystem is already being preserved. But if not, you may want to consider mounting a volume to preserve the appdata folder.

docker run -v /local/path/to/appdata:/opt/engine/appdata -p 8443:8443 sagait/engine

The -v option makes a local directory from your filesystem available to the Docker container. Create a folder on your local filesystem, then change the /local/path/to/appdata part in the example above to the correct local path.

You can also configure volumes as part of your compose.yaml:

services:
  engine:
    image: sagait/engine
    volumes:
      - ~/Documents/appdata:/opt/engine/appdata

⁠Additional extensions

The entrypoint script will automatically look for any .zip files in the /opt/engine/custom-extensions folder and unzip them into the extensions folder before Engine starts up. So to launch Engine with any additional extensions not included in the base application, do this:

docker run -v /local/path/to/custom-extensions:/opt/engine/custom-extensions -p 8443:8443 sagait/engine

Create a folder on your local filesystem containing the ZIP files for your additional extensions. Then change the /local/path/to/custom-extensions part in the example above to the correct local path.

As with the appdata example, you can also configure this volume as part of your compose.yaml.

⁠Building images

To build both images (ubuntu-jre and ubuntu-jdk) run the following command in the deploy/ directory:

docker compose build --build-arg CREATED_AT=$(date -u +"%Y-%m-%dT%H:%M:%SZ")

⁠License

The Dockerfiles, entrypoint script, and any other files used to build these Docker images are Copyright © NextGen Healthcare and OpenIntegrationEngine contributors. They are licensed under the Mozilla Public License 2.0⁠.