CustomBuild

How to Create a Custom Build

Imixs-Office-Workflow is a powerful and highly customizable application platform. Although Imixs-Office-Workflow out can be used of the box as a standard application, it is also possible to create a so-called custom build. A custom build inherits all the functionality of the Imixs-Office-Workflow but also provides the ability to add or customize new features. The following tutorial shows how you can setup a custom build within minutes.

Preconditions

Imixs-Office-Workflow is a Java Enterprise Application. You don't have to be a Java EE developer, however, it is useful to be familiar with the concepts of Java and Java EE. Imixs-Office-Workflow itself is running on an application server. With the help of Docker a manual installation of a Java EE application server is not required. If you go through this tutorial, the application will be deployed into a docker container. This Docker image can also be used in production environment, though, a custom configuration is recommended for most cases.

Checkout Sources

Although it is not absolutely necessary, it simplifies the development of a custom build, when you can have a look at the source code of Imixs-Office-Workflow. For this reason, we recommend the sources of which are available on GitHub to import in a suitable development environment.

Maven 3.x

Imixs-Office-Workflow can be build with maven. It is recommended that you have installed Apache Maven 3.0 or higher. Also you should be familiar with the build concept of maven.

Let's get Started!

Now we can start with the custom build. As Imixs-Office-Workflow is based on Maven even the custom build is created by Maven Archetype. You can change the behaviour and layout of your custom build without conflicting with any updates made by the Imixs project. Also you can easily upgrade to any new version of Imixs-Office-Workflow.

Add the Imixs Maven repository

Before you can create a custom build from the imixs-office-archetype you need to add the Imixs Repository server to your maven configuration. Open your maven settings.xml ([USERHOME]/.m2/settings.xml) and add the imixs server to your default maven profile configuration section:

....
 ......
 <profiles>
        <profile>
            <id>default</id>
             <repositories>          
             <!-- Imixs Maven Repository -->
                <repository>
                    <id>imixs-repository</id>
                    <name>Imixs Maven Repository</name>
                    <url>http://www.imixs.org/maven/</url>
                    <layout>default</layout>
                </repository>
            </repositories>
        </profile>
    </profiles>
    <activeProfiles>
        <activeProfile>default</activeProfile>
    </activeProfiles>
.....

Now you can create a new maven project based on the latest version of the archetype

Creating a custom build using Eclipse

To create a new maven project from an archetype you can use the Eclipse IDE with the Maven Plugin (m2e). This Eclipse plugin provides an easy wizard to create a new maven project based on an archetype.

1. From the main menue choose 'File -> New -> other'
2. Select 'Maven -> Maven Project' and click next
3. Leave the default creation setup and click next again
4. Now search for the Imixs archetype by entering 'com.imixs.workflow'. Eclipse will search the repository for the latest archetype
5. Click next to setup your project, choose a groupID and artifactID
6. Click finish to create the project

It is also possible to create a custom build using maven command line tool:

mvn archetype:generate -Dfilter=imixs-office

Run with Docker

Imixs-Office-Workflow provides a Docker Container to run the service on any Docker host. The docker image is based on the docker image imixs/wildfly.

Docker for Development

Developers can use a docker image for testing and the development of new features. To build a new container first build the maven artefact running:

mvn clean install -Pdocker

To start Imixs-Office-Workflow with docker the docker-compose command can be used:

docker-compose up

Note: this command will start two containers, a postgreSQL server and a Wildfly Server. See the docker-compose.yml file for the configuration details.

Mount Points

The default configuration sets a local mount point at the following location:

~/git/imixs-office-workflow/src/docker/.deployments

Make sure that this directory exits. During development new versions can easily deployed into this directory which is the auto-deployment folder of Wildfly. For further details see the imixs/wildfly docker image.

Docker for Production

To run Imixs-Office-Workflow in a Docker production environment the project proveds serveral additional maven profiles:

docker-build

With the profile 'docker-build' a docker container based on the current version of Imixs-Office-Workflow is created locally

mvn clean install -Pdocker-build

docker-push

With the 'docker-push' profile the current version of Imixs-Office-Workflow can be pushed to a remote repository:

mvn clean install -Pdocker-push -Dorg.imixs.docker.registry=localhost:5000

where 'localhost:5000' need to be replaced with the host of a private registry. See the docker-push command for more details.

docker-hub

Imixs-Office-Workflow is also available on Docker-Hub. The public docker images can be used for development and production. If you need technical support please contact imixs.com