Upcoming changes for self-hosters

If you run your own instance of KoboToolbox, you should be aware of upcoming changes that will affect you.

The repositories kobo-install and kobo-docker, which we at Kobo use ourselves and which we offer publicly for self-hosters, are being updated to better match Docker best practices and our Kubernetes environment.

Please review these notes and consider testing these changes now in a separate environment from your production service.

The main changes are:

  1. Use of only a single service within each Docker container. Instead of simply kpi and kobocat containers, which each hosted multiple services, you will now see kpi and separate containers for each Celery service: worker, worker_low_priority, worker_kobocat, and beat.
  2. Consolidation of KoboCAT, previously an entirely separate Django project, into KPI as an application called openrosa. For this reason, you will no longer see a separate kobocat container: the code that previously ran there now runs inside the kpi container.
  3. Removal of any references to a secondary database server. This was always an alpha-level feature, and it has not been receiving active support. We at Kobo do not use it any longer and are not aware of it being used anywhere else. kobo-install does still allow you to assume control of your own databases by answering “yes” during configuration to the question “Do you want to use separate servers for front end and back end?” From there, you may self-manage advanced database features like replication.
  4. Removal of support for WAL-E backups. Simple database dumps are still supported. WAL-E is obsolete, and what it provides is an advanced use case better left to independent management outside of kobo-install (see the previous point above). If you need continuous archiving, please opt out of having kobo-install configure your PostgreSQL instance, and consider using pgBackRest or WAL-G, both of which are actively supported.

Minor changes include:

  • Upgrading NGINX from 1.21 to 1.26.
  • Upgrading Redis from 6.2 to 7.2.
  • Renaming some environment variables. These are automatically set by kobo-install, but if you use kobo-docker directly or set custom environment variables, this may affect you. Refer to kobotoolbox/kpi#4948 for a complete list of these variables.

What do I have to do?

Note: these steps apply to kobo-install. If you use kobo-docker directly, we assume you have the skill needed to adapt your configuration.

  1. From your kobo-install directory, stop all services and remove Docker resources by executing ./run.py --stop.
  2. In the same directory, execute ./run.py --upgrade kobocat-as-django-app.
  3. Review the configuration as prompted.
  4. When asked “Do you want to (re)start containers?”, answer “yes”.

If you have trouble, please post in Discussion of upcoming changes for self-hosters.

Thanks for using KoboToolbox!


@stephenoduor, @ks_1 pinging the two of you as you have been actively helping the community with self-hosted KoboToolbox server issues.


Thanks @Kal_Lam and @jnm I will check it out

1 Like

Thanks @Kal_Lam!

1 Like