Aller au contenu

Infrastructure CICADA : qui parle à qui

Vue d'ensemble des serveurs autour d'une instance CICADA et des liens entre eux : ce qu'il faut ouvrir, configurer et vérifier pour que l'installation, le suivi, les mises à jour et l'exploration fédérée fonctionnent.

Cette infrastructure est reproduite à l'identique en local par le banc de test (packaging/vm-bench/, scénario a-z et labo.sh) : toute modification d'un lien décrit ici doit y être rejouée avant d'aller en production.

Schéma

flowchart LR
    subgraph GitHub
        CI[CI au tag vX.Y.Z]
        GHCR[(GHCR<br/>images Docker)]
        CI -->|images backend, frontend, hub| GHCR
    end

    subgraph ServeurSuivi[Serveur de suivi]
        APT[(Dépôt APT<br/>reprepro signé GPG)]
        SUIVI[API de suivi<br/>tracking-api]
    end

    subgraph ServeurHub[Serveur du hub]
        HUB[Hub d'exploration<br/>API seule]
    end

    subgraph ServeurBases[Serveur de bases]
        PG[(PostgreSQL + PostGIS)]
    end

    subgraph Instance[Serveur d'une instance CICADA]
        APP[Application<br/>conteneurs Docker]
        SYS[Paquet cicada<br/>heartbeat, updater, installateur]
    end

    CI -.->|.deb, publié à la main| APT
    SYS -->|① apt install / mise à jour| APT
    APP -->|② docker pull| GHCR
    APP -->|③ SQL 5432| PG
    SYS -->|④ enregistrement, heartbeat 03:00| SUIVI
    APP -->|⑤ publication 02:30, recherche| HUB
    HUB -->|docker pull| GHCR
    PG -.->|⑥ script de préparation, une fois| SYS

Toutes les flèches partent de l'instance. Aucun serveur central n'a besoin de joindre une instance : elle peut être derrière un pare-feu sans adresse publique. Seule exception, ponctuelle : le serveur de bases récupère son script de préparation auprès de l'installateur (⑥), le temps de l'installation.

Les liens, un par un

# De → vers Port Quand Configuré par Si le lien est coupé
① Instance → dépôt APT (apt.cicada.reserves-naturelles.org) 443 installation, mise à jour source APT et clé publique fournies par le paquet ; à la première installation, par install.sh (guide, étape 1) ni installation ni mise à jour par apt ; le bouton « Mettre à jour » échoue. Repli : dpkg -i du .deb
② Instance → GHCR (ghcr.io) 443 installation, mise à jour rien (images publiques) les conteneurs ne peuvent pas être téléchargés
③ Instance → serveur de bases 5432 en permanence formulaire d'installation ; côté base : cicada-prepare-db --client <ip> (une ligne pg_hba.conf) l'application ne démarre pas
④ Instance → API de suivi (tracking.cicada.reserves-naturelles.org/api) 443 à l'installation, puis chaque nuit vers 03:00 URL gravée dans le paquet à sa construction (/etc/cicada/cicada.conf) ; jeton dans /etc/cicada/instance_token l'instance fonctionne, mais n'apparaît plus dans le suivi et n'est plus prévenue des mises à jour
⑤ Instance → hub 443 publication chaque nuit à 02:30 ; recherche à chaque exploration si le relais est actif section « Exploration fédérée » du formulaire (CICADA_HUB_* dans /var/lib/cicada/.env) + case « partage » dans Administration → Paramètres rien n'est publié ; avec le relais actif, l'exploration répond 502
⑥ Serveur de bases → installateur de l'instance 4567 une fois, à l'installation commande affichée par le formulaire copier le script à la main (guide, étape 3)
— Navigateur de l'opérateur → installateur 4567 à l'installation — pas de formulaire (tunnel SSH possible)
— Navigateurs → Apache de l'instance → frontend 443 → 8080 en permanence vhost : tout vers 127.0.0.1:8080, jamais /api vers 8000 (#231) application inaccessible

À la première installation, le serveur a aussi besoin de download.docker.com (dépôt Docker).

Le cycle d'une release

sequenceDiagram
    participant Dev as Développeur
    participant GH as GitHub (CI + GHCR)
    participant TC as Serveur de suivi
    participant I as Instance

    Dev->>GH: tag vX.Y.Z
    GH->>GH: images Docker (backend, frontend, hub) + paquet .deb
    Dev->>TC: publish.sh cicada_X.Y.Z_amd64.deb (dépôt APT)
    Dev->>TC: LATEST_VERSION=X.Y.Z (.env de l'API de suivi) + redémarrage
    I->>TC: heartbeat (chaque nuit, 03:00)
    TC-->>I: « mise à jour X.Y.Z disponible »
    Note over I: le super-admin voit le bouton « Mettre à jour »
    I->>TC: apt install cicada=X.Y.Z
    I->>GH: docker pull des images X.Y.Z
    I->>TC: heartbeat suivant : version X.Y.Z

Les trois gestes manuels d'une release : le tag, la publication du .deb dans le dépôt, LATEST_VERSION sur l'API de suivi. Oublier le deuxième fait échouer le bouton « Mettre à jour » ; oublier le troisième fait que personne n'est prévenu. Détail : Releases et mises à jour.

Où est quoi

Serveur Rôle Fichiers et commandes clés Documentation
Serveur de suivi dépôt APT /var/www/repos/cicada ; packaging/apt-repo/init-repo.sh (une fois), publish.sh (à chaque release) Releases et mises à jour §4
API de suivi /opt/tracking-api (sur le serveur de production : /home/tracking/Cicada/tracking-api), son .env (LATEST_VERSION), service cicada-tracking-api, admin sur /admin/ tracking-api/INSTALLATION.md
Hub recherche transverse /opt/cicada-hub, .env.hub.prod, enroler_instance <id> (délivre les 2 jetons) Hub d'exploration fédérée
Serveur de bases PostgreSQL + PostGIS cicada-prepare-db --client <ip-instance> Installation étape 3
Instance l'application /var/lib/cicada/.env (configuration, root seul), /etc/cicada/ (jeton, URL de suivi), /var/log/cicada/ (heartbeat.log, updater.log), /var/lib/cicada/updates/ (échange avec le bouton « Mettre à jour ») Installation

Vérifier que tout est relié

Sur une instance :

systemctl is-active cicada-heartbeat.timer cicada-updater.path   # active, active
sudo systemctl start cicada-heartbeat && tail -2 /var/log/cicada/heartbeat.log   # ④ « Heartbeat envoyé »
apt-cache policy cicada                                          # ① le dépôt propose une version
sudo docker exec cicada_prod_web python manage.py push_federation --dry-run   # ⑤ plans publiables
curl -sI https://<domaine>/api/health/ | grep -i x-correlation-id # vhost : l'API est bien celle de CICADA

Sur le serveur de suivi : l'instance apparaît dans /admin/ avec sa version et un heartbeat de la nuit ; reprepro -b /var/www/repos/cicada list stable donne la dernière version.

Sur le hub : GET /api/federation/instances/ (jeton de lecture) liste l'instance, sa dernière publication et son nombre de plans.

Tester avant de toucher à la production

cd packaging/vm-bench
./bench.sh run a-z      # les 4 serveurs en VM, tous les liens ci-dessus, bilan OK/KO (~25 min)
./labo.sh demarrer      # la même infrastructure, laissée allumée pour jouer une release

Voir packaging/vm-bench/README.md.

Documents liés

Pour… Lire
installer ou mettre à jour une instance Installation
publier une version (tag, dépôt APT, API de suivi) Releases et mises à jour, RELEASE_PIPELINE.md
déployer le hub, enrôler une instance Hub d'exploration fédérée, hub/README.md
installer l'API de suivi tracking-api/INSTALLATION.md
construire le paquet Debian packaging/README.md
rejouer tout cela en local packaging/vm-bench/README.md ; exploration fédérée entre instances de développement : MULTI_INSTANCE_LOCAL.md
l'ensemble de la documentation README.md (index)