Skip to main content

DHIS2 Docker

This guide is written with Debian as a starting point, but with minor adaptations will work on any Debian-based system e.g. Ubuntu or Kali.

The steps themselves apply to any system so with some know-how and elbow grease this can be applied to MacOS X or other Linux flavors.

Guide tested on:

  • Linux 4.19.0-6-cloud-amd64 #1 SMP Debian 4.19.67-2+deb10u1 (2019-09-20) x86_64 GNU/Linux
  • Linux 4.19.0-6-amd64 #1 SMP Debian 4.19.67-2+deb10u2 (2019-11-11) x86_64 GNU/Linux

Overview

  • Update system
  • Setup user account
  • Install Node
  • Install Yarn
  • Install Docker
  • Install Nginx (Optional)
  • Install Certbot (Optional)
  • Install D2 CLI
  • Launch development cluster
  • System cleanup (Optional)

Make sure the system is updated

sudo apt-get update
sudo apt-get upgrade

Install the base dependencies we are going to need.

sudo apt-get install gnupg curl

Setup a user account for yourself

New user:

USER=myuser
sudo useradd -U -G sudo -b /home $USER
sudo passwd $USER

Existing user:

USER=myuser
usermod -a -G sudo $USER
newgrp sudo

Install Node

Abbreviated instructions below, if any problems occur see the full Node installation instructions.

Set up the sources.

curl -sSL https://deb.nodesource.com/gpgkey/nodesource.gpg.key | sudo apt-key add -

VERSION=node_12.x
DISTRO="$(lsb_release -s -c)"

echo "deb https://deb.nodesource.com/$VERSION $DISTRO main" | sudo tee /etc/apt/sources.list.d/nodesource.list
echo "deb-src https://deb.nodesource.com/$VERSION $DISTRO main" | sudo tee -a /etc/apt/sources.list.d/nodesource.list

ℹ️ After adding a new source to apt, we need to run the update command.

Install Node.

sudo apt-get update
sudo apt-get install nodejs

Test the Node install with:

which node
node --version

Install Yarn

Full installation instructions

Add the Apt sources.

curl -sS https://dl.yarnpkg.com/debian/pubkey.gpg | sudo apt-key add -
echo "deb https://dl.yarnpkg.com/debian/ stable main" | sudo tee /etc/apt/sources.list.d/yarn.list

Install Yarn.

sudo apt-get update
sudo apt-get install yarn

Test the Yarn install with:

which yarn
yarn --version

Install Docker

While Docker exists in the standard repositories, the versions for Docker and Docker Compose that are considered stable by Debian are too old for us to use, so we need to install the versions that Docker considers stable.

Other distros (e.g. Ubuntu) are faster about adopting new versions, so they may be current enough. Either way, using the Docker repos guarantees functionality, and faster security patches. Which you do want considering what Docker does and fundamentally is.

Installing Docker is more involved than the other commands, the full instructions used for the abbreviated set are provided here:

Install the dependencies.

sudo apt-get update
sudo apt-get install \
     apt-transport-https \
     ca-certificates \
     software-properties-common

Add the Docker source repository to Apt.

curl -fsSL https://download.docker.com/linux/debian/gpg | sudo apt-key add -
sudo add-apt-repository \
     "deb [arch=amd64] https://download.docker.com/linux/debian \
     $(lsb_release -cs) \
     stable"

Install the Docker packages.

sudo apt-get update
sudo apt-get install docker-ce docker-ce-cli containerd.io

Set up a group for Docker. Tt may already exist and if so, that's OK. Simply proceed with the commands after groupadd.

sudo groupadd docker
sudo usermod -aG docker $USER
newgrp docker

If these commands fail, that's OK. If you run into permission errors down the line, come back and run these again.

sudo chown "$USER":"$USER" /home/"$USER"/.docker -R
sudo chmod g+rwx "$HOME/.docker" -R

Change the Docker data root location (Optional)

If you do not want all the Docker data on your main partition (/opt/docker) as it may consume a lot of space, you can change that adding some configuration to the Docker daemon config file in /etc/docker/daemon.json:

echo "{ \"data-root\": \"/custom/docker/data/dir\", \"exec-root\": \"/custom/docker/dir\" }" | sudo tee /etc/docker/daemon.json

Control the Docker service

sudo systemctl start docker

To configure if Docker starts on boot or not:

sudo systemctl enable docker
sudo systemctl disable docker

Install Docker Compose

Docker Compose is a single binary that we can just download and plop into our /usr/local/bin directory. Note that the directory varies from distro to distro, you want the local binary directory for userland.

sudo curl -L "https://github.com/docker/compose/releases/download/1.24.0/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose

Mark it as executable after inspecting the binary.

sudo chmod +x /usr/local/bin/docker-compose

Test out the install with:

which docker-compose
docker-compose --version

Install Nginx (Optional)

The standard package for Nginx is solid and stable.

sudo apt-get update
sudo apt-get install nginx

Setup default site configuration

This overwrites the Nginx default site. If you want to preserve that, add this as a new vhost.

sudo tee /etc/nginx/sites-available/default <<EOF
server {
        listen 80 default_server;
        listen [::]:80 default_server;
        server_name _;
        charset utf-8;

        client_max_body_size       10m;
        client_body_buffer_size    128k;

        proxy_buffer_size          4k;
        proxy_buffers              4 32k;
        proxy_busy_buffers_size    64k;
        proxy_temp_file_write_size 64k;

        gzip on;
        gzip_types
                "application/json;charset=utf-8" application/json
                "application/javascript;charset=utf-8" application/javascript text/javascript
                "application/xml;charset=utf-8" application/xml text/xml
                "text/css;charset=utf-8" text/css
                "text/plain;charset=utf-8" text/plain;

        root /srv/www/;
        index index.html;

        location /dev {
                proxy_pass                http://localhost:8080/dev;
                proxy_redirect            off;
                proxy_set_header          Host               \$host;
                proxy_set_header          X-Real-IP          \$remote_addr;
                proxy_set_header          X-Forwarded-For    \$proxy_add_x_forwarded_for;
                proxy_set_header          X-Forwarded-Proto  https;
        }
}
EOF

Start the Nginx service and enable it to start on boot.

sudo systemctl start nginx
sudo systemctl enable nginx

Install certbot (Optional)

Full installation instructions for certbot.

sudo apt-get install certbot python-certbot-nginx

Run the tool to setup certificates for sites configured in Nginx:

sudo certbot --nginx

ℹ️ After setting up a certificate with certbot, usually I have to clean up my Nginx default config manually.

To simulate a renewal, use:

sudo certbot renew --dry-run

For the real deal run without the --dry-run switch. You will want to do this every month or so.

Install D2 CLI

Can be installed using Yarn (recommended):

yarn global add @dhis2/cli

ℹ️ NPM can be used, but is not recommended for many reasons. If Yarn is unacceptable, use npx @dhis2/cli instead.

Add the global Yarn packages .bin directory to your PATH so that you can easily execute the commands:

tee -a ~/.bash_profile <<EOF
if [ -d "\$HOME/.config/yarn/global/node_modules/.bin" ] ; then
    PATH="\$HOME/.config/yarn/global/node_modules/.bin:\$PATH"
fi
EOF

For shells other than Bash, a different .profile file is needed, e.g. .zsh_profile for ZSH. If no shell specific profile file is found or used, then .profile would work in most cases.

D2 configuration file (Optional)

mkdir -p ~/.config/d2
tee ~/.config/d2/config.js <<EOF
module.exports = {
    cluster: {
        channel: 'stable',
        clusters: {
            dev: {
                channel: 'dev',
                dbVersion: 'dev',
                dhis2Version: 'master',
                customContext: false, // true if using nginx as a reverse proxy
                port: 8080
            },
        },
    },
}
EOF

Launch the development cluster

If you have the ~/.config/d2/config.js file, starting is as easy as:

d2 cluster up dev

Without the configuration file, the equivalent is:

d2 cluster up dev \
    --channel dev \
    --dhis2-version master \
    --db-version dev \
    --port 8080

System cleanup (Optional)

sudo apt-get autoremove
Edit this page