Déploiement du hub d'exploration fédérée (#636)¶
Le hub est un back API seul, sans interface. Il agrège l'index des instances CICADA et sert la recherche transverse. Il se déploie sur son propre serveur, indépendamment des instances : il doit pouvoir tomber sans les entraîner, et inversement.
- Architecture et contrat d'échange : hub/README.md
- Banc d'essai local (2 instances + hub) : MULTI_INSTANCE_LOCAL.md
- Place du hub parmi les autres serveurs (dépôt APT, API de suivi, bases) : Infrastructure
- Ce déploiement rejoué en VM, instance comprise : packaging/vm-bench (scénarios
federationeta-z)
Pourquoi le hub sort du même dépôt que CICADA¶
Le hub vit dans le dépôt CICADA tant que le contrat d'échange n'est pas figé —
un seul commit fait alors évoluer les deux côtés. Trois choses le retiennent
aujourd'hui : filters.py existe en deux exemplaires dont la parité est
vérifiée par un test qui pilote les deux projets à la fois ; les sérialiseurs de
fiche évoluent de pair ; les référentiels nationaux sont les mêmes fichiers.
Un dépôt commun n'empêche pas un déploiement séparé : chaque image a son
contexte de build, sa release produit trois images (cicada-backend,
cicada-frontend, cicada-hub) portant le même tag, et chaque serveur ne tire
que la sienne. Le numéro de version partagé est même un avantage tant que le
contrat bouge : « quelle version du hub parle à quelle version d'instance » ne
se pose pas.
Ce que le serveur du hub doit avoir¶
| Docker + Docker Compose v2 | le hub et sa base tournent en conteneurs |
Apache avec mod_proxy, mod_proxy_http, mod_headers, mod_ssl |
seul point d'entrée public |
| Un certificat TLS pour le nom public | le dépôt transporte des jetons |
| ~5 Go de disque | image (1,7 Go, GDAL) + index |
Il n'a pas besoin de PostgreSQL installé nativement, ni de Redis, ni de Celery, ni de CICADA à côté : l'image embarque le code et les référentiels nationaux.
Installation¶
1. Récupérer les fichiers de déploiement¶
L'image est tirée depuis GHCR, mais le compose a besoin de deux fichiers du
dépôt (docker-compose.hub.prod.yml et hub/docker/postgres/init.sql, qui crée
les schémas à la première initialisation de la base).
sudo git clone --depth 1 --branch v0.1.X https://github.com/RNF-SI/Cicada.git /opt/cicada-hub
cd /opt/cicada-hub
2. Configurer¶
sudo cp .env.hub.prod.example .env.hub.prod
sudo chmod 600 .env.hub.prod
sudo nano .env.hub.prod # SECRET_KEY, ALLOWED_HOSTS, mots de passe, jetons
sudo mkdir -p /var/log/cicada-hub
ALLOWED_HOSTS : le nom public du hub. localhost et 127.0.0.1 sont
toujours admis en plus, car le healthcheck du conteneur et la vérification
ci-dessous passent par eux. Avec une image ≤ 0.1.49, ajoutez-les vous-même
(ALLOWED_HOSTS=hub.cicada.example.org,localhost,127.0.0.1), sinon le hub répond
400 à ces contrôles et reste « unhealthy ».
Le démarrage échoue explicitement si SECRET_KEY, ALLOWED_HOSTS ou
POSTGRES_PASSWORD manquent — c'est voulu : un hub qui démarre avec la clé de
développement serait pire qu'un hub qui ne démarre pas. Les jetons, eux, ne sont
pas des variables d'environnement : les instances s'enrôlent après coup avec
enroler_instance (voir plus bas).
3. Démarrer¶
sudo docker compose -f docker-compose.hub.prod.yml --env-file .env.hub.prod up -d
sudo docker compose -f docker-compose.hub.prod.yml --env-file .env.hub.prod logs -f hub
Au premier démarrage, l'entrypoint applique les migrations puis importe les deux
référentiels (ref_geo, nomenclatures). Les imports suivants sont ignorés si
les données sont déjà là : redémarrer un hub qui tourne depuis des mois ne coûte
pas un réimport.
Vérification :
curl -s http://127.0.0.1:8002/api/health/
# {"statut": "ok", "service": "cicada-hub", "instance": "hub"}
Variante : base sur un serveur PostgreSQL existant¶
Par défaut la base du hub tourne en conteneur à côté de lui. Là où les bases sont regroupées sur un serveur dédié (cas de la production RNF : le hub sur un conteneur, sa base sur le serveur de bases partagé), on la crée avec le même outil que pour une instance, puis on écarte le conteneur de base.
Sur le serveur de bases, en root — cicada-prepare-db crée le compte, la
base, PostGIS, joue init.sql et n'ouvre pg_hba.conf qu'à l'adresse du hub :
# Le serveur de bases n'a souvent pas d'accès Internet : copier les deux
# fichiers depuis le clone du hub (/opt/cicada-hub), en passant par son poste
# si le serveur de bases n'accepte pas de SSH depuis le réseau du hub.
# packaging/debian/usr/bin/cicada-prepare-db → prepare-db
# hub/docker/postgres/init.sql → hub-init.sql
mv hub-init.sql /tmp/ # PAS dans /root : le script le joue en tant que postgres
PW=$(head -c 24 /dev/urandom | base64 | tr -d '/+=' | cut -c1-24)
bash prepare-db --db-name cicada_hub --db-user cicada_hub_user --password "$PW" \
--init-sql /tmp/hub-init.sql --client <IP-du-hub>
echo "$PW" # → coffre de mots de passe, puis POSTGRES_PASSWORD du hub
--password plutôt que le mot de passe généré : si le script échoue après
avoir créé le compte, une relance sans --password garde un mot de passe que
personne n'a vu.
Sur le hub — docker-compose.hub.extdb.yml désactive le service db et la
dépendance du hub envers lui :
cd /opt/cicada-hub
# Seulement si une base locale a déjà été créée et ne contient rien à garder :
sudo docker compose -f docker-compose.hub.prod.yml --env-file .env.hub.prod down -v
# Dans .env.hub.prod : POSTGRES_HOST=<IP-serveur-bases>, POSTGRES_PORT=5432,
# POSTGRES_DB / POSTGRES_USER / POSTGRES_PASSWORD = ceux passés à prepare-db
alias hub='cd /opt/cicada-hub && sudo docker compose -f docker-compose.hub.prod.yml -f docker-compose.hub.extdb.yml --env-file .env.hub.prod'
hub config --services # « hub » seul — si « db » apparaît, l'overlay manque
hub up -d && hub logs -f hub # « Attente de PostgreSQL (<IP>:5432) », migrations, imports
⚠️ Toujours passer par les deux -f (l'alias ci-dessus, à mettre dans le
.bashrc de root) : une commande sans docker-compose.hub.extdb.yml recrée un
conteneur de base vide, et le hub repart sans registre ni index. La sauvegarde
de la base relève alors du serveur de bases ; le registre des instances (les
empreintes des jetons) n'existe que là.
Apache¶
<VirtualHost *:443>
ServerName hub.cicada.example.org
SSLEngine on
SSLCertificateFile /etc/letsencrypt/live/hub.cicada.example.org/fullchain.pem
SSLCertificateKeyFile /etc/letsencrypt/live/hub.cicada.example.org/privkey.pem
ProxyPreserveHost On
RequestHeader set X-Forwarded-Proto "https"
ProxyPass / http://127.0.0.1:8002/
ProxyPassReverse / http://127.0.0.1:8002/
# Le dépôt d'un lot envoie des pages de plans avec leur fiche JSON
# complète : ni la taille ni la durée par défaut ne suffisent.
LimitRequestBody 104857600
ProxyTimeout 300
ErrorLog ${APACHE_LOG_DIR}/cicada-hub-error.log
CustomLog ${APACHE_LOG_DIR}/cicada-hub-access.log combined
</VirtualHost>
Quatre pièges :
- Ne pas réécrire
/api. Le hub sert tout sous/api/et il n'y a aucun frontend à servir à côté. UnProxyPass /api/ …mal aligné produit des 404 qui ressemblent à un hub vide. - Ne pas filtrer les en-têtes custom. L'authentification passe par
X-Federation-Token(dépôt) etX-Hub-Token(lecture). Apache les transmet par défaut ; un WAF ou unRequestHeader unsettrop large les coupe, et l'erreur ressemble à une révocation de jeton. ALLOWED_HOSTSdoit contenir leServerName. AvecProxyPreserveHost On, Django voit le nom public : s'il n'est pas déclaré, tout répond 400.- Taille du corps. Django refuse par défaut tout corps > 2,5 Mo, y compris
en JSON. Le réglage
DATA_UPLOAD_MAX_MEMORY_SIZEet leLimitRequestBodyd'Apache doivent rester cohérents. La soupape côté instance estpush_federation --page-size N.
Variante : derrière un reverse proxy qui porte le HTTPS¶
Cas de la production RNF : un proxy frontal (Apache + certbot + ModSecurity) porte le TLS de tous les services et relaie en HTTP vers chaque conteneur.
- Sur le hub, un vhost
:80seulement : le bloc ci-dessus sans les lignesSSL*, en<VirtualHost *:80>. - Sur le proxy, un vhost
:80qui redirige vers HTTPS, le certificat (certbot certonly --apache -d <nom>), puis un vhost:443qui relaie vershttp://<IP-du-hub>/avecProxyPreserveHost On,RequestHeader set X-Forwarded-Proto "https", les mêmesLimitRequestBodyetProxyTimeout, etSecRuleEngine Off: le hub n'est qu'une API à jeton, et le jeu de règles CRS bloquerait le texte libre des plans et plafonnerait les corps vers 13 Mo. - DNS interne. Les instances hébergées sur le même réseau joignent le hub
par son nom public. Si le pare-feu ne fait pas de NAT reflection, ce nom
(son IP publique) est injoignable de l'intérieur :
curlrépondCould not connect … after 0 msalors que le hub répond depuis l'extérieur. Faire résoudre le nom vers l'IP interne du proxy par le résolveur du réseau (pfSense : Services › DNS Resolver › Host Overrides) plutôt que par un/etc/hosts: les conteneurs de l'instance ne lisent pas celui de l'hôte. Vérifier depuis le conteneur qui publiera :sudo docker exec cicada_prod_web python -c "import urllib.request as u; print(u.urlopen('https://<nom>/api/health/').read())".
Enrôler une instance¶
Une instance a besoin de deux jetons, distincts parce que lire n'est pas écrire et que révoquer l'un ne doit pas emporter l'autre. Ils se délivrent depuis le hub, sans redémarrage :
sudo docker compose -f docker-compose.hub.prod.yml --env-file .env.hub.prod \
exec hub python manage.py enroler_instance rnf \
--libelle "Réserves Naturelles de France" \
--url https://cicada.rnf.example.org
La commande affiche les deux jetons une seule fois : le hub n'en conserve que l'empreinte. Les reperdre n'est pas grave — un renouvellement coûte une commande et une ligne à changer côté instance — mais aller les relire en base est impossible, et c'est voulu.
enroler_instance rnf --renouveler depot # l'ancien cesse aussitôt d'être accepté
enroler_instance rnf --desactiver # refuse les jetons, n'efface rien
enroler_instance rnf --reactiver
enroler_instance --lister # le registre, et qui publie sans être enrôlé
Adhésion validée par RNF (enrôlement par l'API de suivi, #696)¶
Le chemin ordinaire n'est plus enroler_instance mais l'adhésion : la
structure la demande depuis son instance (Administration > Paramètres), un
administrateur RNF l'accepte dans l'admin de l'API de suivi (la vérification de
l'identité de la structure sera définie plus tard, #697), et le suivi enrôle l'instance sur le hub
par POST /api/federation/enrolements/. L'instance a tiré ses jetons elle-même ;
seules leurs empreintes voyagent, aucun jeton n'est à remettre.
Cela suppose un jeton d'administration partagé entre le hub et l'API de suivi :
à reporter dans HUB_ADMIN_TOKEN du .env.hub.prod et du .env de l'API de
suivi, puis redémarrer le hub. Vide (défaut), l'endpoint répond 403 à tout
appel : l'adhésion est alors impossible et seul enroler_instance enrôle.
Un identifiant déjà enrôlé avec d'autres jetons est refusé (409) sans rien
modifier : c'est à trancher sur le hub avec enroler_instance.
Désactiver ne dépublie pas : l'index déjà déposé reste servi. Le retrait des
données est une décision de l'instance, qui la prend avec
retrait_federation --confirmer ou en décochant le partage — la confondre avec une suspension d'accès
ferait disparaître des plans à la première suspicion.
Les variables
HUB_FEDERATION_TOKENS/HUB_READ_TOKENSrestent acceptées en amorce, pour accueillir la première instance avant qu'un registre n'existe. Mais elles ne valent que pour une instance absente du registre : dès qu'une instance y figure, un jeton d'environnement portant son nom est refusé. Sinon un jeton révoqué en base resterait admis par une variable oubliée dans un fichier de déploiement.
Côté instance, dans son .env de production (/var/lib/cicada/.env pour une
installation par paquet Debian) :
CICADA_INSTANCE_ID=rnf
CICADA_INSTANCE_LABEL=Réserves Naturelles de France
CICADA_PUBLIC_URL=https://cicada.rnf.example.org
CICADA_HUB_URL=https://hub.cicada.example.org
CICADA_HUB_PUSH_TOKEN=<jeton de dépôt>
CICADA_HUB_READ_TOKEN=<jeton de lecture>
CICADA_EXPLORATION_SOURCE=hub
CICADA_HUB_PUSH_AUTO=true
⚠️
CICADA_INSTANCE_IDest immuable. Il s'écrit dans chaque ligne d'index et entre dans toutes les clés d'unicité. Le changer périme tout l'index publié sous l'ancienne valeur : il faut alorsrebuild_search_index --purgecôté instance puis republier. Le choisir court et lisible (rnf,cen-aura) : il apparaît dans la référence d'un plan (rnf:camargue). L'identifiant donné àenroler_instanceet celui de l'instance doivent être le même.
À l'installation par paquet Debian, l'installeur web propose une section
« Exploration fédérée » qui écrit ces lignes. Elle est facultative et refuse
un identifiant mal formé — c'est le seul moment où l'erreur se corrige sans
conséquence. L'URL du hub y est pré-remplie : il n'y a qu'un hub, hébergé
par RNF, dont l'adresse est gravée dans le paquet à sa construction
(HUB_URL de /etc/cicada/cicada.conf, injectée par build-deb.sh, comme
l'URL de l'API de suivi). On ne la change dans le formulaire que pour raccorder
un hub de test. Après l'installation, ces valeurs ne se modifient encore que
dans le .env (#695).
Suivre l'état de la fédération¶
curl -s -H "X-Hub-Token: <jeton-lecture>" \
https://hub.cicada.example.org/api/federation/instances/
Rend, par instance : enrôlée ou non, active ou suspendue, date de la dernière
publication réussie, nombre de plans et de documents publiés. Aucun jeton ni
empreinte n'y figure. Une instance qui publie encore avec un jeton
d'environnement y apparaît avec enrolee: false — c'est la liste de ce qu'il
reste à enrôler.
Publier depuis une instance¶
Rien ne part tant qu'un super administrateur n'a pas activé le partage dans
/administration/parametres. Le réglage est faux par défaut, y compris après
une montée de version : publier le contenu de ses plans est un engagement de la
structure, pas un effet de bord d'une mise à jour.
Une fois le partage activé, la publication est automatique chaque nuit
(tâche Celery apps.search.tasks.publier_vers_le_hub), à une heure propre à
chaque instance entre 1h00 et 5h00, dérivée de CICADA_INSTANCE_ID (#701) :
toutes les instances à la même heure satureraient le hub. Elle ne fait rien
tant que les trois conditions ne sont pas réunies — hub et jeton configurés,
CICADA_HUB_PUSH_AUTO vrai, partage consenti — ce qui permet de la laisser
planifiée sur toutes les instances, fédérées ou non.
Un dépôt porte l'état complet et non un différentiel : une nuit sautée ne perd rien, la suivante repart de l'état courant.
Régulation et relance (#701)¶
- Côté hub : au-delà de
HUB_LOTS_CONCURRENTS_MAXlots ouverts en même temps (défaut 3), l'ouverture d'un lot répond 429 avecRetry-After(HUB_RETRY_AFTER_SECONDES, défaut 600). Un lot ouvert depuis plus deHUB_LOT_DUREE_MAX_MINUTES(défaut 180 — dépôt interrompu, jamais basculé) est considéré comme expiré et ne compte plus.GET /api/federation/instances/marqueen_retardune instance sans publication réussie depuisHUB_RETARD_PUBLICATION_HEURES(défaut 48). - Côté instance : sur un 429, une erreur 5xx ou un hub injoignable, la tâche
de nuit abandonne son lot éventuel puis se relance (jusqu'à 6 fois, après
le délai demandé par le hub, sinon 5 min, 10 min… plafonné à 1 h). Chaque
tentative est consignée dans l'historique des publications (origine
« relance »). Un refus définitif (jeton invalide, charge rejetée) n'est pas
relancé. Le diagnostic de
/administration/parametressignale une publication en retard au-delà de 48 h sans succès.
À la main :
docker exec cicada_prod_web python manage.py push_federation --dry-run
docker exec cicada_prod_web python manage.py push_federation
En cas d'échec, la commande abandonne le lot plutôt que de le basculer : entre « incomplet » et « périmé », c'est périmé qui est récupérable. La publication précédente reste en place, complète.
Retrait volontaire, commande distincte de la publication pour que
l'accidentel ne ressemble pas au voulu (push_federation refuse par ailleurs un
index vide, qui dépublierait tout) :
Décocher le partage dans l'interface (Administration > Paramètres) fait le
même retrait, immédiatement : les plans de l'instance quittent le hub, et le
hub refuse dès lors son jeton de lecture (il ne sert que les instances qui
publient). Si le hub est injoignable à ce moment-là, la case reste décochée et
le retrait est relancé chaque heure (tâche relancer_retrait_hub) jusqu'au
succès ; la page des paramètres l'affiche en « retrait en attente ». Recocher
republie en arrière-plan, sans attendre la nuit. La commande, elle, ne modifie
pas la case : si le partage reste coché, la publication suivante republiera.
Monter de version¶
Avec une base externe, remplacer chaque docker compose -f docker-compose.hub.prod.yml --env-file .env.hub.prod
par l'alias hub (les deux -f).
cd /opt/cicada-hub
sudo git fetch --tags && sudo git checkout v0.1.Y
sudo sed -i 's/^CICADA_VERSION=.*/CICADA_VERSION=0.1.Y/' .env.hub.prod
sudo docker compose -f docker-compose.hub.prod.yml --env-file .env.hub.prod pull
sudo docker compose -f docker-compose.hub.prod.yml --env-file .env.hub.prod up -d
Les migrations s'appliquent au démarrage. L'index n'est pas reconstruit : si une migration change la forme des documents, les instances doivent republier.
Recette après déploiement¶
# 1. Le hub répond, à travers Apache
curl -s https://hub.cicada.example.org/api/health/
# 2. Une instance publie
docker exec cicada_prod_web python manage.py push_federation
# 3. Le hub sert ce qu'elle a publié
curl -s -H "X-Hub-Token: <jeton-lecture>" \
"https://hub.cicada.example.org/api/exploration/plans/?q=<un-nom-de-plan>"
# 4. La fiche d'un plan, désignée par instance:slug
curl -s -H "X-Hub-Token: <jeton-lecture>" \
"https://hub.cicada.example.org/api/exploration/plans/rnf:<slug>/"
# 5. L'instance relaie bien (CICADA_EXPLORATION_SOURCE=hub) : la page
# /exploration annonce une portée nationale et renvoie des plans des
# autres instances. Un 502 ici est explicite et voulu — pas de repli
# silencieux sur l'index local.
Ce que cette recette vérifie et que rien d'autre ne voit : la couture Apache.
En-têtes X-Federation-Token / X-Hub-Token transmis, ALLOWED_HOSTS aligné
sur le ServerName, taille et durée des dépôts.
Le banc d'essai reste local. tests/federation/bench.py pilote les briques
par docker exec sur des noms de conteneurs figés (cicada_web,
cicada_hub_api) : les variables BENCH_*_API ne déplacent que la partie HTTP.
Il ne peut donc pas viser un hub déployé sur un autre hôte. C'est lui qui couvre
le contrat et la parité des 14 requêtes entre les deux filters.py — à
lancer avant de tagger, pas après avoir déployé :
scripts/federation.sh test # suites unitaires (hub + CICADA)
scripts/federation.sh test --bench # contrat, scénarios, parité (3 stacks locaux)
Le test qui manque encore, et qu'aucun des deux niveaux ne donne : un
push_federation à volume réel. C'est là que LimitRequestBody,
ProxyTimeout et DATA_UPLOAD_MAX_MEMORY_SIZE se révèlent — un banc à quelques
plans de test ne les atteindra jamais. À faire sur le staging, avec une base
restaurée depuis une instance réelle.
Ne pas lancer le compose de production sur un poste de développement¶
docker-compose.hub.prod.yml porte le même name: et les mêmes noms de
conteneurs et de volume que le compose de développement : le lancer sur une
machine où tourne le banc d'essai remplace le hub de dev et réutilise sa
base. Le nom de projet figé reste indispensable (sans lui, Compose le déduit du
dossier — « cicada » — et le service db détruit le conteneur de la base de
l'instance principale), mais il fait de ces deux fichiers deux façons de piloter
le même stack, pas deux stacks.