Imixs-Cloud – a Lightweight Docker Swarm Environment

The Imixs-Project started the new subproject Imixs-Cloud.

Imixs-Cloud is a conceptual infrastructure project, describing a way to create a server environment for business applications. One of the main objectives of this project is to focus on simplicity and transparency. The general idea is to setup a lightweight docker based infrastructure with docker swarm. Within this infrastructure business applications like Imixs-Office-Workflow can be deployed in a fast and easy way.
Imixs-Cloud is developed as part of the Open Source project Imixs-Workflow and continuous under development. To contribute to this project please report any issues here. All source are available on Github.

How to use Environment Variables in WildFly Docker Containers

When setting up a Wildfly server, it is possible to use environment variables in the standalone.xml file by using the Bean Shell expression.

See the following example which sets up the database, user and password in a database configuration in the standalone.xml file by accessing environment variables:

<datasource jta="true" jndi-name="java:/jdbc/my_datasource" pool-name="my_pool" enabled="true" use-ccm="true">
    <connection-url>${env.POSTGRES_CONNECTION}</connection-url>
    <driver-class>org.postgresql.Driver</driver-class>
    <driver>postgresql</driver>
    <security>
      <user-name>${env.POSTGRES_USER}</user-name>
      <password>${env.POSTGRES_PASSWORD}</password>
    </security>
</datasource>

With the Bean Shell expression it is not necessary to turning parameters into System Properties: just use the expression:

${env.SYSTEM_ENVIRONMENT_VAR}

Especially when running wildfly in a docker container, this can be very helpful, because you can pass through environment variables to the container:

docker run --name="wildfly" -d -p 8080:8080 -p 9990:9990 \
    -e WILDFLY_PASS="admin_password" \
    -e POSTGRES_USER="my-postgres-user" \
    -e POSTGRES_PASSWORD="mypassword" \
    -e POSTGRES_CONNECTION="jdbc:postgresql://postgres/mydb" \
    imixs/wildfly

Also in combination with docker-compose environment variables can be set in the docker-compose.yml file. See the next example of a docker-compose.yml file, which sets up a postgres service and a wildfly service with a connection pool configuration as defined before in the standalone.xml:

postgres:
 image: postgres:9.6.1
 environment:
 POSTGRES_PASSWORD: mypassword
 POSTGRES_DB: mydb

mywildflyservice:
 image: imixs/mywildfly
 environment:
 POSTGRES_USER: "my-postgres-user"
 POSTGRES_PASSWORD: "mypassword"
 POSTGRES_CONNECTION: "jdbc:postgresql://postgres/mydb"
 ports:
 - "8080:8080"
 - "9990:9990"
 - "8787:8787"
 links: 
 - postgres:postgres

This is an example, which we use in combination with the wildfly docker container provided by the Imixs-Workflow project.

How to Run a Custom Build of Imixs-Office-Workflow Using Docker

The Imixs-Workflow project supports Docker and provides also a Docker image for the workflow management suite ‘Imixs-Office-Workflow‘. Imixs-Office-Workflow provides a full featured business process management suite and can also be used to be extended in various ways. With Docker it becomes easy to setup a custom build for development, test and productive environments.

Setup a New Custom Build

To setup a new custom build of Imixs-Office-Workflow you can use the Imixs-Office-Archetype maven project, which provides a simple starting point for custom development. To run you custom build using Docker you should add a docker folder into your project with the following structure:

-/.data
-/.deployments
-/configuration
 |-standalone.xml
-docker-compose.yml
-Dockerfile

Customize Wildfly standalone.xml

First you can use the standalone.xml file located in the /configuration folder to configure your wildfly server to your project needs. Typically this will be a data-pool configuration and a security realm. This is an example of a custom database pool configuration which can be run in a docker container to access a postgres database running in another Docker container:

...
  <datasource jta="true" jndi-name="java:/jdbc/office-test" pool-name="office-test" enabled="true" use-ccm="true">
 <connection-url>jdbc:postgresql://postgres/office-test</connection-url>
 <driver-class>org.postgresql.Driver</driver-class>
 <driver>postgresql-9.3-1102.jdbc41.jar</driver>
 <security>
 <user-name>postgres</user-name>
 <password>adminadmin</password>
 </security>
 <validation>
 <validate-on-match>false</validate-on-match>
 <background-validation>false</background-validation>
 </validation>
 <timeout>
 <set-tx-query-timeout>false</set-tx-query-timeout>
 <blocking-timeout-millis>0</blocking-timeout-millis>
 <idle-timeout-minutes>0</idle-timeout-minutes>
 <query-timeout>0</query-timeout>
 <use-try-lock>0</use-try-lock>
 <allocation-retry>0</allocation-retry>
 <allocation-retry-wait-millis>0</allocation-retry-wait-millis>
 </timeout>
 <statement>
 <share-prepared-statements>false</share-prepared-statements>
 </statement>
 </datasource>
 ...

Note that the connection-url points to the host ‘postgres’ which need to be linked later to this container.

The Dockerfile

Next you can create a custom Dockerfile to describe you Imixs-Office-Workflow container for your custom build:

FROM imixs/office-workflow:latest
# add custom standalone.xml file
ADD configuration/standalone.xml /opt/wildfly/standalone/configuration/

The Dockerfile is quite simple. It extends the office imixs/office-workflow container and adds the new custom configuration file standalone.xml into the container

Docker-Compose

We use now docker-compose to describe the environment where we run a PostgreSQL Server, a WildFly Application Server and our custom build of Imixs-Office-Workflow.

 postgresloml:
  image: postgres:9.4.6
  environment:
    POSTGRES_PASSWORD: adminadmin
    POSTGRES_DB: office-test
  volumes:
    - ./.data/db:/var/lib/postgresql/data

 officetest:
  build: .
  environment:
    WILDFLY_PASS: adminadmin
  ports:
    - "8080:8080"
    - "9990:9990"
  links: 
    - postgresloml:postgres
  volumes:
   - "./.deployments:/opt/wildfly/standalone/deployments"

The docker-compose.yml file describes the PostgreSQL container with a custom database named ‘office-test’ (see the standalone.xml file), and a new imixs/ofifce-workflow container running our custom build of Imixs-Office-Workflow. The volumes parameter binds the local ./deployments/ folder which is used for autodeployments our application artifacts and also to configure hot-deployment during the development phase.

To start the environment simply run:

docker-compose up

That’s it! Now you can deploy your application aretfact of Imixs-Office-Workflow together with ah postgresql-jdbc.jar file into the local ./deploymetns folder.

After you access Imixs-Office-Workflow from your web browser (http://localhost:8080/office-test) the default user account ‘admin’ with the default password ‘adminadmin’ will be created and can be changed from the Admin section

 

Docker-Compose – How To Install

The Imixs-Workflow project supports Docker and provides several Docker containers to run business applications like Imixs-Office-Workflow on a Docker host. A business application like Imixs-Office-Workflow requires to start different containers to separate the database form the application/web server. With the help of the Docker Tool ‘Docker-Compose’ the  definition of multi-container Docker applications is quite simple. The Imixs project provides different Docker-Compose definitions stored in a docker-compose.yml file.

The Installation

The following installation guide is written for linux users. For other plattforms see the installation guide here.

Fist download docker-compose sources from GitHub and change mod with the following command:

curl -L https://github.com/docker/compose/releases/download/1.7.0/docker-compose-`uname -s`-`uname -m` > /usr/local/bin/docker-compose
 chmod +x /usr/local/bin/docker-compose

After installation you should verify the installation with the following command::

docker-compose --version

this should result in something like:

docker-compose version 1.7.0, build 0d7bf73

How to downgrade the docker-compose

Depending on you docker installation it can be result in a version conflict between Docker and Docker-Compose after a manual installation. You will see an errer message when starting docker-compose like the following:

client and server don't have same version (client : 1.18, server: 1.17)

In this case you can easily install a lower version of docker-compose with the curl command as shown above.

Run Docker-Compose

After you have installed Docker-Compose successfully you can start a multi-container Docker application with the following command:

docker-compose up

You can run the containers in background:

docker-compose up -d

to stop all containers run:

docker-compose stop