---
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 `/`.