Skip to content

Latest commit

 

History

History
190 lines (134 loc) · 8.52 KB

readme.md

File metadata and controls

190 lines (134 loc) · 8.52 KB
Raw

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.

⚠️ You must observe the following when upgrading:

…from any release older than 2.022.44 (November 2022)

If you have already installed KoboToolbox between March 2019 and November 2022, you must complete a manual upgrade process before trying to upgrade. If you do not, kobo-install will not be able to start.

…from any release older than 2.020.18 (May 2020)

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.

…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.

Versions

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

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

Other branches are for development purposes.

Usage

$kobo-install> python3 run.py

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

Rebuild configuration:
$kobo-install> python3 run.py --setup

Get info:
$kobo-install> python3 run.py --info

Get docker logs:
$kobo-install> python3 run.py --logs

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

By default, fetch the latest version of master branch

Stop KoBoToolbox:
$kobo-install> python3 run.py --stop

Get help:
$kobo-install> python3 run.py --help

Get version:
$kobo-install> python3 run.py --version

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

Run docker commands on front-end containers:
$kobo-install> python3 run.py --compose-frontend [docker-compose arguments]

Run docker commands on back-end containers:
$kobo-install> python3 run.py --compose-backend [docker-compose arguments]

Start maintenance mode:
$kobo-install> python3 run.py --maintenance

Stop maintenance mode:
$kobo-install> python3 run.py --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

Options

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

Advanced Options

Option Default Workstation Server
Webserver port 80 ✓
Reverse proxy interal port 8080 ✓ (front end only)
Network interface Autodetected ✓ ✓ (front end only)
Use separate servers No ✓
Use DNS for private routes No ✓ (front end only)
Primary back end IP (if previous answer is no) Local IP ✓ (front end only)
PostgreSQL DB kobo ✓ ✓
PostgreSQL user's username kobo ✓ ✓
PostgreSQL user's password Autogenerate ✓ ✓
PostgreSQL number of connections3 100 ✓ ✓ (back end only)
PostgreSQL RAM3 2 ✓ ✓ (back end only)
PostgreSQL Application Profile3 Mixed ✓ ✓ (back end only)
PostgreSQL Storage3 HDD ✓ ✓ (back end 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 storage5 No ✓ ✓
Use WAL-E PostgreSQL backups6 No ✓ ✓ (back end only)
uWGI workers start: 2, max: 4 ✓ ✓ (front end only)
uWGI memory limit 128 MB ✓ ✓ (front end only)
uWGI harakiri timeout 120s ✓ ✓ (front end only)
uWGI worker reload timeout 120s ✓ ✓ (front end only)
Google UA ✓ ✓ (front end only)
Google API Key ✓ ✓ (front end only)
Raven tokens ✓ ✓ (front end only)
Debug False ✓
Developer mode False ✓
Staging mode False ✓ (front end only)

1) HTTPS certificates must be installed on a Reverse Proxy. kobo-install 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

5) If AWS storage is selected, credentials must be provided if backups are activated

6) WAL-E backups for PostgreSQL are only available when using AWS storage

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

Requirements

  • Linux 5 / macOS 6

  • Python 3.8+

  • Docker 7

  • Available TCP Ports: 8

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

    WARNING:

    • If you use a firewall, be sure to open traffic publicly on NGINX port, otherwise kobo-install 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 front-end and back-end containers only. NGINX port still has to stay publicly opened though).

5) It has been tested with Ubuntu 18.04, 20.04 and 22.04

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) Compose V1 is still supported but has reached its EOL from July 2023

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

Tests

Tests can be run with tox.
Be sure it is installed before running the tests.

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

or

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