KoboToolbox auto-hébergé

Depuis le 28 septembre 2026, le projet héberge sa propre instance de KoboToolbox sur le serveur de préproduction, derrière le Traefik déjà en place. Motif : le plan gratuit de kobotoolbox.org plafonne les soumissions mensuelles.

Confidentialité

Ce site de documentation est public. Adresses IP, comptes, chemins des secrets et identifiants ne figurent pas ici : ils sont dans le gestionnaire de secrets de l'UCP et dans la documentation d'exploitation interne du dépôt.

Adresses

Composant	Adresse
Interface (KPI) et API v2	https://kf.kobo.ucp-pch.org
KoboCAT (soumissions, OpenRosa)	https://kc.kobo.ucp-pch.org
Enketo (formulaires web)	https://ee.kobo.ucp-pch.org

Les trois noms pointent sur le serveur de préproduction. Les certificats sont délivrés par le résolveur Let's Encrypt de Traefik.

Installation

Élément	Emplacement (compte d'exploitation du serveur)
kobo-install (release 2.026.37)	~/kobo-install
kobo-docker (tag 2.026.37)	~/kobo-docker
Configuration	~/kobo-install/.run.conf (générée par preparer_run_conf.py, sans l'assistant interactif)
Raccord Traefik	~/kobo-docker/docker-compose.frontend.custom.yml (labels, réseau traefik_network, port 80 du nginx Kobo)
Journal de démarrage	~/kobo-install/run.log
Super-utilisateur	compte d'administration initial, mot de passe remis à l'administrateur et conservé dans le gestionnaire de secrets ; à changer à la première connexion

Choix de configuration : domaine kobo.ucp-pch.org, sous-domaines kf, kc, ee ; HTTPS géré par Traefik (use_letsencrypt désactivé, proxy activé, port HTTP interne du nginx Kobo lié à l'interface locale seulement) ; e-mails par le relais SMTP de la production (voir ci-dessous) ; PostgreSQL et Mongo réservés au réseau interne.

Conteneurs : kobofe-* (nginx, kpi, enketo_express, workers) et kobobe-* (postgres, mongo, redis).

Exploitation

cd ~/kobo-install
python3 run.py            # démarrer (non interactif tant que .run.conf existe)
python3 run.py --stop     # arrêter
python3 run.py --logs     # journaux
python3 run.py --update   # mise à jour (relire ensuite le port publié dans docker-compose.frontend.override.yml)

Après une mise à jour

kobo-install régénère docker-compose.frontend.override.yml : vérifier que le port publié du nginx Kobo reste lié à 127.0.0.1, sinon le HTTP interne est exposé sur Internet. Le fichier docker-compose.frontend.custom.yml est conservé.

Les certificats sont demandés par Traefik à la première requête après un changement de configuration ; si Traefik sert encore son certificat par défaut, redémarrer le nginx Kobo (docker restart kobofe-nginx-1).

Sauvegarde : les données sont dans les volumes de ~/kobo-docker/.vols (PostgreSQL, Mongo, médias). Aucune sauvegarde automatique n'est en place à ce jour ; à mettre en œuvre si l'instance sert en production.

E-mails

Le serveur de préproduction ne joint aucun port SMTP d'OVH. KoboToolbox envoie donc ses e-mails (confirmation d'adresse, mot de passe oublié) à un relais Postfix installé sur le serveur de production (port 2525), qui ne relaie que pour le serveur de préproduction et réexpédie vers OVH avec le compte noreply@ucp-pch.org.

Élément	Valeur
Configuration Kobo	~/kobo-install/.run.conf et ~/kobo-env/envfiles/smtp.txt : hôte du relais, port 2525, sans authentification
EMAIL_USE_TLS	laisser vide : Kobo lit la valeur comme du texte, « False » vaut vrai
Relais	conteneur smtp_relay sur la production, dans ~/smtp-relay (identifiants dans .env, chmod 600)
Diagnostic	docker logs smtp_relay sur la production : status=sent ou motif du refus

Après une modification de smtp.txt, recréer les services Django de Kobo :

cd ~/kobo-docker
docker compose -f docker-compose.frontend.yml -f docker-compose.frontend.override.yml \
  -f docker-compose.frontend.custom.yml -p kobofe \
  up -d --no-deps kpi worker worker_low_priority worker_long_running_tasks worker_kobocat beat

Mot de passe du relais

Le conteneur du relais conserve un volume : s'il a démarré une fois avec un mauvais mot de passe, celui-ci reste en double et c'est lui qui sert. Pour changer le mot de passe : modifier .env, puis docker compose -f docker-compose.yml down -v et up -d dans ~/smtp-relay.

Comptes et vérification d'adresse

Kobo exige une adresse e-mail vérifiée avant la première connexion (ACCOUNT_EMAIL_VERIFICATION=mandatory). Le courriel de confirmation part par le relais. À défaut, un administrateur peut marquer l'adresse comme vérifiée dans https://kf.kobo.ucp-pch.org/admin/ : Accounts → Email addresses, cocher Verified et Primary.

Création d'un compte : Users → Add user dans la même interface d'administration. Le mot de passe du super-utilisateur est dans le gestionnaire de secrets ; ne jamais le saisir dans un ticket ou une conversation.

Brancher le SIG

Dans la configuration Kobo d'un projet du SIG, renseigner l'adresse https://kf.kobo.ucp-pch.org/api/v2 et un jeton API généré sur le nouveau serveur (compte de service). Le SIG peut lire les deux serveurs, projet par projet.

Migration depuis kobotoolbox.org

• Comptes : un compte appartient à un serveur ; recréer les utilisateurs et leurs permissions sur l'instance du projet.
• Formulaires : export XLSForm depuis kobotoolbox.org, import sur l'instance ; les identifiants de formulaire changent, mettre à jour la configuration des projets du SIG.
• Données : l'outil officiel kobo-transfer recopie les soumissions et leurs médias entre deux serveurs, en conservant l'_uuid (le SIG reconnaît une soumission par cet identifiant, donc pas de doublon à la synchronisation) mais pas la date d'arrivée ni le statut de validation. Recommandation : ne migrer que les formulaires et les collectes en cours ; l'historique reste consultable et exportable sur kobotoolbox.org, le SIG étant le système de référence.
• Liens : un lien Enketo déjà diffusé depuis kobotoolbox.org ne peut pas être redirigé. Laisser les anciens formulaires ouverts le temps de la transition, puis les archiver. Pour l'avenir, ne diffuser que des liens sur un domaine du projet qui redirigent vers le formulaire du moment.
• KoboCollect : changer l'adresse du serveur sur chaque tablette, par QR code de configuration.