railiance-apps/docs/s5-app-onboarding-checklist.md

S5 App Onboarding Checklist

Use this checklist when adding a new user-facing Railiance workload to railiance-apps. It turns the vergabe-teilnahme lessons into a repeatable starting point so new app releases do not have to read the historical workplans first.

Scope And Planning

• Create or update a repo-local workplan under workplans/.
• Confirm the work is S5 app release wiring, not application source code, forge runtime operation, platform service provisioning, or cluster addon work.
• Name the source application repo and the owning package/image release path.
• Record upstream dependencies on railiance-platform, railiance-forge, or railiance-enablement instead of hiding them in app values.
• Run State Hub consistency sync after task-status edits.

Release Files

• Add a Helm chart under charts/<app>/.
• Add non-secret production values under helm/<app>-values.yaml.
• Add app-specific manifests under manifests/ only when they do not fit cleanly in the chart.
• Keep image.tag pinned by git SHA or immutable version.
• Keep committed values non-secret. Runtime secrets must come from Kubernetes Secrets, approved SOPS files, or a platform secret-delivery path.
• Add Makefile targets for render, deploy, status, logs, migrations, and any app-specific secret rebuild helpers.

Image And Artifact Consumption

• Use a forge-owned image or package registry path.
• Link to source-repo publish instructions instead of duplicating build pipelines here.
• Record the source commit, image tag, package version, and evidence needed by the app runbook.
• For private images or packages, name the consuming Secret or approved secret-delivery path without storing tokenized URLs.
• Verify a cluster can pull the image before promoting the release beyond smoke-test use.

Database And Runtime Secrets

• Request app database, role, and Secret handoff through railiance-platform when using shared platform databases.
• Use an app-scoped database and role, for example <app>_db and <app>.
• Mirror only the app role credential into the app namespace.
• If the app consumes DATABASE_URL, URL-encode generated passwords before writing the env Secret.
• Prefer separate PostgreSQL env vars when a framework does not require a single DSN string.
• Document secret rotation commands without printing or committing secret values.

Ingress, TLS, And Probes

• Name the public host, namespace, Helm release, ingress, and TLS Secret in the app runbook.
• Confirm ingress class and cert-manager issuer ownership with railiance-cluster.
• Keep certificate lifecycle in cert-manager, not in app scripts.
• For framework apps with strict host validation, set HTTP probe Host headers to a value included in the app's allowed hosts.
• Keep readiness and liveness paths stable and unauthenticated.

Validation And Smoke Tests

• Run make check-tools.
• Run make <app>-dry-run or the equivalent Helm render before deploy.
• Run make k8s-server-dry-run against a representative cluster before enforcing PR checks.
• Use the persistent-pod plus kubectl exec smoke pattern from docs/operator-recipes.md.
• Capture app-level deployment evidence: dry-run result, rollout status, HTTPS or service smoke check, migration result when applicable, and rollback note.

Runbook Baseline

Each S5 app runbook should include:

• identity table with URL, namespace, release, chart, values, ingress, image, database, and TLS Secret;
• secrets and rotation section;
• day-to-day operator commands;
• image promotion steps;
• rollback behavior and migration warning;
• troubleshooting for probes, database URLs, TLS, and app-specific failure modes;
• backup and restore readiness gate;
• cross-references to source repo, platform handoff docs, forge artifact docs, and common S5 recipes.

Done Gate

A new app is ready for routine S5 operation when an operator can deploy, verify, roll back, inspect logs, rotate app-owned runtime secrets, understand upstream data durability gates, and sync the workplan without reading old app-specific history.