arcodange-org/factory

Files

Gabriel Radureau 8330d82225 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>

2026-05-31 17:22:30 +02:00

3.9 KiB

Raw Blame History

Factory > Doc > Runbooks > Nouvelle application web > 8. Checklist

8. Checklist & Definition of Done

Status: ✅ Active Upstream: 7. Enregistrement ArgoCD Related: README du runbook · Conventions de nommage

Summary

Récapitulatif imprimable de toute la procédure, dans l'ordre des dépendances. À cocher au fur et à mesure ; chaque ligne renvoie à sa page détaillée.

Ordre des dépendances

[01] Dépôt Gitea ──┬──> [02] base + <app>_role ──┐
                   └──> [03] gitea_cicd_<app> ────┤ (02 et 03 avant 05)
                                                  ▼
                          [04+05+06] chart/ + iac/ + .gitea/ ── push → CI
                                                  ▼
                                    [07] ArgoCD ── déploie ── Runtime

Checklist

Préparation

Nom <app> choisi (kebab-case minuscule), cohérent partout — conventions

1 · Dépôt — détails

Dépôt arcodange-org/<app> créé (hérite HOMELAB_CA_CERT, vault_oauth__sh_b64, PACKAGES_TOKEN)
Squelette en place : chart/, iac/, .gitea/workflows/, .gitignore (+ Dockerfile si image maison)

2 · Base de données — détails

"<app>" ajouté à factory/postgres/iac/terraform.tfvars
CI factory « Postgres » verte → base <app> + rôle <app>_role créés

3 · Vault plateforme — détails

{ name = "<app>" } ajouté à tools/hashicorp-vault/iac/terraform.tfvars
CI tools « Vault » verte → gitea_cicd_<app>, policies <app> / <app>-ops créées

Important

Ne pas pousser le iac/ de l'app (étape 5/6) tant que 2 et 3 ne sont pas appliquées : la CI Terraform de l'app en dépend.

4 · Chart Helm — détails

Chart.yaml (name: <app>), values.yaml (image, ingress, serviceAccount.create: true)
config.yaml pointe pgbouncer.tools / base <app>
vaultauth.yaml (role <app>), vaultdynamicsecret.yaml (creds/<app>), vaultsecret.yaml (kvv2/<app>/config)
Ingress choisi : interne .lab (websecure + letsencrypt + localIp@file) ou public .fr (web + crowdsec + nodeSelector pi1)

5 · Terraform de l'app — détails

providers.tf : role gitea_cicd_<app>
backend.tf : prefix <app>/main
main.tf : module "app_roles" (name = "<app>") + secrets kvv2/<app>/config

6 · Workflows CI — détails

vault.yaml : role: gitea_cicd_<app> aligné (pas un reliquat copié-collé) ⚠️
dockerimage.yaml + Dockerfile (si image maison) → push gitea.arcodange.lab/arcodange-org/<app>
Push → CI « vault » verte (creds/<app> + rôle K8s <app> + KV créés), CI « image » verte

7 · ArgoCD — détails

<app> ajouté sous gitea_applications dans factory/argocd/values.yaml (+ annotations image-updater si voulu)
Commit sur main → Application <app> apparaît dans ArgoCD

Definition of Done

Application ArgoCD <app> = Synced + Healthy
Pod Running dans le namespace <app> (SA <app>)
Secret K8s vso-db-credentials présent et roté par VSO (TTL ~1 h) ; le pod redémarre à la rotation
L'app répond sur son ingress (<app>.arcodange.lab ou <app>.arcodange.fr)
Connexion DB OK via pgbouncer.tools avec un user dynamique héritant de <app>_role

README du runbook — vue d'ensemble + carte de bout en bout.
Conventions de nommage — la cohérence du nom <app>, source de la plupart des ratés.