Imixs-Cloud is an open infrastructure project, providing a lightweight docker based container environment for production business applications. The main objectives of this project are simplicity, transparency and operational readiness.
The Imixs-Cloud is based on a docker swarm cluster environment. Docker swarm is much easier to setup and in its management compared to a Kubernetes cluster. However, when deciding which platform to use, you should consider your own criterias. 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 of the Imixs-Cloud project can be itemized under the following rules:
- A new environment can be setup easily and run on commodity hardware.
- The docker command line interface (CLI) is all you need to know to setup and manage the environment.
- Scalabillity and configuration is managed by the core concepts of docker-swarm and docker-compose.
- Docker Images can be deployed to a central Docker-Registry which is part of the environment.
- All services are isolated and accessible through a central reverse proxy server.
- The environment configuration can be managed by a private code repository like Git.
- Docker UI Front-End services are used to monitor and manage the infrastructure.
For a quick setup you need at least a Debian 10 server with a public internet address and a user with sudo privileges.
-
from your users home directory first install git
$ sudo apt-get install -y git -
clone the imixs-cloud repo from github....
$ cd && git clone https://github.com/imixs/imixs-cloud.git -
start the setup script
$ sudo ./imixs-cloud/scripts/setup.sh [YOUR_SERVR_IP_ADDRESS]
replace [YOUR_SERVR_IP_ADDRESS] with your servers public IP address
-
create the overlay networks withon your swarm:
$ docker network create --driver=overlay imixs-cloud-net $ docker network create --driver=overlay imixs-proxy-net
Finally you can launch the portainer Web UI:
$ docker stack deploy -c ~/imixs-cloud/management/portainer/docker-compose.yml portainer
That's it! You can now access your swarm from your browser:
http://[YOUR_SERVR_IP_ADDRESS]:8200
Continue reading for more details...
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 docker swarm. The infrastructure can be easily scaled by adding new worker nodes.
There a several solutions to manage a Docker Swarm through a modern web based user interface. You will find examples in the Setup Guide.
The complete infrastructure of a Imixs-Cloud environment is described in a central configuration directory. The Configuration Directory can be synchronized with a code repository like Git. This makes it easy to setup the environment on a new manager node.
/-
|+ management/
|- monitoring/
|- portainer/
|- registry/
|- traefik/
|+ apps/
|+ MY-APP/
| docker-compose.yml
.....
The /management/ sub-folder 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 copy this structure from GitHub to setup and create your own Imixs-Cloud environment.
$ git clone https://github.com/imixs/imixs-cloud.git && rm -rf imixs-cloud/.git/
Optional you can also fork the repo directyl on Github.
Imixs-Cloud is based on docker and its build in tool chain. Docker-Swarm is the scheduler service 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 setup Imixs-Cloud - basic setup information for a docker-swarm.
- The Private Registry - how to setup and work with a private registry.
- How to secure Imixs-Cloud - advanced setup and security information.
- HTTPS support - how to setup HTTPS encryption.
- Version Control - how to setup a Git repo
- Stateful Services - how to deploy stateful services.
- Monitoring - how to monitor the docker-swarm.
After you have setup you own 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. In this file you can define settings and parameters and describe dependencies and linked resources. Each service in a stack can communicate with each other in the same stack over the network services provided by docker.
The following example shows a docker-compose file describing a Wordpress application. The example consists of two services - a MySQL database and a wordpress application:
version: '3.1'
services:
# Wordpress Example
mysql:
image: mysql:5.7
volumes:
- dbdata:/var/lib/mysql
environment:
MYSQL_ROOT_PASSWORD: your_root_password
MYSQL_DATABASE: wordpress
MYSQL_USER: wordpress
MYSQL_PASSWORD: "yourpassword"
deploy:
placement:
constraints:
- node.hostname == worker-1
networks:
- backend
wordpress:
depends_on:
- mysql
image: wordpress:4.9.8
environment:
WORDPRESS_DB_HOST: mysql:3306
WORDPRESS_DB_USER: wordpress
WORDPRESS_DB_PASSWORD: "yourpassword"
volumes:
- wp-content:/var/www/html/wp-content
deploy:
labels:
traefik.port: "80"
traefik.frontend.rule: "Host:your.host.local"
traefik.docker.network: "imixs-proxy-net"
placement:
constraints:
- node.hostname == worker-1
networks:
- frontend
- backend
volumes:
dbdata:
wp-content:
networks:
frontend:
external:
name: imixs-proxy-net
backend:
The Imixs-Cloud provides a reverse proxy concept based on Traefik.io. In the example the wordpress service is mapped to the domain name 'your.host.local'. Traefik.io automatically manages the routing so that your application is available on port 80. In this example both services are bound to a internal overlay network called 'backend'. Only the service 'wordpress' is connected to the external network 'imixs-proxy-net'. As a result, the service 'wordpress' is visible outside of the stack. This is a typical setup to isolate your services from other applications within your cluster environment. Read the Imixs-Cloud setup guide to learn how the proxy network is working.
In the example two data volumes are defined. The volumes are used to persist the data of the MySQL database and the Wordpress content files. The services are placed on a specific host (worker-1) to avoid a lost of data. Of course the data can be persisted on other storage independent from a cluster node.
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
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.
If your stack contains images hosted in a 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'
services:
app:
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. You can setup a private registry in your Imixs-Cloud environment. See the section "The Private Registry"
Imixs-Cloud also provides also a monitoring feature which allows you to monitor your docker-swarm.
The monitoring is based on Prometheus which is an open-source systems monitoring and alerting toolkit. You can use this monitoring service not only to montor your docker-swarm network but also to monitor specific application data. Read more about the monitoring feature here.
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.