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:
curl -s "https://get.sdkman.io" | bashOpen 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
git clone https://github.com/OpenIntegrationEngine/engine.git
cd engineThen let SDKMAN install and select the pinned JDK. Run this from the repository root, where .sdkmanrc lives:
sdk env installsdk 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:
java -versionBuild
./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:
./gradlew test -PdisableSigning=true # unit tests onlyDependencies 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
server/setup/oieserveroieserver 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:
./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:
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:
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:
perl -pi -e 's/^server\.initialadminpassword\s*=.*/server.initialadminpassword = admin/' server/setup/conf/mirth.properties
server/setup/oieserverThe 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:
| Directory | What it is |
|---|---|
server | The engine itself: server source, the core jars, and the staged distribution under server/setup. |
client | The Swing Administrator client and the client half of each bundled extension. |
donkey | The message engine underneath the server. |
command | The command line client. |
generator | HL7 vocabulary generator tooling. Not part of the distribution build. |
smoketest | Integration 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.