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

[vishnu-exe]

Hi team,

I'm interested in contributing to or using the Open Integration Engine project, but I couldn't find clear documentation or a step-by-step guide on how to build and run the application from source.

Could you please consider adding a detailed README or Wiki section that includes:

Required dependencies and environment setup

Build instructions (e.g., using Ant or other tools)

How to run the engine locally

Directory structure explanation (optional but helpful)

Screenshots of successful build and running state (like web UI or logs)

This would be very helpful for developers like me who want to get started with the project.

Thanks for your work on this!

[mgaffigan]

@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.