A Lightweight Docker Swarm Environment
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.
apps Update README.md Mar 27, 2018
doc doc Jul 26, 2018
management upgrade swarmpit to 1.3 Jan 4, 2018
.gitignore initialized Dec 2, 2017
LICENSE Update LICENSE Dec 29, 2017
README.md doc Jul 27, 2018


The Imixs-Cloud

Imixs-Cloud is a conceptual infrastructure project, describing a lightweight docker based server environment for business applications. The main objectives of this project are simplicity, transparency and operational readiness.

Imixs-Cloud runs on a docker swarm consisting of multiple Docker hosts acting as managers and workers. Imixs-Cloud is optimized to build, run and maintain business services in small and medium-sized enterprises. The project is open source and continuous under development. We sincerely invite you to participate in it!

The Main Objectives

The main objectives of the Imixs-Cloud project can be itemized under the following rules:

  1. A new environment can be setup easily and run on commodity hardware.
  2. The docker command line interface (CLI) is the main interface to setup and manage the environment.
  3. Scalabillity and configuration is managed by the core concepts of docker-swarm and docker-compose.
  4. Docker Images can be deployed to a central Docker-Registry which is part of the environment.
  5. All services are isolated and accessible through a central reverse proxy server.
  6. The environment configuration can be managed by a private code repository like Git.
  7. Docker UI Front-End services are used to monitor the infrastructure.

Basic Architecture

The basic architecture of the Imixs-Cloud consists of the following components:

  • A Docker-Swarm Cluster running on virtual or hardware nodes.
  • One management node, providing central services.
  • One or many worker nodes to run the services.
  • A central Reverse-Proxy service to dispatch requests (listening on port 80).
  • A management UI running on the management node.
  • A private registry to store custom docker images.


A Imixs-Cloud consists of at least two nodes.

  • The management node is the swarm manager and provides a private registry and a reverse proxy service.
  • The worker nodes are serving the business applications.

Only the management node should be visible via the internet. Worker nodes are only visible internally by the swarm. The infrastructure can be easily scaled by adding new worker nodes.

The Configuration Directory

The management node holds the configuration for all services in a central directory which can be synchronized with a code repository like Git. The configuration directory is used to setup and run the Imixs-Cloud and its services. The directory can be located in a project directory and is structured like in the following example:

 |+ management/
    |- registry/
    |- swarmpit/
    |- traefik/
 |+ apps/
    |+ MY-APP/
       |  docker-compose.yml

The /management/ subfolder holds the configuration for all management services running on the management node only. This configuration is maintained by this project and can be customized for individual needs.

The /apps/ directory is the place where the custom business services are configured. Each sub-directory holds at least one docker-compose.yml file to startup the corresponding services. Optional additional configuration files are located in this directory.

You can fork this structure from GitHub to setup and create your own environment.

$ git clone https://github.com/imixs/imixs-cloud.git

How to Setup

Docker-Swarm is used to run a cluster of docker hosts serving business applications in docker-containers. Each node in the swarm has at least installed Docker.

Read the following sections to setup a Imixs-Cloud environment:

How to Manage Services

After you have setup the Imixs-Cloud environment you can deploy and start your custom business services. In Docker-Swarm, containers are started as services within a so called 'stack'. A stack is described by a docker-compose.yml file. Each service of a stack can comunitcate with eachother in the same stack. A docker-compose file looks like this:

version: '3.1'

    image: my-registry.com:8300/apps/my-app:1.0.0
      - frontend
      - backend  
    image: postgres:9.6.1
      - dbdata:/var/lib/postgresql/data
      - backend
      name: imixs-proxy-net 


In this example there a three services, all bound to a internal overlay network called 'backend'. Only the service 'apps/my-app' is connected in addition to the external proxy network, so that only this application is visible outside of the stack. Read the Imixs-Cloud setup guide to learn how the proxy network is working.

docker deploy stack

You can define new custom applications in the /apps/ directory. Each application has its own sub-folder and consists at least of one docker-compose.yml file.

 |+ apps/
    |+ MY-APP/
       |  docker-compose.yml

To deploy and run a custom application within the Imixs-Cloud, you run the docker stack deploy command:

docker stack deploy -c apps/MY-APP/docker-compose.yml MY-APP 

Updating a Stack

If you need to change some configuration or add a new services to a stack, you can restart the already existing stack with the same command. Docker-Swarm will automatically redeploy all affected services.

Running Services form the Private Registry

If your stack contains images hosted on the private registry, you need to specify the registry name and port number to enable docker-swarm to download the image. See the following example:

version: '3'

    image: my-registry.com:8300/app/my-app:1.0.0

To start the stack run the docker command with the option --with-registry-auth.

docker stack deploy -c apps/MY-APP/docker-compose.yml MY-APP --with-registry-auth

This will force the docker service to authenticate against the registry.


Imixs-Cloud is open source and your are sincerely invited to participate in it. If you want to contribute to this project please report any issues here. All source are available on Github.