---
title: Architecture et processus
description: Les services de l'instance (web, worker, release, PostgreSQL, Redis), les profils optionnels, les réseaux et le rôle du worker.
---

# Architecture et processus

Cette page présente les pièces d'une instance 101Maintain et leur rôle. Elle s'adresse à l'exploitant, la personne ou l'équipe qui déploie et fait fonctionner l'instance.

**Qui peut le faire :** l'exploitant, avec un accès à l'hôte Docker ou à la ressource Coolify.

## Vue d'ensemble

L'instance est décrite par un seul fichier Docker Compose, `compose.mvp.yaml`, à la racine du dépôt. Ce fichier fait foi pour le déploiement. Une seule image applicative sert à plusieurs services.

```text
                 Internet (HTTPS)
                        |
                 Proxy Coolify
                        |
                      web  ─────────────┐
                        |               |
 réseau « default » : sorties GitHub, Langdock, SMTP (web et worker)
                        |               |
                     worker ────────────┤
                                        |
 réseau « data » (interne, sans sortie) : postgres, redis
```

## Services permanents

| Service | Rôle | Particularités |
| --- | --- | --- |
| `web` | Serveur de l'application (interface, API, webhooks). | Seul service routé par le proxy, port interne 3333. Rôle PostgreSQL **runtime**. |
| `worker` | Traitements d'arrière-plan. | Même image, processus séparé, sonde de battement, arrêt drainé. Rôle **runtime**. |
| `release` | Étape ponctuelle à chaque déploiement : migrations, puis vérification des droits du rôle runtime. | Rôle PostgreSQL de **migration**. Reste *Exited (0)* après succès : c'est normal. |
| `postgres` | Base de données PostgreSQL 18, source de vérité. | Volume `postgres-data`, aucun port publié. |
| `redis` | Transport des travaux. | Volume `redis-data`, persistance AOF, mot de passe obligatoire, aucun port publié. |

Le web et le worker ne démarrent qu'après la réussite de `release` et quand Redis est sain.

## Services optionnels (profils)

Ces services ne démarrent que si leur profil Compose est activé.

| Profil | Services | Usage |
| --- | --- | --- |
| `scanner` | `scanner`, `zap`, `scanner-egress` | Contrôles dynamiques d'une recette. Voir [GitHub App et interrupteurs](06-github-app-et-fonctionnalites.md). |
| `benchmark` | `benchmark` | Banc d'essai des modèles, processus séparé. |
| `import` | `legacy-import` | Import ponctuel d'anciennes données. Voir la [page de migration des données](11-migrer-depuis-le-poc.md). |
| `maintenance` | `retention` | Export puis purge du journal. Voir [Rétention du journal et rôles PostgreSQL](10-retention-et-roles-postgresql.md). |

## Réseaux et durcissement

| Réseau | Membres | Propriété |
| --- | --- | --- |
| `default` | web, worker, benchmark | Routage du web, sorties vers GitHub, Langdock et la messagerie. |
| `data` | postgres, redis, release, web, worker | Interne : pas de route sortante, pas d'exposition au proxy. |
| `scanner-control` | worker, scanner | Interne : seul le worker parle au scanner. |

Tous les services tournent en lecture seule, sans capacité Linux et avec `no-new-privileges`. Les seuls emplacements inscriptibles sont les volumes et des répertoires temporaires en mémoire. L'image applicative tourne avec un compte non administrateur (UID 1000). Les journaux Docker sont limités à 5 fichiers de 10 Mo par conteneur.

## Volumes

| Volume | Contenu | Sauvegardé |
| --- | --- | --- |
| `postgres-data` | Base de données | Oui |
| `platform-storage` | Stockage privé partagé par le web et le worker : file de secours du journal, remise de l'invitation du premier administrateur | Oui |
| `redis-data` | File de transport | Non, voir ci-dessous |

## Le worker

Le worker est le processus d'arrière-plan qui exécute tout ce qui ne répond pas directement à une requête :

- envoi des e-mails (codes de sécurité, invitations, liens) ;
- exécutions de maintenance et appels au modèle ;
- notifications avant publication et publication GitHub ;
- suivi des PR brouillons ;
- audits de dépôt et contrôles dynamiques ;
- génération des rapports PDF ;
- distribution des travaux durables ;
- surveillance de l'instance et alertes.

### Battement et sonde

Le worker écrit un battement toutes les 5 secondes. Sa sonde de santé, `node apps/platform/build/bin/worker.js --health`, échoue si le battement a plus de 30 secondes. Le worker n'a pas de serveur HTTP.

### Arrêt drainé

À l'arrêt, le worker reçoit `SIGTERM`. Il cesse de prendre de nouveaux travaux et termine ceux en cours, avec 30 secondes par travail. Le délai de grâce Compose est de 120 secondes. Un arrêt propre se termine par la ligne `worker_drained` et le code 0. Un code 137 signale un arrêt forcé : délai dépassé.

### Redis n'est pas la source de vérité

Redis ne transporte que des identifiants. Toutes les décisions et tous les états sont dans PostgreSQL. Si Redis perd ses messages, le worker reconstruit les livraisons depuis PostgreSQL au passage suivant. Les travaux déjà terminés ne sont pas rejoués. C'est pourquoi Redis n'est pas sauvegardé.

La livraison est garantie « au moins une fois ». Un effet externe dont le résultat est incertain passe à l'état inconnu et n'est jamais relancé automatiquement.

## Limites connues

- Une seule instance de chaque service est prise en charge. Augmenter le nombre de workers demande de revoir le pool de connexions PostgreSQL.
- Aucune sonde externe indépendante n'est fournie. Si l'hôte ou le worker s'arrête, l'application ne peut pas le signaler elle-même. Voir [Santé, métriques et alertes](07-sante-metriques-et-alertes.md).

## Pour continuer

Préparez la configuration avec [Variables d'environnement](02-variables-d-environnement.md).
