OEM Edition Installer Packaging

Intro

This guide will help you set up everything you need to build your customized OEM Edition installers.

You'll start by setting up your environment then organize your project and configure the build process.

By the end, you will have fully working installers for both Linux and Windows that include your branding and custom changes that you have made.

Prerequisites

Before you begin, make sure you have already apply every necessary OEM branding or customizations in oem-enterpriseweb project and successfully build the jw-community source code as explained in "Building and Deploying OEM Edition" article.

This process requires stable internet connectivity to download Maven dependencies and following tools are installed:

• Java JDK
• Maven
• Git

To verify tools is ready for use, you can check them with:

java -version
mvn -v
git --version

Set Up Windows Installer Builder

Step 1: Install NSIS (makensis)

Install NSIS to enable the generation of Windows .exe installer as part of the build process. It's a required tool for compiling wflow-install/src/main/resources/setup.nsi script into a Windows installer.

On Linux

sudo apt update
sudo apt install nsis

On Mac

brew update
brew install nsis

On Windows

Download NSIS from the official site then install it.

Open System Properties > Environment Variables.

Then in System variables, edit the Path variable and add:

C:\Program Files (x86)\NSIS

Open up a new terminal and test below command:

makensis -VERSION

If you can see the version, NSIS is now ready to use.

Step 2: Create a Project Folder

Create a dedicated folder for building the OEM Edition.

mkdir my-oem-repo
cd my-oem-repo

Prepare the Source Code

Step 1: oem-enterpriseweb Directory

Copy or move oem-enterpriseweb-8.2.1-d17136c project into my-oem-repo folder:

cp -r oem-enterpriseweb-8.2.1-d17136c /path/to/my-oem-repo

Then rename it to just oem-enterpriseweb.

Step 2: wflow-install and .gitignore

Copy the wflow-install folder from the jw-community source code into my-oem-repo project:

cp -r /path/to/jw-community/wflow-install /path/to/my-oem-repo

Create a .gitignore file to avoid committing build artifacts:

cat <<EOF > .gitignore
/*/target
/*/downloads
/*/builds
EOF

In my-oem-repo folder, you should now have a similar content as below:

my-oem-repo/
├── oem-enterpriseweb/
├── wflow-install/
└── .gitignore

Step 3: Update Build Metadata

Edit oem-enterpriseweb/src/main/resources/custom.properties file and add below in its content:

console.footer.label.revision=Version: ${git.build.version} - build ${git.commit.id.abbrev}
build.number=${git.commit.id.abbrev}
build.version=${git.build.version}

This injects Git commit information into the OEM Edition's build metadata.

Step 4: Replace Maven pom.xml Files

oem-enterpriseweb/pom.xml

Replace this file with below content to define the building logic. Make sure to set <version> to match the tag or branch in jw-community.

<projecct xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <groupId>org.joget</groupId>
    <artifactId>oem-enterpriseweb</artifactId>
    <packaging>war</packaging>
    <version>same-version-as-jw-community</version>
    <name>oem-enterpriseweb</name>
    <url>http://your-website</url>
    <dependencies>
        <dependency>
            <groupId>org.joget</groupId>
            <artifactId>cloud-consoleweb</artifactId>
            <version>${project.version}</version>
            <type>war</type>
        </dependency>
        <dependency>
            <groupId>org.joget</groupId>
            <artifactId>wflow-core</artifactId>
            <version>${project.version}</version>
            <scope>provided</scope>
        </dependency>
        
        <!-- Dependency for SampleDataEncryptionImpl -->
        <dependency>
            <groupId>org.jasypt</groupId>
            <artifactId>jasypt</artifactId>
            <version>1.9.0</version>
            <scope>compile</scope>
        </dependency>
        <!-- Dependency for SampleDataEncryptionImpl -->
    </dependencies>
    <build>
        <finalName>jw</finalName>
        <resources>
            <resource>
                <directory>src/main/resources</directory>
                <filtering>true</filtering>
                <excludes>
                    <exclude>**/*.ttf</exclude>
                    <exclude>**/*.zip</exclude>
                    <exclude>**/*.png</exclude>
                </excludes>
            </resource>
            <resource>
                <directory>src/main/resources</directory>
                <filtering>false</filtering>
                <includes>
                    <include>**/*.ttf</include>
                    <include>**/*.zip</include>
                    <include>**/*.png</include>
                </includes>
            </resource>
        </resources>
        <plugins>
            <plugin>
                <artifactId>maven-compiler-plugin</artifactId>
                <version>2.0.2</version>
                <configuration>
                    <source>1.7</source>
                    <target>1.7</target>
                </configuration>
            </plugin>
            <plugin>
                <groupId>io.github.git-commit-id</groupId>
                <artifactId>git-commit-id-maven-plugin</artifactId>
                <version>9.0.2</version>
                <executions>
                    <execution>
                        <id>save-git-info</id>
                        <goals>
                            <goal>revision</goal>
                        </goals>
                        <phase>initialize</phase>
                    </execution>
                </executions>
                <configuration>
                    <generateGitPropertiesFile>true</generateGitPropertiesFile>
                    <generateGitPropertiesFilename>${project.build.directory}/git.properties</generateGitPropertiesFilename>
                </configuration>
            </plugin>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-war-plugin</artifactId>
                <version>2.4</version>
            </plugin>             
            <plugin>
                <groupId>org.codehaus.mojo</groupId>
                <artifactId>tomcat-maven-plugin</artifactId>
                <version>1.0</version>
                <configuration>
                    <port>8080</port>
                    <warSourceDirectory>${project.basedir}/target/jw</warSourceDirectory>
                    <path>/jw</path>
                </configuration>
            </plugin>
        </plugins>
    </build>
</project>

wflow-install/pom.xml

Replace this file with below content. It controls how the installer is built by downloading dependencies, packaging resources and generating final installer files.

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <groupId>org.joget</groupId>
    <artifactId>wflow-install</artifactId>
    <packaging>pom</packaging>
    <version>same-version-as-jw-community</version>
    <name>wflow-install</name>
    <url>http://your-website</url>
    <properties>
        <oem-enterpriseweb>../oem-enterpriseweb</oem-enterpriseweb>
    </properties>
    <modules>
        <module>${oem-enterpriseweb}</module>
    </modules>
    <build>
        <resources>
            <resource>
                <directory>src/main/resources</directory>
                <filtering>true</filtering>
            </resource>
        </resources>
        <plugins>
            <plugin>
                <groupId>org.codehaus.mojo</groupId>
                <artifactId>properties-maven-plugin</artifactId>
                <version>1.2.1</version>
                <executions>
                    <execution>
                        <id>parse-git-properties</id>
                        <phase>validate</phase>
                        <goals>
                            <goal>read-project-properties</goal>
                        </goals>
                        <configuration>
                            <files>
                                <file>${project.basedir}/${oem-enterpriseweb}/target/git.properties</file>
                            </files>
                        </configuration>
                    </execution>
                </executions>
            </plugin>

            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-antrun-plugin</artifactId>
                <version>3.1.0</version>
                <executions>
                    <execution>
                        <id>build-archives</id>
                        <phase>prepare-package</phase>
                        <configuration>
                            <target>
                                <property file="src/main/resources/install.properties" />
                                
                                <delete dir="target" />
                                <mkdir dir="target" />
                                <mkdir dir="builds" />
                                
                                <copy todir="target/data">
                                    <fileset dir="src/main/resources/data" />
                                </copy>
                                <copy file="src/main/resources/README.txt" todir="target" />
                                <copy file="src/main/resources/CHANGES.txt" todir="target" />
                                <copy file="src/main/resources/LICENSE.txt" todir="target" />
                                <copy file="src/main/resources/NOTICE.txt" todir="target" />
                                <copy file="src/main/resources/setup.nsi" todir="target" />
                                <copy file="src/main/resources/joget_logo.bmp" todir="target" />
                                <copy file="src/main/resources/joget.ico" todir="target" />
                                <copy file="src/main/resources/joget_start.ico" todir="target" />
                                <copy file="src/main/resources/joget_stop.ico" todir="target" />
                                <copy file="src/main/resources/mariadb-start.bat" todir="target" />
                                <copy file="src/main/resources/mariadb-stop.bat" todir="target" />
                                <copy file="src/main/resources/tomcat-run.bat" todir="target" />
                                <copy file="src/main/resources/tomcat-stop.bat" todir="target" />
                                <copy file="src/main/resources/joget-start.bat" todir="target" />
                                <copy file="src/main/resources/joget-stop.bat" todir="target" />
                                <copy file="src/main/resources/build.xml" todir="target" />
                                <copy file="src/main/resources/setup.sh" todir="target" />
                                <copy file="src/main/resources/tomcat.sh" todir="target" />

                                <mkdir dir="downloads" />
                                <get src="https://dev.joget.org/downloads/dependencies/apache-tomcat-${tomcat.version}.tar.gz" dest="downloads/apache-tomcat-${tomcat.version}.tar.gz" username="public" password="public" usetimestamp="true" />
                                <get src="https://dev.joget.org/downloads/dependencies/apache-ant-${apache-ant.version}-bin.tar.gz" dest="downloads/apache-ant-${apache-ant.version}-bin.tar.gz" username="public" password="public" usetimestamp="true" />
                                <get src="https://dev.joget.org/downloads/dependencies/mariadb-noinstall-${mariadb.version}-winx64.zip" dest="downloads/mariadb-noinstall-${mariadb.version}-winx64.zip" username="public" password="public" usetimestamp="true" />
                                <get src="https://dev.joget.org/downloads/dependencies/jre${jre.version}.tar.gz" dest="downloads/jre${jre.version}.tar.gz" username="public" password="public" usetimestamp="true" />
                                
                                <untar compression="gzip" dest="target">
                                    <fileset dir="downloads/">
                                        <include name="apache-tomcat-${tomcat.version}.tar.gz" />
                                        <include name="apache-ant-${apache-ant.version}-bin.tar.gz" />
                                        <include name="jre${jre.version}.tar.gz" />
                                    </fileset>
                                </untar>

                                <unzip dest="target">
                                    <fileset dir="downloads/">
                                        <include name="mariadb-noinstall-${mariadb.version}-winx64.zip" />
                                    </fileset>
                                </unzip>

                                <pathconvert property="resolved.oem.project.dir" pathsep="">
                                    <first count="1">
                                        <dirset dir="..">
                                            <include name="oem-enterpriseweb*/" />
                                        </dirset>
                                    </first>
                                </pathconvert>

                                <copy flatten="true" todir="target/apache-tomcat-${tomcat.version}/webapps">
                                    <fileset dir="${resolved.oem.project.dir}/target">
                                        <include name="jw.war" />
                                    </fileset>
                                </copy>
                                <copy tofile="target/apache-tomcat-${tomcat.version}/conf/server.xml" file="src/main/resources/server.xml" overwrite="true" />
                                <copy tofile="target/apache-tomcat-${tomcat.version}/conf/context.xml" file="src/main/resources/context.xml" overwrite="true" />
                                <copy todir="target/mariadb-${mariadb.version}-winx64/" file="src/main/resources/my.ini" />
                                <copy todir="target/mariadb-${mariadb.version}-winx64/data/" overwrite="true">
                                    <fileset dir="src/main/resources/mariadb-data" />
                                </copy>

                                <echo file="target/VERSION.txt">${git.build.version} - build ${git.commit.id.abbrev}</echo>

                                <copy todir="target/wflow">
                                    <fileset dir="src/main/resources/wflow-home" />
                                </copy>

                                <zip destfile="builds/joget-windows-${git.build.version}-${git.commit.id.abbrev}.zip">
                                    <fileset dir="target">
                                        <include name="apache-ant-${apache-ant.version}/**" />
                                        <include name="apache-tomcat-${tomcat.version}/**" />
                                        <include name="jre${jre.version}/**" />
                                        <include name="mariadb-${mariadb.version}-winx64/**" />
                                        <include name="data/**" />
                                        <include name="docs/**" />
                                        <include name="wflow/**" />
                                        <include name="build.xml" />
                                        <include name="joget-start.bat" />
                                        <include name="joget-stop.bat" />
                                        <include name="LICENSE.txt" />
                                        <include name="NOTICE.txt" />
                                        <include name="README.txt" />
                                        <include name="CHANGES.txt" />
                                        <include name="tomcat-run.bat" />
                                        <include name="tomcat-stop.bat" />
                                        <include name="mariadb-start.bat" />
                                        <include name="mariadb-stop.bat" />
                                        <include name="VERSION.txt" />
                                    </fileset>
                                </zip>

                                <tar compression="gzip" destfile="builds/joget-linux-${git.build.version}-${git.commit.id.abbrev}.tar.gz">
                                    <tarfileset dir="target" prefix="joget-linux-${git.build.version}">
                                        <include name="apache-ant-${apache-ant.version}/**" />
                                        <include name="apache-tomcat-${tomcat.version}/**" />
                                        <exclude name="apache-ant-${apache-ant.version}/bin/ant" />
                                        <exclude name="apache-tomcat-${tomcat.version}/bin/*.sh" />
                                        <include name="data/**" />
                                        <include name="docs/**" />
                                        <include name="wflow/**" />
                                        <exclude name="wflow/app_datasource.properties" />
                                        <include name="build.xml" />
                                        <include name="LICENSE.txt" />
                                        <include name="NOTICE.txt" />
                                        <include name="README.txt" />
                                        <include name="CHANGES.txt" />
                                        <include name="VERSION.txt" />
                                    </tarfileset>
                                    <tarfileset dir="target" filemode="755" prefix="joget-linux-${git.build.version}">
                                        <include name="apache-ant-${apache-ant.version}/bin/ant" />
                                        <include name="apache-tomcat-${tomcat.version}/bin/*.sh" />
                                        <include name="*.sh" />
                                    </tarfileset>
                                </tar>
                            </target>
                        </configuration>
                        <goals>
                            <goal>run</goal>
                        </goals>
                    </execution>
                </executions>
            </plugin>

            <plugin>
                <groupId>org.digitalmediaserver</groupId>
                <artifactId>nsis-maven-plugin</artifactId>
                <version>1.0.6</version>
                <executions>
                    <execution>
                    <id>build-windows-installer</id>
                    <phase>package</phase>
                    <goals>
                        <goal>make</goal>
                    </goals>
                    </execution>
                </executions>
                <configuration>
                    <scriptFile>${project.build.directory}/setup.nsi</scriptFile>
                    <outputFile>${project.basedir}/builds/joget-setup-${git.build.version}-${git.commit.id.abbrev}.exe</outputFile>
                </configuration>
            </plugin>

        </plugins>
    </build>
</project>

Build the Installers

Step 1: Initialize Git

This is required because the build process uses Git commit metadata (such as the short hash) to populate the OEM Build Hash.

In a terminal, execute following commands:

cd my-oem-repo
git init
git config user.name "Your Name"
git config user.email "you@example.com"
git add .
git commit -m "Initial commit"

Step 2: Run Maven Build

Run the following command:

mvn clean install -f ./wflow-install/pom.xml

If all goes well, the installers will be generated at my-oem-repo/wflow-install/builds/ folder. You’ll see files like:

• joget-linux-8.2.1-d17136c.tar.gz
• joget-windows-8.2.1-d17136c.zip
• joget-setup-8.2.1-d17136c.exe

Where d17136c is the short Git commit hash.

Troubleshooting

ZLIB or Corrupt Download Errors

If Maven fails with an error like:

Unexpected end of ZLIB input stream

Delete the corresponding corrupted files, example:

rm wflow-install/downloads/apache-tomcat-*.tar.gz
rm wflow-install/downloads/jre*.tar.gz

Then rebuild:

mvn clean install -f ./wflow-install/pom.xml

JDBC Driver Missing on First Joget Launch (Windows)

You might see this error on the first time of starting up installed OEM Edition:

Unable to load class: com.mysql.cj.jdbc.Driver

Simply fix it by downloading the correct mysql-connector-java-<version>.jar from MySQL website then move the jar file to:

C:\Joget-DX8\apache-tomcat-9.0.104\webapps\jw\WEB-INF\lib

Then restart Joget instance to load up the new jar file.

Summary

By following this guide, you’ve successfully set up a well structured and repeatable process for building custom OEM Edition installers for both Linux and Windows platforms.

Why This Matters?

Fast iteration: You can make changes and quickly regenerate new installers without redoing setup steps.

Consistent output: Each build is tagged with exact version and Git hash, ensuring traceability.

Cross-platform support: Both Linux and Windows installers are covered in a single process.

Custom branding: Your OEM changes are cleanly integrated, packaged and distributed in the final artifacts.

Keeping Up With Joget Source Code Updates

Joget’s open-source jw-community repository and OEM Edition evolves over time. To keep your OEM Edition up to date:

Watch for updates in the wflow-install folder of jw-community and oem-enterpriseweb in OEM Edition latest package. If any changes is identified, you’ll want to mirror those changes in my-oem-repo.

Copy updated files from the latest version of wflow-install and oem-enterpriseweb while preserving your customizations.

Maintain a changelog for your own updates to make merging or comparing easier later.

Regularly test your generated installers to ensure compatibility with newer Joget versions and other components like MariaDB, Tomcat or Java JDK.