Installing MOTECH Using Docker (“Beta”)¶

Note

These instructions assume you’re running on Ubuntu. This setup is also possible on Mac OSX but the steps are slightly different. We hope to provide OSX instructions in future. Docker Compose isn’t currently supported in Boot2Docker because it uses Tiny Core Linux. The Docker team is working on native Windows support and will integrate Docker Compose in the future. If using Windows, it’s best to setup an Ubuntu virtual machine using Vagrant and installing it to the Vagrant virtual machine. Make sure to dedicate at least 2GB of RAM to this virtual machine.

This document provides instructions for creating a MOTECH environment using Docker containers. These instructions are “in beta” (the official installation guide is still the one here), but many members of the MOTECH dev team have been following this approach with success. This installation method is much faster than the official route.

There are two supported ways to install MOTECH with Docker:

As an implementer - follow this approach if you want to install a released version of MOTECH.
As a developer - follow this approach if you will be developing MOTECH and want to build the platform and modules from source code.

Get Docker, Docker-Compose and motech-docker¶

Whether you’re installing as an implementer or a developer, you’ll need Docker and Docker-Compose:

Docker¶

Follow the instructions on the Docker website to get the latest version of Docker.

Execute the following to configure Docker to work for non-root users:

sudo groupadd docker
sudo gpasswd -a ${USER} docker (logout and re-login)
sudo service docker restart

Docker-Compose —

Execute the following to install Docker-Compose in Linux:

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

If you get a memory error, you may need to run these commands in root (sudo -i)

motech-docker¶

Clone the motech-docker project from GitHub or download it as a zip file and extract it. You’ll need to run all commands from the motech-docker directory.

sudo apt-get install git
git clone https://github.com/motech/motech-docker
cd motech-docker

Implementer Setup¶

Go to your motech-docker directory. To setup as an implementer (everything is automagically installed):

./setup_as_imp.sh

Type the following to start MOTECH in the background:

docker-compose up -d

Voila! MOTECH has started. Wait a little bit (about 30s) then direct your browser to: http://localhost:8080/motech-platform-server

Note

‘docker-compose up’ ERASES ALL YOUR DATA (well not really all, but pretend it does). You have to run it at least once to setup MOTECH. If you run it again, it’ll erase everything you did in MOTECH. It’s useful to start afresh, but remember: it nukes everything!

Developer Setup¶

Go to your motech-docker directory. To setup as a dev:

./setup_as_dev.sh

Type the following to start all the pieces that MOTECH needs to run in the background:

docker-compose up -d

Once you start the containers with the docker-compose up -d command above and before you build MOTECH for the first time. If you wish to add additional modules to MOTECH, then you can either use the Admin UI or copy them into /root/.motech/bundles directory of the container.

Conveniently, the container’s /root/.motech/bundles directory is exposed as the docker-motech-bundles directory (with a-rw access) in your home directory (also note that the container’s /root/.motech/config dir is also exposed as ~/docker-motech-config). So, you can either manually copy the binaries you require, or you can create a symbolic link to ~/docker-motech-bundles from ~/.motech/bundles.

Assuming the latter, and that you never built MOTECH before, you’d run the following commands:

# go to your home dir
cd
# create the .motech dir
mkdir .motech
# create the symlink
ln -s ~/docker-motech-bundles .motech/bundles

If you built MOTECH before, you can just delete the bundles directory and create the symlink using the command above.

Build, deploy and run MOTECH: see :doc:dev_install.

Note

For your convenience, the max upload in the Tomcat Manager is already increased to accept the MOTECH war.

Some Useful Docker Compose Commands¶

Stop MOTECH¶

docker-compose stop

Restart MOTECH¶

docker-compose start

Watching logs¶

To watch all the logs (very verbose):

docker-compose logs

To watch only the tomcat logs:

docker-compose logs tomcat

See the sections in the generated docker-compose.yml to see what other logs you can watch.