# 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.

## Endpoint Landing Pages

- [ ] Give every public S5 endpoint an intentional browser response at `/`.
- [ ] For API-only services, serve a static informational landing page at `/`
  that states the service purpose, avoids any login claim, does not expose or
  hint at runtime secrets, and links only to non-secret health/status or
  operator documentation.
- [ ] For UI-backed services, a landing page may forward users to the canonical
  login or application route, but it must also include a visible button for the
  same destination.
- [ ] Preserve existing machine-facing paths. Health probes, API prefixes,
  OAuth callbacks, and static asset routes must continue to reach their owning
  backend after the landing page is enabled.
- [ ] For API-only endpoints, route explicit API/probe paths such as `/health`
  and `/v1` to the API service, then use `/` as the landing fallback. Avoid
  competing exact `/` and prefix `/` rules for different backends.
- [ ] Add `noindex` metadata for operator and service landing pages that are
  not intended as public marketing pages.

Example UI-backed landing values:

```yaml
landing:
  enabled: true
  title: "Application sign-in"
  eyebrow: "app.example.coulomb.social"
  body: "You are being sent to the application sign-in page."
  buttonLabel: "Continue to sign-in"
  redirect:
    enabled: true
    target: "/login/"
    delaySeconds: 5
```

## 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, landing-page check when enabled, 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;
- public `/` landing-page behavior and the canonical login or API entrypoints;
- 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.