Skip to content
Go to file


Failed to load latest commit information.
Latest commit message
Commit time

The purpose of the script is to install KoBoToolbox in minutes without messing with configuration files.
It prompts the user to answer some questions to create configuration files automatically and to start docker containers based on kobo-docker.

Important notice when upgrading from any release older than 2.020.18

Prior to release 2.020.18(, KPI and KoBoCAT both shared a common Postgres database. They now each have their own. If you are upgrading an existing single-database installation, you must follow these instructions to migrate the KPI tables to a new database and adjust your configuration appropriately.

If you do not want to upgrade at this time, please use the shared-database-obsolete branch instead.

Warning for kobo-docker installations made prior to March 2019

If you have already installed KoBoToolbox with kobo-docker prior March 2019, you must complete a manual upgrade process before using this repository. If you do not, kobo-install will not be able to start.


Branch stable is the recommended branch to use kobo-install on your production environment.
Just run git checkout stable before your first run.

Branch master is a pre-release of next stable version. It contains new features and bug fixes.

Other branches are for development purposes.


$kobo-install> python3

First time the command is executed, setup will be launched.
Subsequent executions will launch docker containers directly.

Rebuild configuration:
$kobo-install> python3 --setup

Get info:
$kobo-install> python3 --info

Get docker logs:
$kobo-install> python3 --logs

Update KoBoToolbox:
$kobo-install> python3 --update [branch or tag]

By default, fetch latest version of stable branch

Stop KoBoToolbox:
$kobo-install> python3 --stop

Get help:
$kobo-install> python3 --help

Get version:
$kobo-install> python3 --version

Build kpi and kobocat (dev mode):
$kobo-install> python3 --build

Run docker commands on frontend containers:
$kobo-install> python --compose-frontend [docker-compose arguments]

Run docker commands on backend containers:
$kobo-install> python --compose-backend [docker-compose arguments]

Start maintenance mode:
$kobo-install> python --maintenance

Stop maintenance mode:
$kobo-install> python --stop-maintenance

Build the configuration

User can choose between 2 types of installations:

  • Workstation: KoBoToolbox doesn't need to be accessible from anywhere except the computer where it's installed. No DNS needed
  • Server: KoBoToolbox needs to be accessible from the local network or from the Internet. DNS are needed


Option Default Workstation Server
Installation directory ../kobo-docker
SMTP information ✓ (frontend only)
Public domain name kobo.local ✓ (frontend only)
Subdomain names kf, kc, ee ✓ (frontend only)
Use HTTPS1 False (Workstation)
True (Server)
✓ (frontend only)
Super user's username super_admin ✓ (frontend only)
Super user's password Random string ✓ (frontend only)
Activate backups2 False ✓ (backend only)

Advanced Options

Option Default Workstation Server
Webserver port 80
Reverse proxy interal port 8080 ✓ (frontend only)
Network interface Autodetected ✓ (frontend only)
Use separate servers No
Use DNS for private routes No ✓ (frontend only)
Primary backend IP (if previous answer is no) Local IP ✓ (frontend only)
PostgreSQL DB kobo
PostgreSQL user's username kobo
PostgreSQL user's password Autogenerate
PostgreSQL number of connections3 100 ✓ (backend only)
PostgreSQL RAM3 2 ✓ (backend only)
PostgreSQL Application Profile3 Mixed ✓ (backend only)
PostgreSQL Storage3 HDD ✓ (backend only)
MongoDB super user's username root
MongoDB super user's password Autogenerate
MongoDB user's username kobo
MongoDB user's password Autogenerate
Redis password4 Autogenerate
Use AWS storage No ✓ (frontend only)
uWGI workers start: 2, max: 4 ✓ (frontend only)
uWGI memory limit 128 MB ✓ (frontend only)
uWGI harakiri timeout 120s ✓ (frontend only)
uWGI worker reload timeout 120s ✓ (frontend only)
Google UA ✓ (frontend only)
Google API Key ✓ (frontend only)
Raven tokens ✓ (frontend only)
Debug False
Developer mode False
Staging mode False ✓ (frontend only)

1) HTTPS certificates must be installed on a Reverse Proxy. KoBoInstall can install one and use Let's Encrypt to generate certificates thanks to nginx-certbot project

2) If AWS credentials are provided, backups are sent to configured bucket

3) Custom settings are provided by PostgreSQL Configuration Tool API

4) Redis password is optional but strongly recommended

Intercom App ID must now be configured through "Per user settings" in the Django admin interface of KPI.


  • Linux 5 / macOS 6

  • Python 2.7/3.5+ Python2 support will be dropped in a future release

  • Docker & Docker Compose

  • Available TCP Ports: 7

    1. 80 NGINX
    2. 443 NGINX (if you use KoBoInstall with LetsEncrypt proxy)
    3. Additional ports when expose ports advanced option has been selected
      1. 5432 PostgreSQL
      2. 6379-6380 redis
      3. 27017 MongoDB


    • If you use a firewall, be sure to open traffic publicly on NGINX port, otherwise KoBoInstall cannot work
    • By default, additional ports are not exposed except when using multi servers configuration. If you choose to expose them, be sure to not expose them publicly (e.g. use a firewall and allow traffic between frontend and backend containers only. NGINX port still has to stay publicly opened though).

5) It has been tested with Ubuntu 14.04, 16.04 and 18.04, CentOS 8

6) Docker on macOS is slow. First boot usually takes a while to be ready. You may have to answer Yes once or twice to question Wait for another 600 seconds? when prompted

7) These are defaults but can be customized with advanced options


Tests can be run with tox.
Be sure it's install before running the tests

$kobo-install> sudo apt install python3-pip
$kobo-install> pip3 install tox
$kobo-install> tox


$kobo-install> sudo apt install tox
$kobo-install> tox


A command-line installer for setting up and running KoBoToolbox on a remote server or local computer, using kobo-docker.



No packages published
You can’t perform that action at this time.