Missing Documentation: Steps to Build and Run the Application from Source #118

Activity

1. vishnu-exe

   added

   documentationImprovements or additions to documentationImprovements or additions to documentation

   on Jun 11, 2025
2. mgaffigan commented on Jun 11, 2025

   

   mgaffigan

   on Jun 11, 2025

   Last edited by mgaffigan

   Contributor

   More actions

   @vishnu-exe ,

   Agreed that this is an area that needs work. See https://github.com/OpenIntegrationEngine/engine/blob/main/CONTRIBUTING.md for some general background, and https://github.com/OpenIntegrationEngine/engine/blob/main/.github/workflows/build.yaml for what runs in github pipelines to produce a release.

   Currently in main

   Here's a quick rundown of what I'm aware of in main:

   • The project itself uses ant to build
   • It requires a Java 8 JDK to build, and a Java 9+ JRE to run.
   • You will need to use a JWS launcher - typically Ballista
   • You can get copies of ant and a suitable jdk by running sdk env install from within /
   • You can build the project by running ant -f mirth-build -DdisableSigning=true from within /server/
   • The results of the build are found in /server/setup/
   • Starting the server requires constructing an appropriate java invocation to run. A script to do so is not currently in main. An example invocation is:

   java -server -Xmx256m -Djava.awt.headless=true -Dapple.awt.UIElement=true --add-modules=java.sql.rowset --add-exports=java.base/com.sun.crypto.provider=ALL-UNNAMED --add-exports=java.base/sun.security.provider=ALL-UNNAMED --add-opens=java.base/java.lang=ALL-UNNAMED --add-opens=java.base/java.lang.reflect=ALL-UNNAMED --add-opens=java.base/java.math=ALL-UNNAMED --add-opens=java.base/java.net=ALL-UNNAMED --add-opens=java.base/java.security=ALL-UNNAMED --add-opens=java.base/java.security.cert=ALL-UNNAMED --add-opens=java.base/java.text=ALL-UNNAMED --add-opens=java.base/java.util=ALL-UNNAMED --add-opens=java.base/sun.security.pkcs=ALL-UNNAMED --add-opens=java.base/sun.security.rsa=ALL-UNNAMED --add-opens=java.base/sun.security.x509=ALL-UNNAMED --add-opens=java.desktop/java.awt=ALL-UNNAMED --add-opens=java.desktop/java.awt.color=ALL-UNNAMED --add-opens=java.desktop/java.awt.font=ALL-UNNAMED --add-opens=java.xml/com.sun.org.apache.xalan.internal.xsltc.trax=ALL-UNNAMED --add-opens=java.desktop/java.awt.color=ALL-UNNAMED -cp /path/to/mirth-server-launcher.jar com.mirth.connect.server.launcher.MirthLauncher

   • The invocation should come from the options listed in https://github.com/mgaffigan/oie/blob/feature/add-docker/server/basedir-includes/oieserver.vmoptions and therein referenced file.
   • After the server starts, you can connect to it with Ballista at https://localhost:8443/

   Branches working to make this easier

   There are some efforts ongoing to make this an easier onboarding. Two I'm aware of are mgaffigan/feature/add-docker and nicopiel/feature/gradle-2.

   mgaffigan/feature/add-docker

   There's a branch and PR which uses docker to encapsulate everything. That PR does add a "Getting Started" guide, but the short version is:

   docker build -t oie-dev .
   docker run --rm -p 8443:8443 oie-dev
   # Connect to https://localhost:8443 with ballista

   If you only want to run it and poke around, and are not trying to edit the source code, then the Docker Getting Started in that branch is even easier:

   docker run --name myconnect -d -p 8443:8443 ghcr.io/mgaffigan/oie

   nicopiel/feature/gradle-2

   Caigh has a branch that moves to gradle. After clone and with an appropriate JDK 8 + JavaFX as JAVA_HOME, you can build the repo with ./gradlew dist -x test. -x test disables running unit tests as part of build. Once built, the archives are in /dist/ - but I tend to run them directly from /server/dist/ by executing mirth-connect.sh. Connect with ballista to https://localhost:8443. There's also a post for this in Discord.

   👍React with 👍4Reacted by MatthiasDM, vishnu-exe, 潤沁軟體 and VillePekka
3. VillePekka commented on Dec 16, 2025

   

   VillePekka

   on Dec 16, 2025

   Last edited by VillePekka

   Contributor

   More actions

   Thank you @mgaffigan, I got the system running with the help of your instructions!

   The comments below are related to mgaffigan's section "Currently in main":

   Currently the java invocation is not necessary anymore. There's a oieserver script which you can run. I ran the following commands on Ubuntu 24.04 terminal to get the system running.

   • clone the OIE engine repo:

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

   • install curl

   sudo apt install curl

   • Install sdkman

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

   • switch to repo

   cd engine

   • install suitable ant and and jdk

   sdk env install

   • change to server directory and build project

   cd server

   ant -f mirth-build.xml -DdisableSigning=true

   • run with oieserver script

   ~/engine/server/setup/oieserver

   • download Ballista to ~/Downloads/

   wget -P ~/Downloads/ https://github.com/kayyagari/ballista/releases/download/0.6.0/Ballista_0.6.0_amd64.deb

   • install ballista

   sudo apt install ~/Downloads/Ballista_0.6.0_amd64.deb

   • Run ballista

   Ballista

   👍React with 👍1Reacted by Mitch Gaffigan
4. mmdavenport commented on Sep 20, 2026

   

   mmdavenport

   on Sep 20, 2026

   More actions

   Since the Ant→Gradle migration, README and CONTRIBUTING carry build sections, but the docs site itself still has no build-and-run guide — installation.md covers release installers only, and the docs contributing page goes from tooling install straight to implementation.

   I'd like to contribute a "Building from source" page for the docs site covering the current Gradle workflow (JDK per .sdkmanrc, build, Derby DB setup, dev server and client targets), verified against a clean build before I open the PR. Planning docs/engine/building_from_source.md with a sidebar entry, leaving the retired getting_started redirect as is. If the maintainers would rather see this somewhere else, happy to follow that.