170 lines
6.0 KiB
Markdown
170 lines
6.0 KiB
Markdown
---
|
|
id: RAILIANCE-WP-0008
|
|
type: workplan
|
|
title: "Add friendly landing pages for S5 service endpoints"
|
|
domain: railiance
|
|
repo: railiance-apps
|
|
status: finished
|
|
owner: codex
|
|
topic_slug: railiance
|
|
created: "2026-06-15"
|
|
updated: "2026-06-15"
|
|
state_hub_workstream_id: "41b9deea-a935-4372-8916-b3981336f597"
|
|
---
|
|
|
|
# Add friendly landing pages for S5 service endpoints
|
|
|
|
Create a small, reusable landing-page pattern for public S5 application
|
|
endpoints. The page should give humans a clear next step without changing the
|
|
machine-facing API contract:
|
|
|
|
- UI-backed applications may show a friendly page with a short redirect notice
|
|
and a visible **Continue** button to the correct login or application route.
|
|
- API-only services should show a proper no-login informational page at `/`,
|
|
with links to health/status/runbook documentation where appropriate.
|
|
|
|
First rollout target: **`https://reuse.coulomb.social`**, which hosts the
|
|
`reuse-surface` federation API and intentionally has no browser login UI.
|
|
|
|
## Current Context
|
|
|
|
`RAILIANCE-WP-0007` deployed the `reuse-surface` Helm release and runbook for
|
|
`reuse.coulomb.social`. The release is useful to machines and operators, but a
|
|
human visiting `/` should not be left with an API-shaped response or a dead end.
|
|
|
|
The implementation must preserve the existing CLI/API surface:
|
|
|
|
- `/health` remains suitable for Kubernetes probes and external smoke checks.
|
|
- `/v1/*` API routes continue to reach the `reuse-surface` service.
|
|
- Authenticated federation operations continue to use `REUSE_SURFACE_TOKEN` and
|
|
must not expose token material in the landing page, chart values, or logs.
|
|
|
|
## Design Constraints
|
|
|
|
- Keep the page static and non-secret.
|
|
- Prefer explicit Ingress path routing over changing API semantics when a
|
|
service has no upstream web UI.
|
|
- Use exact `/` routing for the landing page when possible, so API prefixes are
|
|
unaffected.
|
|
- Add `noindex` metadata for operator/service landing pages that are not meant
|
|
to be public marketing surfaces.
|
|
- Keep the pattern reusable for later services with login destinations.
|
|
|
|
---
|
|
|
|
## Define Landing Page Contract
|
|
|
|
```task
|
|
id: RAILIANCE-WP-0008-T01
|
|
status: done
|
|
priority: high
|
|
state_hub_task_id: "ca47efdb-ed0e-47bf-90f3-5a78c6861ebf"
|
|
```
|
|
|
|
Document the endpoint contract in `docs/s5-app-onboarding-checklist.md` or a
|
|
small companion doc:
|
|
|
|
- API-only service: static informational page at `/`, no login claim, no token
|
|
hints, links to health/status and operator runbook.
|
|
- UI-backed service: landing page may auto-forward after a short delay and must
|
|
include a visible button to the canonical login/application route.
|
|
- All variants must preserve health, API, OAuth callback, and asset paths.
|
|
|
|
Done when future S5 app workplans can cite a single landing-page rule instead
|
|
of rediscovering the behavior per service.
|
|
|
|
## Add Reusable Helm Support
|
|
|
|
```task
|
|
id: RAILIANCE-WP-0008-T02
|
|
status: done
|
|
priority: high
|
|
state_hub_task_id: "44dfe49f-a3f4-4381-a4ca-eb9218099868"
|
|
```
|
|
|
|
Add a reusable Helm pattern for a static landing page, either as shared snippets
|
|
or as chart-local templates following one documented convention. The pattern
|
|
should support:
|
|
|
|
- enable/disable flag in values;
|
|
- static HTML content from a ConfigMap;
|
|
- a lightweight static HTTP container or equivalent service;
|
|
- exact `/` Ingress path to the landing service;
|
|
- prefix routes for API and app paths to the existing backend;
|
|
- optional redirect target and button label for UI-backed applications.
|
|
|
|
Done when `helm template` can render both disabled and enabled landing-page
|
|
variants without changing non-landing deployments.
|
|
|
|
## Implement API-Only Landing Page For reuse.coulomb.social
|
|
|
|
```task
|
|
id: RAILIANCE-WP-0008-T03
|
|
status: done
|
|
priority: high
|
|
state_hub_task_id: "4e90315d-f0f0-49ca-b44f-533c23a44e96"
|
|
```
|
|
|
|
Enable the landing-page pattern in `charts/reuse-surface` and
|
|
`helm/reuse-surface-values.yaml` for `reuse.coulomb.social`.
|
|
|
|
Content should make clear that this endpoint is the Railiance REUSE capability
|
|
federation service, not a login application. Include non-secret operator links
|
|
or text for:
|
|
|
|
- service purpose;
|
|
- `/health`;
|
|
- `/v1/federated`;
|
|
- `docs/reuse-surface-on-railiance01.md`;
|
|
- noindex metadata.
|
|
|
|
Done when a browser request to `/` receives the landing page while `/health`
|
|
and `/v1/federated` still reach the API service.
|
|
|
|
## Add Login-Forward Variant For UI Applications
|
|
|
|
```task
|
|
id: RAILIANCE-WP-0008-T04
|
|
status: done
|
|
priority: medium
|
|
state_hub_task_id: "80c843b2-68d0-4f8a-aba6-39db1a2a6f70"
|
|
```
|
|
|
|
Prepare the values contract and at least one documented example for services
|
|
that do have a browser UI. The page should explain that the user is being sent
|
|
to the application and include a visible button to the configured login or
|
|
application route.
|
|
|
|
Done when a future UI-backed app can set only values such as `redirectTarget`,
|
|
`buttonLabel`, and explanatory copy, without editing templates.
|
|
|
|
## Verify, Deploy, And Update Runbook
|
|
|
|
```task
|
|
id: RAILIANCE-WP-0008-T05
|
|
status: done
|
|
priority: medium
|
|
state_hub_task_id: "0fc250a8-8fea-4c88-bd81-ad7ecf6143a1"
|
|
```
|
|
|
|
Render, deploy, and smoke-test the reuse landing page on railiance01:
|
|
|
|
- `make reuse-dry-run`;
|
|
- deploy with pinned image and non-secret landing values;
|
|
- verify `/`, `/health`, and `/v1/federated` over the public hostname;
|
|
- confirm no secret values appear in manifests or rendered HTML;
|
|
- update `docs/reuse-surface-on-railiance01.md` with the landing-page behavior
|
|
and rollback notes.
|
|
|
|
Done when the public browser experience is friendly and the existing
|
|
machine-facing API checks still pass.
|
|
|
|
Completed 2026-06-15: deployed Helm revision 5 to namespace `reuse`.
|
|
`reuse-surface-landing` is Running, HTTP `/` redirects to HTTPS, HTTPS `/`
|
|
returns `200 text/html`, `/health` returns `200 application/json`,
|
|
`/v1/federated` returns `200 application/json` with 12 capabilities, and the
|
|
fetched landing page contains no token references. Follow-up fix separated the
|
|
API and landing Service selectors with `app.kubernetes.io/component` labels and
|
|
changed ingress routing to explicit API paths (`/health`, `/v1`) plus landing
|
|
fallback `/`.
|