Kobo Docker Setup

Step by step how-to instructions on installing and running KoBo Toolbox on a standalone server.
Revision as of 00:09, 19 February 2018 by Vladimir (talk | contribs)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

Pre-requisites

Decide upon the location

$ cd /home/ate
$ git clone https://github.com/kobotoolbox/kobo-docker.git

The working tree repository will be created in the directory kobo-docker, i.e. /home/ate/kobo-docker. We will set the ystem-wide environment variable to point to this directory:

$ sudo nano /etc/profile.d/kobo-docker.sh
export KOBO_DOCKER="/home/ate/kobo-docker"

This will define the system-wide (environment) variable, available to all users.

$ cd $KOBO_DOCKER && pwd
/home/ate/kobo-docker
KOBO_DOCKER=/home/ate/kobo-docker/

Configure KoBo Docker

$ ln -s docker-compose.server.yml docker-compose.yml
$ sudo docker-compose pull
$ docker-compose build
$ nano envfile.server.txt
# The publicly-accessible domain where your KoBo Toolbox instance will be reached.
PUBLIC_DOMAIN_NAME=msf.org
# The publicly-accessible subdomain for the KoBoForm form building and management interface.
KOBOFORM_PUBLIC_SUBDOMAIN=kobo
# The publicly-accessible subdomain for the KoBoCAT data collection and project management interface.
KOBOCAT_PUBLIC_SUBDOMAIN=kc
# The publicly-accessible subdomain for the Enketo Express web forms.
ENKETO_EXPRESS_PUBLIC_SUBDOMAIN=ee
# See "api key" here: https://github.com/kobotoolbox/enketo-express/tree/master/config#linked-form-and-data-server.
ENKETO_API_TOKEN=fAvPevhvWb1w79XQxSabMKN9mW
# Canonically a 50-character random string. See https://docs.djangoproject.com/en/1.8/ref/settings/#secret-key and https://docs.djangoproject.com/en/1.8/ref/settings/#secret-key.
DJANGO_SECRET_KEY=QE7Vwf7uqYJ8LgLaEZLC9f3AebTCX8DPukue46tYAU7ZyVTbXX
# The initial superuser's username.
KOBO_SUPERUSER_USERNAME=msfuser
# The initial superuser's password.
KOBO_SUPERUSER_PASSWORD=msfOCB1971

######################
# Optional variables #
######################

# For help customizing backup schedules, use a `cron` schedule generator (e.g.
#   crontab.guru). To enable a backup, uncomment the relevant schedule.
# Default KoBoCAT media backup schedule is weekly at 12:00 AM UTC on Sunday.
KOBOCAT_MEDIA_BACKUP_SCHEDULE=51 1 * * *
# Default MongoDB backup schedule is weekly at 01:00 AM UTC on Sunday.
MONGO_BACKUP_SCHEDULE=57 1 * * *
# Default Postgres backup schedule is weekly at 02:00 AM UTC on Sunday.
POSTGRES_BACKUP_SCHEDULE=57 1 * * *

Automatic backup creation

Two structured databases and a collection of files should be backed up, as discussed in Backup Targets and Storage.

$ nano $KOBO_DOCKER/envfile.server.txt
KOBOCAT_MEDIA_BACKUP_SCHEDULE=51 1 * * *
MONGO_BACKUP_SCHEDULE=57 1 * * *
POSTGRES_BACKUP_SCHEDULE=57 1 * * *

Note that the times are expressed in UTC. The example configuration above will create backups just before 3 o'clock (not two) if the Host is in Europe, located in CET time zone. You might also want to try crontab creation tools such as https://crontab.guru, as pointed out in this config file.

Creation of backup archives will now happen automatically, at the times configured above; but to fully round-up and automate the process please follow the instructions in Backup Procedures.

Configure outgoing email

$ sudo nano envfiles/smtp.txt
EMAIL_BACKEND=django.core.mail.backends.smtp.EmailBackend
EMAIL_HOST=smtp.office365.com
EMAIL_PORT=587
EMAIL_HOST_USER=Kobo-OCB@brussels.msf.org
EMAIL_HOST_PASSWORD=DertVzer98
EMAIL_USE_TLS=True
DEFAULT_FROM_EMAIL=Kobo-OCB@brussels.msf.org

Upload SSL Certificates

$ mkdir secrets && cd secrets/
$ nano ssl.crt # - paste your certificate and issuer's chain certificate here
$ nano ssl.key # - paste your private key here

Please refer to the article SSL Setup for more information.

Start the system!

$ sudo docker-compose up -d
$ sudo docker ps
           Name                         Command             State                    Ports<
------------------------------------------------------------------------------------------------------------
kobodocker_nginx_1            /sbin/my_init                 Up      0.0.0.0:443->443/tcp, 0.0.0.0:80->80/tcp
kobodocker_enketo_express_1   /sbin/my_init                 Up      8005/tcp
kobodocker_kobocat_1          /sbin/my_init                 Up      8000/tcp
kobodocker_kpi_1              /sbin/my_init                 Up      8000/tcp
kobodocker_mongo_1            /sbin/my_init                 Up      27017/tcp
kobodocker_postgres_1         /sbin/my_init                 Up      5432/tcp
kobodocker_rabbit_1           /sbin/my_init                 Up      5672/tcp
kobodocker_redis_cache_1      /entrypoint.sh redis-server   Up      6379/tcp
kobodocker_redis_main_1       /entrypoint.sh redis-server   Up      6379/tcp
KoBo-Toolbox-Diagram.png
Are the names on the list familiar? They should be - it is our (living and breathing) instance of the system laid out in the article KoBo Toolbox Architecture.

Well done!

Your KoBo Toolbox has now been set up, and you should be able to log into the system with the initial username and password, as provided in envfile.server.txt.

Should you require to stop KoBo Toolbox, issue the following command:

$ sudo docker-compose down

Make Kobo start with the OS

To make the system start with OS, i.e. restart on every reboot, firstly create the new system service called kobo-toolbox

$ sudo nano /etc/systemd/system/kobo-toolbox.service
[Unit]
Description=Kobo Toolbox containers
Requires=docker.service
After=docker.service

[Service]
Restart=on-failure
ExecStart=/usr/local/bin/docker-compose -f /home/ate/kobo-docker/docker-compose.server.yml up
ExecStop=/usr/local/bin/docker-compose -f /home/ate/kobo-docker/docker-compose.server.yml stop

[Install]
WantedBy=default.target
$ sudo ln -s /etc/systemd/system/kobo-toolbox.service /etc/systemd/system/default.target.wants/kobo-toolbox.service

...then enable the service

$ sudo systemctl enable kobo-toolbox.service

...and kobo-toolbox will start with the OS. You can use usual service command to start, query the status of, and stop KoBo Toolbox:

 $ sudo service kobo-toolbox start
 $ sudo service kobo-toolbox status
 $ sudo service kobo-toolbox stop

For additional information, please familiarise yourself woth Docker setup at Github

Related