New-app checklist

The playbook in one screen. Fill in <app>, <owner>, hosts. Each box links to the step with the full template.

App: Reset

Ticks are saved in your browser per app name.

1. Decide

• Pick <app>, namespaces <app>-staging / <app>-prod, and the staging + prod hostnames
• Database? Postgres (CNPG, section 3) or SQLite on a volume (Invoicer: one pod, Recreate, no canary). Browser login (Keycloak client)? Note which steps apply
• New server? That is Provision, not this list

2. Build & ship the image: details

• Multi-stage Dockerfile (distroless/static, arm64, USER 65532:65532; bundle migrate if needed)
• .dockerignore
• CI → ghcr.io/<owner>/<app>:sha-<sha>
• Package public, or plan an imagePullSecret

3. Database (if needed): details

• CNPG Cluster (<app>-pg) in workloads/<app>/base/
• App reads DB_URL / JDBC from the auto-created <app>-pg-app Secret
• Migrations if the app needs a Job (Penvoice applies schema on startup, example only)
• backup.barmanObjectStore + ScheduledBackup; overlay-patch the S3 prefix per env

4. Deploy & reconcile: details

• Copy workloads/<example>/{base,overlays} and rename
• Two list entries in apps/workloads.yaml (staging + prod)
• DNS A records → node public IP

5. Secrets: details

• Infisical GUI: Project <app>, environments staging and prod; type values there
• Machine Identity per env; infisical-<app>-identity Secret in each namespace
• Overlay projectId + environmentSlug; Rollout envFrom the synced Secret
• <app>-pg-backup-creds via kubectl. Never in Git

6. Email (if the app sends mail): details

• Notices alias oci-<app> on the oci mailbox
• OCI compartment email-<app> (inside email); approved sender <app>@mail.visarend.systems in it
• OCI user SMTP <App> (email oci-<app>@…), group email-<app>, line added to policy email-apps-send
• SMTP credentials → Infisical SMTP_HOST, SMTP_PORT, SMTP_USERNAME, SMTP_PASSWORD, MAIL_FROM (staging + prod)
• Cloud Shell test prints SENT; the received mail shows SPF, DKIM and DMARC pass
• Row added to Reference § Email

7. Canary: details

• Prod overlay: timed 25→50→75. Do not add ServiceMonitor / AnalysisTemplate until a metrics stack exists

8. Go live

• Push this repo → Argo syncs
• First app push goes to staging; move main only by fast-forward once that image is built
• App Synced / Healthy; cert READY=True
• curl https://<host>/healthz returns 200

9. Day-2

• Staging: bump images.newTag in the staging overlay. Prod: Promote the same digest
• Optional: a worked-example page for this app

---

Stuck? Troubleshooting. New node? Provision.