# Sites documentaires Data Asso

C-22398 fournit les sources de deux applications Docusaurus 3.10.2 : `app/documentation` pour l’exploitation et `app/developer-portal` pour les développeurs. Chaque application possède ses commandes, son index local et son image statique. L’[architecture](../decisions/0001-architecture-cible.md) reste la référence des décisions transversales. Le lot 22400 raccorde les sites au Compose local.

## Prérequis et installation

À la racine du dépôt, utiliser le NVM déjà installé :

```sh
nvm install
nvm use
node --version
corepack yarn --version
```

`.nvmrc` fixe Node 24.22.2 ; `packageManager` fixe Yarn 4.18.1. Ne pas changer l’alias NVM par défaut. `ignorePath: true` empêche un `yarnPath` personnel hérité de remplacer le Yarn épinglé par Yarn 1 ; aucun réglage personnel n’est modifié. TypeScript 5.9.3 vérifie les configurations strictes.

Le registre est `https://npm.app.synaltic.app/` dans `.npmrc` et `.yarnrc.yml`. Fournir `NPM_PROXY_AUTH` dans la session via le mécanisme habituel de gestion des secrets, sans afficher sa valeur ni l’écrire dans le dépôt ou une commande enregistrée. Le format attendu est l’authentification Basic base64 correspondant à `_auth`, pas un jeton Bearer. Yarn utilise `npmAuthIdent` limité au registre. Ce nom reprend le mécanisme existant LCA : npm/Yarn 1 lit `_auth=${NPM_PROXY_AUTH}` ; Yarn 4 reçoit la même variable via `npmAuthIdent` dans `.yarnrc.yml`. La session actuelle dispose déjà de cette variable. Aucun secret ne doit être copié depuis LCA ; un trousseau ou un fichier npm ne crée pas à lui seul une variable d’environnement.

```sh
: "${NPM_PROXY_AUTH:?Configurer cette variable dans la session via votre gestionnaire de secrets, sans afficher sa valeur}"
corepack yarn install --immutable
```

Un seul lockfile racine est attendu. Pour la création initiale de ce lockfile seulement, l’installation se fait sans `--immutable`, puis son contrôle immutable est obligatoire. Ne pas remplacer le registre par un registre public en cas d’échec. Aucune installation ne déclenche d’import de données.

## Commandes des sites

Exécuter depuis la racine :

| Usage | Exploitation | Développeurs |
| --- | --- | --- |
| Développement | `corepack yarn dev:documentation` | `corepack yarn dev:developer-portal` |
| Build statique | `corepack yarn build:documentation` | `corepack yarn build:developer-portal` |
| Prévisualisation du build | `corepack yarn workspace @data-asso/documentation serve` | `corepack yarn workspace @data-asso/developer-portal serve` |
| Sortie distribuable | `app/documentation/build/` | `app/developer-portal/build/` |

Les ports par défaut sont 3001 et 3002 ; passer `--port` pour les commandes Docusaurus si nécessaire. `start` compile les documents à la volée ; `serve` exige un build déjà produit. Le runtime cible est Docker, pas le serveur de développement.

```sh
corepack yarn typecheck
corepack yarn check:docs
```

`typecheck` vérifie l’outillage et les deux configurations. `check:docs` vérifie les métadonnées des pages sans écrire de sorties. Les builds contrôlent les liens internes et les liens Markdown comme erreurs. Les liens externes entre sites se vérifient sur les deux instances locales.

## Paramètres publics fixés au build

| Variable | Contrat | Défaut exploitation / développeurs |
| --- | --- | --- |
| `SITE_URL` | Origine HTTP(S) publique, sans chemin ni slash final | `http://localhost:3001` / `http://localhost:3002` |
| `SITE_BASE_URL` | `/` dans le contrat initial Docker | `/` |
| `OTHER_SITE_URL` | URL publique de l’autre site, utilisée dans la navigation | `http://localhost:3002/` / `http://localhost:3001/` |

Ces variables sont lues par le build Yarn. Changer une adresse exige un nouveau build du site puis une nouvelle image ; `docker run -e` ne reconfigure pas les HTML/JavaScript. Les noms de conteneurs ne sont pas des URL publiques pour les lecteurs. La publication future sous un sous-chemin nécessite une adaptation explicite ; aucune prise en charge n’est annoncée ici.

Le [parcours de livraison 22445](../work-items/22445-images-scans-versionnement.md#variantes-documentaires) exige deux origines HTTPS distinctes. Son manifeste associe chaque variante et ses valeurs de compilation au digest de son image. Un changement d’origine produit une nouvelle variante à scanner.

L’interface et les pages sont publiées en français. L’index analyse le français et l’anglais technique ; aucun contenu anglais traduit ni sélecteur de langue n’est annoncé.

## SPDD et recherche locale

Chaque page éditoriale déclare `spdd_sources`, liste non vide de chemins Markdown relatifs vers `docs/` ou `catalog/`. Les références doivent exister et rester dans leurs racines réelles. Les chemins sortants et liens symboliques hors périmètre sont refusés. `catalog/` est actuellement réservé, sans faux contrat ajouté.

Avant `start` et `build`, `scripts/documentation.ts` prépare uniquement le site demandé : page `docs/sources-spdd.md` et copies de lecture dans `static/spdd/`. Ces sorties sont ignorées par Git, recréées à partir des seules références déclarées et ne se modifient pas à la main. Leur catalogue associe pages et chemins canoniques. Les liens internes des Markdown bruts se consultent dans le dépôt ; les snapshots sont des téléchargements de sources, pas un second site SPDD.

`@easyops-cn/docusaurus-search-local` 0.55.3 construit un index par site sans service externe. Il indexe les documents, pas les snapshots statiques ; blog et indexation de pages hors docs sont désactivés. Les noms des fichiers d’index contiennent une empreinte. Pas de dépendance ou service Ask AI activé.

## Construire et exécuter les images

Après une installation et les builds séparés réussis avec les adresses publiques choisies :

```sh
docker build -t dataasso-documentation:22398 app/documentation
docker build -t dataasso-developer-portal:22398 app/developer-portal
```

Chaque Dockerfile copie uniquement le `build` de son application et sa configuration Nginx. Pas de compilation Docker supplémentaire ni de Node dans le runtime. Base exacte : `nginx:1.30.6-alpine3.24-slim` ; tag applicatif exact, non fixé par digest. Vérifier que le build correspond aux sources avant empaquetage. Les contextes `.dockerignore` fermés excluent les configurations npm et les credentials.

Vérifier les noms et ports libres, puis démarrer les deux images indépendantes :

```sh
docker run --rm -d --name dataasso-22398-documentation -p 127.0.0.1:3001:80 dataasso-documentation:22398
docker run --rm -d --name dataasso-22398-developer-portal -p 127.0.0.1:3002:80 dataasso-developer-portal:22398
```

Port interne : 80. Ces conteneurs de vérification sont limités à la boucle locale. Ils n’ont besoin ni de credential npm, ni de volume ou base, ni l’un de l’autre pour démarrer. Leurs liens réciproques exigent naturellement que les deux sites soient accessibles aux URL compilées.

Nginx sert les répertoires `index.html` des routes profondes (`trailingSlash: true`) et renvoie un vrai 404 pour une ressource absente. Pas de fallback universel vers l’accueil. HTML et snapshots sont revalidés (`no-cache`), les index JSON empreintés sont servis avec `public, max-age=31536000, immutable`. Logs sur stdout/stderr. Contrôler les en-têtes de l’index réellement produit plutôt qu’un nom supposé.

```sh
curl -fsS http://localhost:3001/ -o /dev/null
curl -fsS http://localhost:3002/demarrage/ -o /dev/null
docker logs dataasso-22398-documentation
docker stop dataasso-22398-documentation dataasso-22398-developer-portal
```

L’arrêt supprime uniquement ces conteneurs `--rm`. Aucun nettoyage global ou `prune`. Publication, registre d’images, domaines, TLS, hébergement et CI restent hors lot.

## Diagnostic et état des preuves

- Variable d’auth absente : la rendre disponible dans la session, sans la communiquer en chat. Ne pas lire ou copier un secret d’un autre projet.
- 401/403 du miroir : vérifier droits/expiration avec l’administrateur ; ne pas afficher l’authentification ou un dump de configuration.
- DNS/TLS : vérifier accès et certificat du miroir ; ne pas désactiver TLS.
- Paquet absent du miroir : contrôler sa disponibilité, sans changer silencieusement la version épinglée.
- Mauvais liens entre sites : vérifier les paramètres du dernier build, puis reconstruire et empaqueter le site concerné.
- Index absent : utiliser un build statique réussi, inspecter les fichiers produits et la réponse HTTP ; `start` ne remplace pas cette preuve.
- Port occupé : choisir un port libre, aligner les URL publiques avant build ; ne pas arrêter les conteneurs d’un autre travail.

Le [work item](../work-items/deux-sites-docusaurus.md) consigne les preuves d’exécution de C-22398 et leurs limites. Les commandes ci-dessus constituent la procédure ; leur résultat sur un environnement donné doit être vérifié dans cet environnement.

## Compose local — 22400

| Profil | Services |
| --- | --- |
| `local` | PostgreSQL |
| `docs` | Documentation et portail développeur |
| `app` | PostgreSQL et Next.js |
| `full` | PostgreSQL, Next.js et les deux sites |
| `tools` | data-jobs, conteneur ponctuel |

Sans profil, Compose ne sélectionne aucun service. Les sites restent indépendants de PostgreSQL et démarrables séparément. Pour un traitement, `docker:jobs` exige une opération et lance `run --rm`. Un `up` direct du profil `tools` affiche l’aide puis quitte.

### Préparer le worktree

Utiliser Docker avec Compose et BuildKit, Node 24.22.2 via `nvm use` et Yarn 4.18.1 via Corepack. `docker:docs` et `docker:all` demandent l’installation préalable des dépendances hôte pour les builds Docusaurus. Les Dockerfiles Next.js et data-jobs installent leurs dépendances Linux à partir du lockfile racine. Ils demandent l’accès du builder au miroir Synaltic et à la distribution de Yarn. Fournir `NPM_PROXY_AUTH` dans la session, d’où Compose l’envoie comme secret BuildKit temporaire aux seuls builds qui l’utilisent. [Next.js](nextjs.md#exécuter-le-socle-en-docker) nécessite également Google Fonts à la compilation.

```sh
nvm use
cp .env.docker.example .env.docker
# Éditer le fichier local ; ne pas afficher ni committer de secret.
corepack yarn docker:config
```

`.env.docker` est lu explicitement dans le worktree par le script Node et par Compose. Le fichier, puis les valeurs par défaut ci-dessous, priment sur le shell. Utiliser des apostrophes pour un mot de passe contenant `#` ou `$`. Les clés inconnues, les identifiants PostgreSQL invalides et les ports hors 1–65535 ou identiques sont refusés. Renseigner un mot de passe sur une seule ligne pour les commandes utilisant PostgreSQL.

| Clé | Défaut | Usage |
| --- | --- | --- |
| `POSTGRES_DB` | `dataasso` | Base technique locale |
| `POSTGRES_USER` | `dataasso` | Utilisateur local |
| `POSTGRES_PASSWORD` | vide | À renseigner localement avant la base |
| `POSTGRES_PORT` | `5432` | Port hôte PostgreSQL |
| `NEXTJS_PORT` | `3000` | Port hôte Next.js |
| `DOCUMENTATION_PORT` | `3001` | Origine publique exploitation |
| `DEVELOPER_PORTAL_PORT` | `3002` | Origine publique développeurs |

Tous les ports publiés sont liés à `127.0.0.1`. Un autre worktree peut utiliser `15432`, `13000`, `13001`, `13002`. En cas de collision, configurer des ports libres.

Le nom Compose `dataasso-<empreinte du chemin réel>` est affiché, stable pour ce chemin et passé explicitement à chaque commande. Ni override global `COMPOSE_*`, ni nom fixe de conteneur/volume/réseau ne remplace cette isolation. Les images construites et sorties de build sont propres au worktree. Déplacer le worktree change le nom de projet : noter l’ancien nom pour retrouver ses ressources avant déplacement.

### Commandes disponibles

| Commande racine via `corepack yarn` | Effet |
| --- | --- |
| `docker:db` | PostgreSQL 18.0 seul, attente du healthcheck, délai borné 90 s |
| `docker:docs` | Builds Yarn des deux sites avec leurs URL, puis images, puis démarrage ; délai de démarrage 60 s |
| `docker:docs documentation` | Même séquence pour le seul site exploitation |
| `docker:docs developer-portal` | Même séquence pour le seul portail développeur |
| `docker:app` | Build de l’image Next.js, démarrage de PostgreSQL et Next.js, attente d’une lecture WALDEC réussie |
| `docker:all` | Builds des deux sites et des trois images HTTP, puis démarrage du profil `full` |
| `docker:jobs <opération>` | Build de l’image, attente de PostgreSQL si nécessaire et exécution ponctuelle avec suppression du conteneur |
| `docker:stop` | Arrêt de tous les services du projet, conteneurs et volumes conservés |
| `docker:down` | Suppression des conteneurs/réseaux du projet, volumes conservés |
| `docker:logs [service]` | Suivi des logs, interrompre par Ctrl-C |
| `docker:status` | État incluant les conteneurs arrêtés et nom du projet |
| `docker:config` | Validation silencieuse Compose, sans valeurs résolues |

Le script vérifie les prérequis et propage le code de la commande en échec. Les commandes de gestion de la base et du cycle de vie fonctionnent avec Docker et Node. `docker:docs` et `docker:all` prennent un verrou `.docker-local.lock` pour protéger les sorties Docusaurus du worktree. Après un arrêt brutal, vérifier qu’aucun build ne les utilise avant de retirer un verrou périmé.

Les deux `SITE_URL` et `OTHER_SITE_URL` sont dérivées des ports avant les builds, avec `SITE_BASE_URL=/`. Si un build échoue, le script s’arrête avant le démarrage. Si Compose échoue pendant le démarrage, consulter `docker:status` pour identifier les services déjà lancés. Un changement de port demande un nouveau `docker:docs`. Le démarrage direct par nom de service Compose suppose un build déjà aligné aux ports.

### Base technique, persistance et reset ciblé

Le volume Compose `postgres-data` est monté sous `/var/lib/postgresql`, conformément au contrat de l’image PostgreSQL 18. Le healthcheck vérifie uniquement la disponibilité PostgreSQL.

Les wrappers hôte utilisent `localhost:<POSTGRES_PORT>`. Next.js et data-jobs en conteneur utilisent `postgres:5432` sur le réseau du projet. Pour une base neuve autorisée, appliquer les [migrations](prisma.md#déployer-et-contrôler-depuis-docker), puis [synchroniser WALDEC](waldec.md#synchroniser-dans-docker). Les démarrages ordinaires préparent uniquement les services. `docker:app` et `docker:all` renvoient un échec si Next ne peut pas lire la nomenclature publiée. Le conteneur peut déjà servir la page et son message d’indisponibilité. Voir le [diagnostic Next](nextjs.md#diagnostiquer-la-disponibilité).

`docker:stop`, `docker:down` puis `docker:db` réutilisent les données existantes. Modifier les variables POSTGRES ne transforme pas un cluster existant ; garder son mot de passe et ses identifiants ou réaliser une opération PostgreSQL explicite. Une erreur de schéma ne déclenche aucun reset.

Le reset suivant détruit **uniquement** la base du worktree choisi. Sauvegarder les données utiles avant ; aucun nettoyage global. Depuis la racine, remplacer `dataasso-…` par le nom exact affiché par `docker:status` :

```sh
project=dataasso-…
# Reprendre les mêmes valeurs que .env.docker dans cette session si elles diffèrent
# du shell ; les scripts ordinaires effectuent ce chargement automatiquement.
docker compose -f compose.yaml --env-file .env.docker --project-name "$project" stop postgres
docker compose -f compose.yaml --env-file .env.docker --project-name "$project" rm -f postgres
docker volume rm "${project}_postgres-data"
corepack yarn docker:db
```

Ces commandes ciblent explicitement le projet et le volume. Pour une commande directe Compose, retirer les variables globales `COMPOSE_*` et éviter les valeurs shell qui supplantent `.env.docker`. Les scripts racine font cette normalisation. `docker:down` conserve le volume.

Les [preuves du lot](../work-items/22400-compose-local.md) distinguent les validations exécutées des limites de l’environnement et des dépendances applicatives.
