Skip to content

Building from Source ​

This page is for contributors who want to compile the engine and run what they compiled. If you only want a working server, install a published release instead: see Installation. Nothing here is required to use OIE.

The build is driven by Gradle through a wrapper committed to the repository, so the only thing you have to install yourself is a JDK.

Prerequisites ​

Java ​

The repository pins the JDK it is built against in .sdkmanrc at the root of the tree. At the time of writing that is a Java 17 Zulu build with JavaFX included, and the JavaFX part matters when you run the Administrator client. The client compiles on a plain JDK, because the repository carries the JavaFX classes it compiles against.

The least error-prone way to get exactly that JDK is SDKMAN, which reads the pin for you:

bash
curl -s "https://get.sdkman.io" | bash

Open a new shell afterwards so the sdk command is on your path.

Gradle ​

You do not install Gradle. The gradlew script in the repository root downloads and runs the correct version on first use.

Windows

Every command below is written as ./gradlew. On Windows use gradlew.bat instead. If the build stops in the javadoc step complaining that a path is too long, add -x :server:userApiJavadoc to skip it.

Get the source ​

bash
git clone https://github.com/OpenIntegrationEngine/engine.git
cd engine

Then let SDKMAN install and select the pinned JDK. Run this from the repository root, where .sdkmanrc lives:

bash
sdk env install

sdk env install installs the pinned version if you do not have it and switches the current shell to it. In a new shell, run sdk env to switch again without reinstalling. Confirm you got what you expected before building:

bash
java -version

Build ​

bash
./gradlew build -PdisableSigning=true

-PdisableSigning=true turns off jar signing. Without it the build signs with a self-signed development certificate kept in the repository, so no key of yours is needed. Signing is slow, though, and contacts a timestamp service over the network. Leave it off for local work.

The first run downloads the Gradle distribution and every dependency, so expect several minutes. Later runs are much faster. A successful build ends with BUILD SUCCESSFUL and leaves a complete server layout in server/setup.

A few other targets are useful once you are working in the tree:

bash
./gradlew test -PdisableSigning=true   # unit tests only

Dependencies are checksum-verified

Versions are pinned in gradle/libs.versions.toml and their checksums are recorded. Editing a version means regenerating that metadata, and it has to be done against a cold dependency cache or the result passes locally and fails in CI. CONTRIBUTING.md has the exact command.

Development database ​

You do not need to create or reset the database — but do not expect it to keep anything either. Every build deletes the embedded Derby database: the stageSetup task wipes setup/appdata, which is where it lives. On the next startup the server notices it is gone and recreates the database and its schema automatically. No manual action is needed, and any channels or messages you saved locally do not survive a build.

Run the server ​

bash
server/setup/oieserver

oieserver is the launcher script the build stages into server/setup for running the engine out of your working tree. (A production installation starts through a launcher generated by install4j, so this is not the production entry point.) It changes to its own directory first, so you can run it from the repository root. It runs in the foreground and streams the log to your terminal. Stop it with Ctrl+C.

You can also start the same staged server through Gradle:

bash
./gradlew :server:devLauncher -PdisableSigning=true

:server:devRun does not currently work

CONTRIBUTING.md also lists :server:devRun, which runs the server straight from the compiled classes rather than from server/setup. On current main it fails at startup with Could not find resource SqlMapConfig.xml and then retries startup twice, 10 seconds apart, before aborting, because the dbconf directory that holds that file is packaged into the distribution but is not on the task's classpath. The reporter closed engine issue #416 after finding that :server:devLauncher works, and :server:devRun itself still fails. Use server/setup/oieserver until it is fixed.

A successful startup ends with lines like these. Versions, addresses and dates will differ:

log
INFO  [Main Server Thread] com.mirth.connect.server.Mirth: Open Integration Engine 4.6.0 (Built on ...) server successfully started.
INFO  [Main Server Thread] com.mirth.connect.server.Mirth: Running OpenJDK 64-Bit Server VM 17.0.17 on Mac OS X (15.6, aarch64), derby, with charset UTF-8.
INFO  [Main Server Thread] com.mirth.connect.server.Mirth: Web server running at http://<host>:8080/ and https://<host>:8443/

Stop any other engine first

The server binds ports 8080 and 8443. If you already have OIE running as a service, or a container publishing those ports, start nothing until you have stopped it. A second engine logs http.port port is already in use: 8080 and https.port port is already in use: 8443 and does not serve, but its process keeps running while the first engine keeps answering, so you can end up administering the wrong one without noticing.

First login ​

Scan the startup log for the initial administrator password. A new database prints it once, in a banner near the top of the output:

log
WARN  [Main Server Thread] com.mirth.connect.server.Mirth:
********************************************************************************
************   Initial admin password is <generated>            ************
********************************************************************************

The username is admin. To choose the password yourself instead, set server.initialadminpassword in server/setup/conf/mirth.properties before the first startup. The file already contains an empty server.initialadminpassword = entry, so set that line rather than appending a second one, then start the server:

bash
perl -pi -e 's/^server\.initialadminpassword\s*=.*/server.initialadminpassword = admin/' server/setup/conf/mirth.properties
server/setup/oieserver

The property is read only when the database is first created; if it is left empty, the server generates a password and prints it in the banner above.

Connect to it ​

Open https://localhost:8443/ in a browser. The server presents a certificate signed by the engine's own generated certificate authority, so you will have to accept a warning the first time. You should land on the engine's status page, which links to the launcher documentation and the client API.

From there, Accessing the Administrator covers the browser-based administrator and the desktop Administrator's launcher.

The Gradle build also exposes :client:devClient, which launches the desktop Administrator from the tree you just compiled. It connects to https://localhost:8443 and will only reach the server you intended if nothing else is bound to that port.

What is in the tree ​

The repository is a multi-module Gradle build. The modules, as declared in settings.gradle:

DirectoryWhat it is
serverThe engine itself: server source, the core jars, and the staged distribution under server/setup.
clientThe Swing Administrator client and the client half of each bundled extension.
donkeyThe message engine underneath the server.
commandThe command line client.
generatorHL7 vocabulary generator tooling. Not part of the distribution build.
smoketestIntegration tests that run against a live server, not unit tests.

Two directories outside the module list are worth knowing: gradle holds the version catalog and dependency verification metadata, and ci holds the scripts the pipelines run.

Working in an IDE ​

Import the repository as a Gradle project. IntelliJ IDEA handles this natively; Eclipse does it through Buildship. The old .classpath and .project files were removed deliberately, so do not go looking for them.

To attach a debugger, add --debug-jvm to any of the run targets. The JVM suspends at startup and waits for a connection on port 5005.