136 lines
5.6 KiB
Markdown
136 lines
5.6 KiB
Markdown
# 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.
|