Installation Guide - WorldHealthOrganization/d2-docker GitHub Wiki
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:
If you don’t have yet an organizations created for your group team, create one in Organizations:
Now we can create the two repositories we need (dhis2-core and dhis2-data) in section Repositories with public or private access:
And finally create/edit the teams and its permissions over the repositories:
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:
$ 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
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
For end user commands (like starting or stopping instances, please refer to the end-user manual
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
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
$ 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
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
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
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.
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
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