Installing MOTECH Using Docker (“Beta”)


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.

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:

  1. As an implementer - follow this approach if you want to install a released version of MOTECH.
  2. 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, Fig and motech-docker

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


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

  2. 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


Execute the following to install Fig:

sudo apt-get install python-pip python-dev build-essential
sudo pip install -U fig


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

Implementer Setup

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


Type the following to start MOTECH in the background:

fig up -d

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


‘fig 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:


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

fig up -d

Once you start the containers with the fig up -d command above and before you build MOTECH for the first time, you need to copy the MOTECH binaries into the container’s /root/.motech/bundles directory.

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 necessary binaries, 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
# 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.

Some Useful Fig Commands


fig stop

Restart MOTECH

fig start

Watching logs

To watch all the logs (very verbose):

fig logs

To watch only the tomcat logs:

fig logs tomcat

See the sections in the generated fig.yml to see what other logs you can watch.