OIE Docker Image

Saga IT publishes sagait/engine on Docker Hub — a distribution of Open Integration Engine (OIE) with a curated set of community plugins pre-installed. OIE is the open-source fork of Mirth Connect that continues active development after NextGen Healthcare transitioned Mirth Connect to commercial-only licensing.

The plugins are baked into the image at build time, so they are available immediately without any additional setup.

---

Quick Start

Get running in one command

Terminal

docker run -p 8443:8443 sagait/engine

This starts OIE with the embedded Derby database and all default settings. Access the Administrator GUI at https://localhost:8443.

Give your container a name and run it in the background:

Terminal

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

To use a different base image variant, specify a tag:

Terminal

docker run --name oie -d -p 8443:8443 sagait/engine:latest-alpine-jdk

---

Bundled Plugins

Plugin	Description
mirthsync-mirth-plugin	Engine-side plugin for MirthSync integration
simple-channel-history	Lightweight channel deployment history tracking
tls-manager-plugin	TLS certificate management UI for the engine

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

---

Supported Tags

Note

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

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

All images are published to Docker Hub:

• Alpine (default)
  • latest, latest-alpine, latest-alpine-jre → 4.5.2-alpine, 4.5.2-alpine-jre
  • latest-alpine-jdk → 4.5.2-alpine-jdk
• Ubuntu
  • latest-ubuntu, latest-ubuntu-jre → 4.5.2-ubuntu, 4.5.2-ubuntu-jre
  • latest-ubuntu-jdk → 4.5.2-ubuntu-jdk

The JRE variants are smaller (283 MB Alpine, 310 MB Ubuntu). Use the JDK variants if you need to compile custom Java code at runtime.

---

Docker Compose with PostgreSQL

For production use, run OIE with an external PostgreSQL database instead of the embedded Derby.

compose.yaml

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"

Start the stack:

Terminal

docker compose up -d

---

Environment Variables

Environment variables configure the mirth.properties file and JVM options.

Set them with -e on the command line:

Terminal

docker run -e DATABASE='postgres' -e DATABASE_URL='jdbc:postgresql://db:5432/enginedb' -p 8443:8443 sagait/engine

Or use an env 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

Terminal

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

Use Docker Secrets for credentials

Avoid storing database passwords and keystore passphrases in plain environment variables or env files. Use Docker Secrets instead.

Common Options

Database

Variable	Description
DATABASE	Backend database type: derby, mysql, postgres, oracle, sqlserver
DATABASE_URL	JDBC connection URL (e.g. jdbc:postgresql://host:5432/enginedb)
DATABASE_USERNAME	Database username
DATABASE_PASSWORD	Database password
DATABASE_MAX_CONNECTIONS	Max connections for the internal connection pool
DATABASE_MAX_RETRY	Number of connection retry attempts on startup (default: 2, so 3 total)
DATABASE_RETRY_WAIT	Milliseconds between retry attempts (default: 10000)

Security

Variable	Description
KEYSTORE_STOREPASS	Password for the keystore file
KEYSTORE_KEYPASS	Password for keys within the keystore (server cert + encryption key)
KEYSTORE_TYPE	Keystore type
KEYSTORE_DOWNLOAD	URL to download a keystore file into the container
ALLOW_INSECURE	Allow insecure SSL for startup downloads (true/false, default: false)

Server

Variable	Description
VMOPTIONS	JVM options, e.g. -Xmx512m
DELAY	Seconds to wait before starting the engine (useful when DB needs time to initialize)
SESSION_STORE	Set to true to store web sessions in the database (for clustered deployments)
SERVER_ID	Set a specific server.id value — preferred over persisting appdata
EXTENSIONS_DOWNLOAD	URL to a zip file of extension zips to install at startup
CUSTOM_JARS_DOWNLOAD	URL to a zip of JAR files to add to the server classpath

Custom mirth.properties via _MP_ Prefix

Any environment variable starting with _MP_ sets the corresponding value in mirth.properties. Replace . with a single underscore _ and - with two underscores __.

Examples:

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

mirth.properties

https.server.protocols = TLSv1.3,TLSv1.2

Environment variable

_MP_HTTPS_SERVER_PROTOCOLS='TLSv1.3,TLSv1.2'

Set max connections for the read-only database pool:

mirth.properties

database-readonly.max-connections = 20

Environment variable

_MP_DATABASE__READONLY_MAX__CONNECTIONS='20'

---

Docker Secrets

For sensitive information, use Docker Secrets instead of environment variables. Two secret names are supported:

Secret	Purpose
mirth_properties	Properties merged into mirth.properties
oieserver_vmoptions	JVM options appended to the .vmoptions file

Example: Store keystore credentials as a secret:

secret.properties

keystore.storepass=changeme
keystore.keypass=changeme

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

---

Volumes

Application Data

The appdata directory stores configuration files and temporary data created after startup, including the keystore and server.id. Mount a volume to persist this across container restarts:

Terminal

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

Or in your compose file:

compose.yaml

services:
  engine:
    image: sagait/engine
    volumes:
      - ./appdata:/opt/engine/appdata

Tip

If you set SERVER_ID via environment variable, you may not need to persist appdata at all — the server ID is the main reason to preserve it.

Additional Extensions

The entrypoint script automatically installs any .zip files found in /opt/engine/custom-extensions before the engine starts:

Terminal

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

Place your extension ZIP files in the local folder and they will be installed on every container start.

---

Where to Get Help

• OIE Website: openintegrationengine.org
• OIE Discord: Join the server
• OIE GitHub: github.com/OpenIntegrationEngine/engine
• Image issues: github.com/SagaHealthcareIT/engine-docker

License

The Dockerfiles, entrypoint scripts, and build files are licensed under the Mozilla Public License 2.0. OIE itself is open-source under the same terms as the original Mirth Connect codebase.

---

OIE Downloads Download OIE with or without the MDDS Gateway Plugin. Includes installation guides and release notes.

MirthSync CLI Git-based version control for Mirth Connect and OIE channels, scripts, and configurations.

Troubleshooting Solutions for database connections, performance, channel errors, SSL/TLS, and startup issues.