Imagine… Imagine if you could setup a new Mendix hosting environment in seconds, everywhere. A lightweight, secure and isolated environment where you just have to talk to a RESTful API to deploy your MDA (Mendix Deployment Archive) and start your App.
Since the 2nd quarter of this year a great piece of software became very popular to help to achieve this goal: Docker. Docker provides a high-level API on top of Linux Containers (LXC), which provides a lightweight virtualization solution that runs processes in isolation.
tl;dr
Run a Mendix App in a Docker container in seconds:
root@host:~# docker run -d mendix/mendix
root@host:~# curl -XPOST -F model=@project.mda http://172.17.0.5:5000/upload/
File uploaded.
root@host:~# curl -XPOST http://172.17.0.5:5000/unpack/
Runtime downloaded and Model unpacked.
root@host:~# curl -XPOST -d "DatabaseHost=172.17.0.4:5432" -d "DatabaseUserName=docker" -d "DatabasePassword=docker" -d "DatabaseName=docker" http://172.17.0.5:5000/config/
Config set.
root@host:~# curl -XPOST http://172.17.0.5:5000/start/
App started. (Database updated)
root@host:~#
Docker
There has been a lot of buzz around Docker since its start in March 2013. Being able to create an isolated environment once, package it up, and run it everywhere makes it very exciting. Docker provides easy-to-use features like Filesystem isolation, Resource isolation, Network isolation, Copy-on-write, Logging, Change management and more.
For more details about Docker, please read “The whole story”. We’d like to go on with the fun stuff.
Mendix on Docker
Once a month a so-called FedEx Day (Research Day, ShipIt day, Hackatron) is organized at Mendix. On that day, Mendix developers have the freedom to work on whatever they want. We’ve been playing with Docker a couple of Research Day’s ago. Just see how it works, that kind of stuff. But this time we really wanted to create something we’d potentially use in production. A proof of concept how to run Mendix on Docker.
The plan:
- Create a Docker Container containing all software to run Mendix
- Create a RESTful API to upload, start and stop a Mendix App within that container
What about the database, you may be wondering? We’ll just use a Docker container that provides us a PostgreSQL service! You can also build your own PostgreSQL container or use an existing PostgreSQL server in your network.
Start off with an image:
This is what we are building. A Docker container containing:
- All required software to run a Mendix App, like the Java Runtime Environment and the m2ee library
- A RESTful API (m2ee-api) to upload, start and stop an App (listening on port 5000)
- A webserver (nginx), to serve static content and proxy App paths to the Mendix runtime (listening on port 7000)
- When an App is deployed the Mendix runtime will be listening on port 8000 locally
Building the base container
Before we can start to install the software, we need a base image. A minimal install of an operating system like Debian GNU/Linux, Ubuntu, Red Hat, CentOS, Fedora, etc. You could download a base container from the Docker Index. But because this is so basic and we’d like to create a Mendix container we can trust 100% (a 3rd party base image could contain back-doors), we created one ourselves.
A Debian GNU/Linux Wheezy image:
debootstrap wheezy wheezy http://cdn.debian.net/debian
tar -C wheezy -c . | docker import - mendix/wheezy
That’s all! Let’s show the image we’ve just created:
root@host:~# docker images
REPOSITORY TAG IMAGE ID CREATED VIRTUAL SIZE
mendix/wheezy latest 1bee0c7b9ece 6 seconds ago 218.6 MB
root@host:~#
Building the Mendix container
On top of the base image we just created, we can start to install all required software to run Mendix. Creating a Docker container can be done using a Dockerfile. It contains all instructions to provision the container and information like what network ports to expose and what executable to run (by default) when you start using the container.
There is an extensive manual available about how to run Mendix on GNU/Linux. We’ve used this to create our Dockerfile. This Dockerfile also installs files like /home/mendix/.m2ee/m2ee.yaml, /home/mendix/nginx.conf and /etc/apt/sources.list. They must be in your current working directory when running the docker build command. All files have been published to GitHub.
To create the Mendix container run:
docker build -t mendix/mendix .
That’s it! We’ve created our own Docker container! Let’s show it:
root@host:~#
REPOSITORY TAG IMAGE ID CREATED VIRTUAL SIZE
mendix/mendix latest c39ee75463d6 10 seconds ago 589.6 MB
mendix/wheezy latest 1bee0c7b9ece 3 minutes ago 218.6 MB
root@host:~#
Our container has been published to the Docker Index: mendix/mendix
The RESTful API
When you look at the Dockerfile, it shows you it’ll start the m2ee-api on startup. This API will listen on port 5000 and currently supports a limited set of actions:
GET /about/ # about m2ee-api
GET /status/ # app status
GET /config/ # show configuration
POST /config/ # set configuration
POST /upload/ # upload a new MDA
POST /unpack/ # unpack the uploaded MDA
POST /start/ # start the app
POST /stop/ # stop the running app
POST /terminate/ # terminate the running app
POST /kill/ # kill the running app
POST /emptydb/ # empty the database
Usage
Now that we’ve created the container and published it to the Docker Index we can start using it. And not only we can start using it. Everyone can!
Pull the container and start it.
root@host:~# docker pull mendix/mendix
Pulling repository mendix/mendix
c39ee75463d6: Download complete
eaea3e9499e8: Download complete
...
855acec628ec: Download complete
root@host:~# docker run -d mendix/mendix
bd7964940dfc61449da79cddd1c0e8845d61f6ec1092b466e8e2e582726a5eea
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
bd7964940dfc mendix/mendix:latest /bin/su mendix -c /u 19 seconds ago Up 18 seconds 5000/tcp, 7000/tcp tender_hawkings
root@host:~# docker inspect bd7964940dfc | grep IPAddress | awk '{ print $2 }' | tr -d ',"'
172.17.0.5
root@host:~#
In this container the RESTful API started and is now listening on port 5000. We can for example ask for its status or show its configuration.
root@host:~# curl -XGET http://172.17.0.5:5000/status/
The application process is not running.
root@host:~# curl -XGET http://172.17.0.5:5000/config/
{
"DatabaseHost": "127.0.0.1:5432",
"DTAPMode": "P",
"MicroflowConstants": {},
"BasePath": "/home/mendix",
"DatabaseUserName": "mendix",
"DatabasePassword": "mendix",
"DatabaseName": "mendix",
"DatabaseType": "PostgreSQL"
}
root@host:~#
To run an App in this container, we first need a database server. Pull a PostgreSQL container from the Docker Index and start it.
root@host:~# docker pull zaiste/postgresql
Pulling repository zaiste/postgresql
0e66fd3d6a6f: Download complete
27cf78414709: Download complete
...
046559147c70: Download complete
root@host:~# docker run -d zaiste/postgresql
9ba56a7c4bb132ef0080795294a077adca46eaca5738b192d2ead90c16ac2df2
root@host:~# docker ps
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
9ba56a7c4bb1 zaiste/postgresql:latest /bin/su postgres -c 22 seconds ago Up 21 seconds 5432/tcp jolly_darwin
bd7964940dfc mendix/mendix:latest /bin/su mendix -c /u 30 seconds ago Up 29 seconds 5000/tcp, 7000/tcp tender_hawkings
root@host:~# docker inspect 9ba56a7c4bb1 | grep IPAddress | awk '{ print $2 }' | tr -d ',"'
172.17.0.4
root@host:~#
Now configure Mendix to use this database server.
root@host:~# curl -XPOST -d "DatabaseHost=172.17.0.4:5432" -d "DatabaseUserName=docker" -d "DatabasePassword=docker" -d "DatabaseName=docker" http://172.17.0.5:5000/config/
Config set.
root@host:~# curl -XGET http://172.17.0.5:5000/config/
{
"DatabaseHost": "172.17.0.4:5432",
"DTAPMode": "P",
"MicroflowConstants": {},
"BasePath": "/home/mendix",
"DatabaseUserName": "docker",
"DatabasePassword": "docker",
"DatabaseName": "docker",
"DatabaseType": "PostgreSQL"
}
root@host:~#
Upload, unpack and start an MDA:
root@host:~# curl -XPOST -F model=@project.mda http://172.17.0.5:5000/upload/
File uploaded.
root@host:~# curl -XPOST http://172.17.0.5:5000/unpack/
Runtime downloaded and Model unpacked.
root@host:~# # set config after unpack (unpack will overwrite your config)
root@host:~# curl -XPOST -d "DatabaseHost=172.17.0.4:5432" -d "DatabaseUserName=docker" -d "DatabasePassword=docker" -d "DatabaseName=docker" http://172.17.0.5:5000/config/
Config set.
root@host:~# curl -XPOST http://172.17.0.5:5000/start/
App started. (Database updated)
root@host:~#
Check if the application is running:
root@host:~# curl -XGET http://172.17.0.5:7000/
-- a lot of html --
root@host:~# curl -XGET http://172.17.0.5:7000/xas/
-- a lot of html --
root@host:~#
Great success! We’ve deployed our Mendix App in a completely new environment in seconds.
Reflection
Docker is a very powerful tool to deploy lightweight, secure and isolated environments. The addition of a RESTful API makes it very easy to deploy and start Apps.
One of the limitations after finishing this is that the App isn’t reachable from the outside world. The port redirection feature from Docker can be used for that. To run more Mendix containers on one host there must be some kind of orchestrator on the Docker host that administrates the containers and keeps track of what is running where.
The RESTful API provides a limited set of features in comparison with m2ee-tools. When you start your App using m2ee-tools and your database already contains data, the CLI will ask you kindly what to do. Currently the m2ee-api will just try to upgrade the database scheme if needed and start the App without a notice.