Installation Guide - WorldHealthOrganization/d2-docker GitHub Wiki

PREPARING A DOCKER HUB ORGANIZATION

D2-docker​ uses two custom images to run DHIS2 instances:

-dhis2-core: Contains Tomcat​ that deploys the dhis.war​ bundle.

-dhis2-data​: Contains a database dump and the directory with the DHIS2 web apps.

We use Docker Hub​ to store those images. If you don’t have yet an account on the Docker Hub, go to its main page and click on​ Sign up​:

imagen

imagen

If you don’t have yet an organizations created for your group team, create one in Organizations:

imagen

Now we can create the two repositories we need (​dhis2-core​ and dhis2-data​) in section Repositories​ with public or private access​:

imagen

And finally create/edit the teams and its permissions over the repositories:

imagen

imagen

INSTALLING d2-docker

You can either download ​d2-docker.zip​ or clone the source repository using git:

$ git clone ​https://github.com/EyeSeeTea/d2-docker

For GNU/Linux, install the contents from non-admin user with sudo permissions (entering the d2-docker folder first):

$ cd d2-docker

$ sudo python3 setup.py install

For Windows, run a terminal as an Administrator and run:

imagen

$ cd d2-docker

$ python setup.py install

NOTE:​ In case you changed the location where you downloaded d2-docker, please change the “cd” command accordingly to access the d2-docker folder

COMMAND SYNTAX

D2-docker uses a single executable with subcommands (start, stop, ...) with this structure:

$ d2-docker [GLOBAL_OPTIONS] COMMAND [COMMAND_OPTIONS]

The complete interface:

$ d2-docker --help

usage: d2-docker [-h] [--dhis2-docker-images-directory DIRECTORY]

[--log-level NOTSET | DEBUG | INFO | WARNING | ERROR | CRITICAL]

{start,logs,stop,commit,push,copy,export,import,list,run-sql,create}

...

positional arguments:

{start,logs,stop,commit,push,copy,export,import,list,run-sql,create} Subcommands

start Start a container from an existing dhis2-data Docker image or from an exported file

logs Show docker logs

stop Stop docker containers

commit Commit docker images

push Push dhis2-data docker image

copy Copy databases from/to docker containers

export Export d2-docker images to a single file

import Import d2-docker images from file

list List d2-docker data images

run-sql Run SQL or open interactive session in a d2-docker container

create Create d2-docker images

optional arguments:

-h, --help show this help message and exit

--dhis2-docker-images-directory DIRECTORY Directory containing dhis2-data docker source code

--log-level NOTSET | DEBUG | INFO | WARNING | ERROR | CRITICAL Run command with the given log level

MAINTAINING d2-docker

For end user commands (like starting or stopping instances, please refer to the ​end-user manual

Setup: create the base images

Example with version 2.30 and an ento​ database:

$ d2-docker create core eyeseetea/dhis2-core:2.30 --version=2.30

And now create your data images:

$ d2-docker create data eyeseetea/dhis2-data:2.30-ento --sql=db-ento.sql.gz --apps=path/to/apps/

$ d2-docker create data eyeseetea/dhis2-data:2.30-ento-gh --sql=db-ento-gh.sql.gz # No apps

Make an instance backup

Extract data image eyeseetea/dhis2-data:2.30​ (DB + apps) to the local directory ​eyeseetea-dhis2-data-2.30​:

$ d2-docker copy eyeseetea/dhis2-data:2.30 eyeseetea-dhis2-data-2.30

$ ls eyeseetea-dhis2-data-2.30/

apps db.sql.gz

You can restore it with the same command, just swapping the arguments:

$ d2-docker copy eyeseetea-dhis2-data-2.30 eyeseetea/dhis2-data:2.30

Backup: export and import to/from a single file

$ d2-docker export -i eyeseetea/dhis2-data:2.30 eyeseetea-dhis2-data-2.30.tgz

You can now copy ​ eyeseetea-dhis2-data-2.30.tgz​ to another machine and run an ​import​ command:

$ d2-docker import eyeseetea-dhis2-data-2.30.tgz

Clone one instance

The ​_copy​_ command also allows creating new images from existing ones:

$ d2-docker copy eyeseetea/dhis2-data:2.30 anotherorg/dhis2-data:2.30-cloned

Modify and commit changes

First, start the image you want to work on:

$ d2-docker start eyeseetea/dhis2-data:2.30-ento --detach

Make all the changes you need and when done, run this command to update the local image​:

$ d2-docker commit

Now you might publish the Docker image with a ​push​ command:

$ d2-docker push

Alter DHIS2 databases

Execute a sql file in an instance using command ​run-sql​:

$ d2-docker run-sql -i eyeseetea/dhis2-data:2.30-ento somefile.sql

If no file is specified, an interactive psql​ terminal will open:

$ d2-docker run-sql -i eyeseetea/dhis2-data:2.30-ento

psql (9.6.14)

Type "help" for help.

dhis2=#

It may be also useful to run some initializing SQL everytime an image is started. An example:

$ d2-docker start eyeseetea/dhis2-data:2.30-ento --run-sql=directory-with-sql-files

directory-with-sql-files should contain .sql, .sql.gz​ or .dump​ files. Those files will be imported after the DB initialization process is finished but before Tomcat is started.

Upgrade a DHIS2 instance in the docker

Update to the latest 2.30 for an existing core image:

$ d2-docker create core eyeseetea/dhis2-core:2.30 --version=2.30

Or use a local WAR​ file:

$ d2-docker create core eyeseetea/dhis2-core:2.30 --war=dhis.war

Cleaning-up

Docker infrastructure (images, networks, containers, volumes) takes up a lot of hard-disk space.

Remove all local volumes not used by at least one container:

$ docker volume prune

Remove all stopped containers:

$ docker container prune

Remove all dangling images (the temporal images that have on its name/tag):

$ docker image prune

[WARNING: Dangerous operation] This command deletes all stopped containers, networks, volumes, images and cache. Note, that any ​ dhis2-data​ image will be also deleted whether the instance is running or nor (as the data container is not running), so make sure it’s pushed to the hub if you want to keep the data.

$ docker system prune -a --volumes

⚠️ **GitHub.com Fallback** ⚠️