# Railiance Overlay Repo Pattern

A Railiance overlay repo wraps a third-party upstream application without
forking Railiance deployment logic into the upstream source repository.

The overlay repo owns the Railiance deployment contract, promotion evidence,
Helm/Kubernetes overlay, values, probes, and runbooks. The upstream repository
remains the source of application code and release artifacts.

## Goals

- Keep upstream code and Railiance deployment mechanics separate.
- Make Stage 1, Stage 2, Stage 3, and rollback behavior reproducible from Git.
- Declare all platform dependencies, health checks, and secret references in
  `railiance/app.toml` without plaintext secret values.
- Allow third-party applications to adopt the staged promotion lifecycle without
  requiring changes to their upstream repositories.

## Repo Layout

A generated overlay repo should look like this:

```text
<app>-railiance-overlay/
  README.md
  railiance/
    app.toml
    upstream.toml
  charts/
    <app>/
      Chart.yaml
      values.yaml
      templates/
        deployment.yaml
        service.yaml
  values/
    stage1.yaml
    stage2-canary.yaml
    stage3-production.yaml
  patches/
    upstream/.gitkeep
  tests/
    stage1.sh
  runbooks/
    rollback.md
  docs/
    promotion.md
```

## Ownership Boundary

The overlay repo owns:

- `railiance/app.toml` staged promotion declaration;
- Railiance-specific Helm chart, values, probes, and runbooks;
- canary and promotion evidence expectations;
- secret references by approved route and target object name;
- compatibility notes for a specific upstream revision or release line.

The upstream repo owns:

- application source code;
- upstream build and release artifacts;
- upstream tests and release notes;
- upstream vulnerability and license notices.

The overlay must not vendor upstream source by default. If a patch is required,
store the patch under `patches/upstream/` and record why the patch exists, when
it can be retired, and which upstream issue or release should replace it.

## Required Files

### `railiance/app.toml`

This file follows `docs/app-toml-contract.md` and
`schemas/railiance-app.schema.json` from `railiance-cluster`. It is the primary
machine-readable contract for promotion tooling.

### `railiance/upstream.toml`

This file records non-secret upstream identity:

```toml
[upstream]
url = "https://example.com/vendor/app.git"
revision = "v1.2.3"
tracking = "tag"
license = "see-upstream"
notes = "Railiance overlay only; upstream code is not vendored here."
```

`revision` should be immutable where possible: tag, commit SHA, release id, or
image digest. Mutable branches are acceptable only before a workload becomes a
Stage 2 candidate.

### `charts/<app>/`

The chart is the Railiance deployment wrapper. It may start as a thin Helm
chart around an upstream image and grow only as required by the promotion gates.
Generated charts include stable/canary release identities, Prometheus-compatible
annotations, HTTP probes, resource limits, isolated canary ingress, and optional
Traefik weighted routing. Production-specific choices stay in `values/` files.

### `values/`

Stage values separate local validation, canary, and production settings:

- `stage1.yaml`: local or dry-run defaults;
- `stage2-canary.yaml`: limited exposure canary defaults;
- `stage3-production.yaml`: stable production defaults.

Secret values do not belong in these files. Use Kubernetes Secret,
ExternalSecret, OpenBao, KeyCape, or another approved route and record only the
reference name.

### `tests/stage1.sh` And `tests/stage2-template.sh`

Stage 1 should be runnable without production credentials. The generated script
performs syntax and Helm rendering checks when the relevant tools are available.

Stage 2 template validation verifies the canary scaffold, stable/canary values,
Prometheus annotations, rollback labels, and Helm rendering when Helm is
available. Workload-specific tests can extend either script.

### `runbooks/rollback.md`

Rollback instructions must exist before Stage 2. Early overlays may include a
placeholder, but it must name the intended rollback target and verification
check.

## Creation Tool

Use:

```bash
tools/create_railiance_overlay_repo.sh \
  --app-id forgejo \
  --name "Forgejo" \
  --owner railiance-forge \
  --criticality critical \
  --upstream-url https://codeberg.org/forgejo/forgejo.git \
  --upstream-revision v12.0.0 \
  --out-dir /tmp/forgejo-railiance-overlay
```

The tool writes only local files. It does not call Gitea, clone upstream code,
fetch secrets, or push Git remotes.

## Promotion Use

1. Generate or update the overlay repo.
2. Fill in accurate image, namespace, health, dependency, and rollback fields.
3. Validate `railiance/app.toml` against the schema.
4. Run `tests/stage1.sh` and `tests/stage2-template.sh`.
5. Use later T06-T07 commands to deploy, observe, promote, and rollback.

## Safety Rules

- No plaintext secrets in `railiance/app.toml`, values files, tests, runbooks,
  or generated evidence.
- Do not hide deployment logic in upstream source patches.
- Do not promote mutable upstream branches to Stage 2/3 without an explicit
  operator exception.
- Production-critical overlays require human approval before canary exposure and
  production promotion.