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

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>

doc/runbooks/new-web-app/01-gitea-repo.md

@@ -0,0 +1,88 @@
+[Factory](../../../README.md) > [Doc](../../README.md) > [Runbooks](../README.md) > [Nouvelle application web](README.md) > **1. Dépôt Gitea**
+
+# 1. Créer le dépôt Gitea
+
+> **Status:** ✅ Active
+> **Downstream:** [2. Base de données](02-database.md), [3. Vault plateforme](03-vault-platform.md)
+> **Related:** [Conventions de nommage](conventions.md) · [6. Workflows CI](06-ci-workflows.md)
+
+---
+
+## Summary
+
+Tout part d'un dépôt Gitea nommé exactement `<app>` (voir [conventions](conventions.md)). Le créer **sous l'organisation `arcodange-org`** n'est pas un détail : c'est ce qui lui fait **hériter automatiquement des secrets Actions d'organisation** dont tous les workflows dépendent. Le dépôt contient un squelette fixe que les étapes suivantes viennent remplir.
+
+## Pourquoi sous `arcodange-org`
+
+Les workflows `.gitea/workflows/*` (voir [étape 6](06-ci-workflows.md)) référencent des secrets qui ne sont **pas** définis dans le dépôt mais au niveau de l'organisation et hérités par tous ses dépôts :
+
+| Secret d'organisation | Usage |
+|---|---|
+| `HOMELAB_CA_CERT` | CA interne (base64) pour parler en TLS à `vault.arcodange.lab` |
+| `vault_oauth__sh_b64` | Script (base64) qui réalise l'échange OIDC Gitea → JWT Vault |
+| `PACKAGES_TOKEN` | Token de push vers le registre d'images `gitea.arcodange.lab` |
+
+Ces secrets sont propagés par le rôle Ansible [`gitea_secret`](https://gitea.arcodange.lab/arcodange-org/factory/src/branch/main/ansible/arcodange/factory/roles/gitea_secret/defaults/main.yml) (`gitea_owner_type: organization`).
+
+> [!IMPORTANT]
+> Un dépôt créé **hors** `arcodange-org` (par ex. sous l'org `arcodange`) n'hérite pas forcément de ces secrets. Si tu surcharges l'org (cf. `org:` à l'[étape 7](07-argocd-register.md)), assure-toi que les mêmes secrets y existent.
+
+## Options pour créer le dépôt
+
+| Méthode | Quand | Comment |
+|---|---|---|
+| UI Gitea | one-shot manuel | `https://gitea.arcodange.lab` → New Repository sous `arcodange-org` |
+| MCP Gitea | depuis un agent | outil `mcp__gitea__create_repo` (cf. règle « Gitea = MCP, pas `gh` » du guide global) |
+| Rôle Ansible `gitea_repo` | reproductible/inventaire | [`roles/gitea_repo`](https://gitea.arcodange.lab/arcodange-org/factory/src/branch/main/ansible/arcodange/factory/roles/gitea_repo/defaults/main.yml) |
+| Ressource Terraform `gitea_repository` | tout-en-IaC | dans [`factory/iac`](https://gitea.arcodange.lab/arcodange-org/factory/src/branch/main/iac) (provider `go-gitea/gitea` déjà configuré) |
+
+## Squelette minimal du dépôt
+
+```
+<app>/
+├── chart/                 # chart Helm — ArgoCD déploie CE dossier (path: chart)   → étape 4
+│   ├── Chart.yaml
+│   ├── values.yaml
+│   └── templates/
+├── iac/                   # Terraform/OpenTofu de l'app                            → étape 5
+│   ├── providers.tf
+│   ├── backend.tf
+│   └── main.tf
+├── .gitea/workflows/      # CI (tofu apply + build image)                          → étape 6
+│   ├── vault.yaml
+│   └── dockerimage.yaml   # uniquement si l'app build sa propre image
+├── Dockerfile             # uniquement si l'app build sa propre image
+├── README.md
+└── .gitignore
+```
+
+> [!IMPORTANT]
+> Le dossier du chart **doit** s'appeler `chart/` et être à la racine : le template ArgoCD impose `path: chart` (cf. [étape 7](07-argocd-register.md)). Pas de `helm/`, pas de sous-dossier.
+
+## `.gitignore` recommandé
+
+Aligné sur les dépôts existants (exclut tout secret local) :
+
+```gitignore
+.terraform
+.terraform.*
+.env
+*.key
+secrets/
+.DS_Store
+```
+
+## Le bot `tofu_module_reader`
+
+La CI de l'app clone le module Terraform partagé `tools` **en SSH** (cf. [étape 5](05-app-terraform.md)). C'est l'utilisateur restreint `tofu_module_reader` (créé dans [`factory/iac/gitea_tofu_ci_user.tf`](https://gitea.arcodange.lab/arcodange-org/factory/src/branch/main/iac/gitea_tofu_ci_user.tf), clé privée dans Vault `kvv1/gitea/tofu_module_reader`) qui sert d'identité de lecture. Rien à faire de spécial, mais le dépôt `tools` doit rester lisible par ce bot.
+
+## Notes / contraintes
+
+- Le nom du dépôt = `<app>` **exactement** (kebab-case minuscule). Voir [conventions](conventions.md) — ce nom se propage partout.
+- Pas besoin de protéger `main` autrement que par la convention worktree/PR de l'équipe ; ArgoCD suit `HEAD`.
+
+## Related
+
+- [2. Base de données](02-database.md) — provisionner la base, en parallèle de l'étape 3.
+- [3. Vault plateforme](03-vault-platform.md) — déclarer l'app côté Vault, en parallèle de l'étape 2.
+- [6. Workflows CI](06-ci-workflows.md) — consomme les secrets d'org hérités ici.