diff --git a/docs/RailianceAppDeploymentGuide.md b/docs/RailianceAppDeploymentGuide.md index e54baad..60dcf75 100644 --- a/docs/RailianceAppDeploymentGuide.md +++ b/docs/RailianceAppDeploymentGuide.md @@ -51,7 +51,8 @@ Railiance classifies repositories on four complementary axes A `rapp` is **managed packaging, not ownership**. The application repo keeps domain logic, tests, image build, and schema migrations. The rapp owns Helm/manifests, rail compatibility, smoke and rollback, secret -*references*, and reef binding. +*references*, and reef binding. The architecture term is *managed +workload package*; "service wrapper" is informal. Do not derive a rapp from a Forgejo organization or a State Hub domain. Rapp context is its own dimension (ADR-0007): @@ -124,9 +125,35 @@ Helm, probes, landing pages, and image pins. New first-class wrappers should **copy those recipes into a `rapp-*` repo**, not add another chart to `railiance-apps`. +When a rapp already exists, S5 becomes a thin delegate rather than a +second chart. `railiance-apps` `make policy-nexus-deploy` calls +`make -C ../rapp-policy-nexus deploy`. Production *approval* may still +be recorded in `railiance-apps` bindings; the package and apply path +belong to the rapp. + `railiance-platform` retains cross-workload policy, credential custody, lane approval, and the postgres credential broker. +`railiance-fabric` projects `supports_rail` / `hosts_rail` / `binds_rapp` +from family declarations. That is discovery, not a deploy engine. Do not +treat "register in Fabric" as wrapping the app. + +### 3.5 Three wrap paths (only one is the target) + +| Path | Where it lives | Use | +| --- | --- | --- | +| **A. `rapp-*` repo** | `declarations/rapp.yaml` + package Makefile | Canonical destination for a managed app or platform service. This guide. | +| **B. Overlay + `railiance/app.toml`** | `bin/railiance create-overlay` in `rail-kubernetes` | Migration-era third-party wrap. Produces `-railiance-overlay/`. Graduate it to Path A; do not start new overlays. | +| **C. S5 chart in `railiance-apps`** | `charts//` + `helm/-values.yaml` | How user-facing apps actually ship today. Stay here only for an already-extracted-or-not decision; new managed apps should leave as Path A. | + +`flex-auth` is a live Path B example (`flex-auth/railiance/app.toml`) +with no `rapp-*` repo. `vergabe-teilnahme` is a live Path C example. +`rapp-policy-nexus` is the only live A←C bridge. + +There is no `railiance register-rapp`. A rapp exists when +`declarations/rapp.yaml` is committed and +`validate-family-declarations.py` accepts it. + --- ## 4. Decide before creating a rapp @@ -150,7 +177,12 @@ Ask these in order. Stop at the first "no". 7. **What exposure?** Omit the field (private) until a grant exists. A service that fails (1) or (2) can still be operated from its ownership -repo. It is not blocked; it is just not ready to be a rapp. +repo. It is not blocked; it is just not ready to be a rapp. Keep it on +Path C (S5) or in the ownership repo until those answers are yes. + +If the workload is already an S5 chart and is not yet ready for a rapp, +do not generate an overlay (Path B) on top of it. Path B is only a +third-party compatibility wrap. --- @@ -399,9 +431,24 @@ previous-revision rollback). Only when `rail-knative` is the primary rail. ### 8.4 Overlay compatibility path `rail-kubernetes/docs/overlay-repo-pattern.md` still describes -`-railiance-overlay/` with `railiance/app.toml`. New work should -not create overlay repos. If you find one, graduate it to `rapp-` -and keep `railiance/app.toml` inside the rapp. +`-railiance-overlay/` with `railiance/app.toml`. The existing +scaffold is: + +```bash +# from rail-kubernetes; cluster/bootstrap only keep shims +bin/railiance create-overlay --app-id --upstream-url … +bin/railiance run # Stage 1 +bin/railiance deploy --stage 2 # Stage 2 canary +bin/railiance promote # Stage 3 +bin/railiance rollback +``` + +`create-overlay` writes local files only. It does not create +`declarations/rapp.yaml`, a Forgejo remote, or a family classification. +Repo Manager's later `rmgr rapp init` replaces this for first-party apps. + +New work should not create overlay repos. If you find one, graduate it +to `rapp-` and keep `railiance/app.toml` inside the rapp. --- @@ -788,7 +835,9 @@ Recorded so the scaffolder does not silently pick a side. small allow-list and refuse new names without a note. 5. **`rapp-vergabe-teilnahme` was the planned user-facing proof and was never built.** Extracting it remains a `railiance-apps` residual. Do - not pretend `rapp-user-engine` closes that ADR-0003 item. + not pretend `rapp-user-engine` closes that ADR-0003 item. Other + planned-but-unbuilt names (`rapp-forgejo`, `rapp-coulomb-social`, + `rapp-netkingdom-identity`) are not this workplan. 6. **Reef `bound_rapps` on `reef-railiance` has been stale.** Never teach the scaffolder to edit it. 7. **Metrics and Host-validated apps** need extra chart care. The @@ -832,6 +881,9 @@ Proven wrappers and operator recipes: - `railiance-apps/docs/s5-app-onboarding-checklist.md` - `railiance-apps/docs/django-on-railiance.md` - `railiance-apps/docs/operator-recipes.md` +- `railiance-apps/Makefile` (`policy-nexus-deploy` delegate) +- `rail-kubernetes/docs/create-overlay-command.md` +- `railiance-fabric/docs/rail-rapp-reef-adaptation.md` (discovery only) Worked example: