docs(runbooks): runbook « mettre en service une nouvelle application web » #9

arcodange · 2026-05-31T17:23:05+02:00

arcodange commented

2026-05-31 17:23:05 +02:00

Contexte

Mettre en service une nouvelle app web sur la plateforme suppose aujourd'hui de connaître une mécanique répartie sur trois dépôts (factory, tools, dépôt de l'app) avec des dépendances d'ordre non triviales, et jamais documentée de bout en bout. Cette PR comble l'item legacy non coché [ ] setup hello world web app de doc/adr/README.md.

Contenu

Un arbre tree-docs complet en français sous doc/runbooks/new-web-app/ (10 pages) + 2 hubs (doc/README.md, doc/runbooks/README.md) :

#	Page	Sujet
—	`conventions.md`	Le nom `<app>` réutilisé à l'identique dans 16 systèmes
01	`01-gitea-repo.md`	Dépôt sous `arcodange-org` + héritage des secrets CI d'org
02	`02-database.md`	`factory/postgres/iac` → base `<app>` + rôle `<app>_role`
03	`03-vault-platform.md`	`tools/hashicorp-vault/iac` → `gitea_cicd_<app>` + policies
04	`04-helm-chart.md`	Chart Helm : connexion via `pgbouncer.tools`, secrets VSO, ingress `.lab`/`.fr`
05	`05-app-terraform.md`	`iac/` de l'app : module `app_roles`, providers, backend GCS
06	`06-ci-workflows.md`	`.gitea/workflows/` : `tofu apply` + build image
07	`07-argocd-register.md`	`factory/argocd/values.yaml` → Application ArgoCD
08	`08-checklist.md`	Checklist ordonnée + definition of done

Points clés : l'ordre des dépendances (gitea_cicd_<app> et <app>_role doivent exister avant la CI de l'app) est le fil conducteur ; la mécanique DB à deux couches (rôle propriétaire statique + users dynamiques VSO via pgbouncer) est explicitée ; chaque snippet renvoie au code source réel par URL Gitea.

Conventions tree-docs

Fils d'Ariane à chaque page, hubs README par dossier, diagrammes Mermaid (1 bout-en-bout + locaux), liens croisés bidirectionnels, encadrés [!IMPORTANT]/[!WARNING]. Câblage depuis le README.md racine et la checklist doc/adr/.

Vérifications

✅ Self-test liens relatifs tree-docs : aucun lien mort dans les nouvelles pages.
✅ 6 diagrammes Mermaid validés (valid:true). Placeholder rendu via ‹app› (le <app> HTML était avalé comme balise vide).

Observations hors périmètre (non modifiées)

doc/adr/20260509-telegram-gateway-auth.md référence 20260407-network-architecture.md, restée dans l'ancien docs/ (pluriel, non-suivi) → lien mort orphelin après la PR #8.

🤖 Generated with Claude Code

## Contexte Mettre en service une nouvelle app web sur la plateforme suppose aujourd'hui de connaître une mécanique répartie sur **trois dépôts** (`factory`, `tools`, dépôt de l'app) avec des **dépendances d'ordre non triviales**, et jamais documentée de bout en bout. Cette PR comble l'item legacy non coché `[ ] setup hello world web app` de `doc/adr/README.md`. ## Contenu Un arbre **tree-docs** complet en français sous `doc/runbooks/new-web-app/` (10 pages) + 2 hubs (`doc/README.md`, `doc/runbooks/README.md`) : | # | Page | Sujet | |---|---|---| | — | `conventions.md` | Le nom `<app>` réutilisé à l'identique dans 16 systèmes | | 01 | `01-gitea-repo.md` | Dépôt sous `arcodange-org` + héritage des secrets CI d'org | | 02 | `02-database.md` | `factory/postgres/iac` → base `<app>` + rôle `<app>_role` | | 03 | `03-vault-platform.md` | `tools/hashicorp-vault/iac` → `gitea_cicd_<app>` + policies | | 04 | `04-helm-chart.md` | Chart Helm : connexion via `pgbouncer.tools`, secrets VSO, ingress `.lab`/`.fr` | | 05 | `05-app-terraform.md` | `iac/` de l'app : module `app_roles`, providers, backend GCS | | 06 | `06-ci-workflows.md` | `.gitea/workflows/` : `tofu apply` + build image | | 07 | `07-argocd-register.md` | `factory/argocd/values.yaml` → Application ArgoCD | | 08 | `08-checklist.md` | Checklist ordonnée + definition of done | **Points clés** : l'ordre des dépendances (`gitea_cicd_<app>` et `<app>_role` doivent exister avant la CI de l'app) est le fil conducteur ; la mécanique DB à deux couches (rôle propriétaire statique + users dynamiques VSO via pgbouncer) est explicitée ; chaque snippet renvoie au code source réel par URL Gitea. ## Conventions tree-docs Fils d'Ariane à chaque page, hubs README par dossier, diagrammes Mermaid (1 bout-en-bout + locaux), liens croisés bidirectionnels, encadrés `[!IMPORTANT]`/`[!WARNING]`. Câblage depuis le `README.md` racine et la checklist `doc/adr/`. ## Vérifications - ✅ Self-test liens relatifs tree-docs : aucun lien mort dans les nouvelles pages. - ✅ 6 diagrammes Mermaid validés (`valid:true`). Placeholder rendu via `‹app›` (le `<app>` HTML était avalé comme balise vide). ## Observations hors périmètre (non modifiées) - `doc/adr/20260509-telegram-gateway-auth.md` référence `20260407-network-architecture.md`, restée dans l'ancien `docs/` (pluriel, non-suivi) → lien mort orphelin après la PR #8. 🤖 Generated with [Claude Code](https://claude.com/claude-code)

arcodange added 1 commit 2026-05-31 17:23:06 +02:00

docs(runbooks): add "new web app" setup runbook under doc/runbooks/ 8330d82225

Document, as a tree-docs tree, the end-to-end procedure to stand up a new
web application on the Arcodange platform — a mechanic spread across the
factory, tools and app repos with non-trivial ordering dependencies.

Covers: Gitea repo creation (org-secret inheritance), Postgres DB + owner
role (factory/postgres/iac), platform Vault declaration (gitea_cicd_<app>
+ policies, tools/hashicorp-vault/iac), the app Helm chart (VSO dynamic
secrets via pgbouncer), the app Terraform (app_roles module), the CI
workflows (tofu apply + image build, incl. the copy-pasted role pitfall),
and ArgoCD registration (factory/argocd/values.yaml). Adds a naming-
conventions concept page and an ordered checklist.

Wires the legacy doc/adr "setup hello world web app" item and the factory
README to the runbook. New docs live under doc/ (singular) per the PR #8
convention.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

arcodange merged commit 827af6b392 into main

2026-05-31 17:25:39 +02:00

arcodange deleted branch claude/new-web-app-runbook

2026-05-31 17:25:39 +02:00

arcodange referenced this issue from a commit

2026-05-31 17:25:41 +02:00

Merge pull request 'docs(runbooks): runbook « mettre en service une nouvelle application web »' (#9) from claude/new-web-app-runbook into main

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: arcodange-org/factory#9