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:

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.

5.6 KiB Raw Blame History