railiance-apps/docs/forgejo-on-railiance01.md

# Forgejo on railiance01

Production source forge at **`https://forgejo.coulomb.social`**.

Mirrors the coulombcore Gitea pattern (`railiance-forge`) but targets
**railiance01** using the same OAS split as other S5 apps (`inter-hub`,
`reuse-surface`).

## Layer ownership

| Layer | Repo | Concern |
| --- | --- | --- |
| S3 | `railiance-platform` | `forgejo-db` CNPG cluster + network policies |
| S5 | `railiance-apps` | Helm release, ingress, operator Makefile |
| S2 | `railiance-cluster` | Traefik, cert-manager, cnpg operator |

Hostname decision: `the-custodian/docs/forgejo-production-decisions.md`.

## Hosts

| Item | Value |
| --- | --- |
| Server | railiance01 `92.205.62.239` |
| Namespace | `forgejo` |
| Helm release | `forgejo` |
| HTTP service | `forgejo-gitea-http` (chart naming; ingress must target this) |
| Chart | `gitea-charts/gitea` **12.5.0** (Forgejo-compatible; 12.6+ needs Gitea 1.26 `config edit-ini`) |
| Image | `code.forgejo.org/forgejo/forgejo:11.0.3` |
| Database | `forgejo-db-rw.databases.svc.cluster.local:5432` |
| Kubeconfig | `~/.kube/config-hosteurope` |

## Bootstrap (first deploy)

### 1. Database credentials (platform)

```bash
cd ~/railiance-platform
# One-time: create and SOPS-encrypt helm/forgejo-db-secret.sops.yaml from template
KUBECONFIG=~/.kube/config-hosteurope make forgejo-db-deploy
KUBECONFIG=~/.kube/config-hosteurope make forgejo-db-status
```

### 2. Application secrets (apps)

```bash
cd ~/railiance-apps
# Encrypt helm/forgejo-secrets.sops.yaml from template (DB PASSWD must match platform secret)
make check-sops
```

### 3. Deploy Forgejo

```bash
cd ~/railiance-apps
make forgejo-dry-run
make forgejo-deploy
make forgejo-ingress-deploy
make forgejo-ssh-nodeport-deploy   # optional; git+ssh via nodePort 30022
# In-cluster Actions runner (ADR-004, railiance-infra/docs/adr/ADR-004-...)
# One-time: encrypt helm/forgejo-runner-registration.sops.yaml from template
make forgejo-runner-registration-deploy
make forgejo-runner-deploy
make forgejo-status
make forgejo-smoke
make forgejo-runner-status
```

## Upgrade notes

- Pin `FORGEJO_CHART_VERSION=12.5.0` — chart 12.6+ requires Gitea 1.26 `config edit-ini`.
- `strategy.type: Recreate` in `helm/forgejo-values.yaml` — avoids leveldb queue lock
  on the shared RWO PVC during rolling updates.
- Actions enabled via `gitea.config.actions.ENABLED: true`.
- Ingress backend service name is `forgejo-gitea-http` (Helm release naming).

## Day-2 operator targets

```bash
make forgejo-status
make forgejo-logs
make forgejo-smoke
make forgejo-verify          # T05 acceptance (smoke, TLS, DB, mailer, SSH operator)
make forgejo-secrets-check   # SOPS sentinels present
```

## Operator accounts (T05)

Bootstrap is automated and does not commit secrets:

```bash
# Requires admin API token at /tmp/forgejo-tegwick-api-token (or FORGEJO_ADMIN_TOKEN)
make forgejo-operator-bootstrap
```

Default operator: `tegwick` (site admin, `coulomb` Owners team, SSH via
`forgejo-remote` / `~/.ssh/id_gitea`). `forgejo_admin` remains the Helm chart
bootstrap account; day-2 git+ssh should use the operator user.

Runner registration token: if the cluster secret was created with `kubectl create
secret` (not SOPS), capture it once on a host with the age key:

```bash
make forgejo-runner-registration-sops-bootstrap
make check-sops SOPS_SENTINEL=helm/forgejo-runner-registration.sops.yaml
```

## Break-glass administrator (RAPPS-WP-0016-T01)

The floor under every sign-in change: one local site admin that works even when
NetKingdom, KeyCape or the OAuth source is broken.

| Item | Value |
| --- | --- |
| Account | `forgejo_admin` (chart bootstrap admin, local password, site admin) |
| Custody | OpenBao coulombcore `platform/workloads/forgejo/break-glass-admin`, field `PASSWORD` |
| Delivered to cluster | No. Not synced by ESO; only a human retrieves it |
| Who | The founder. Agents never read or hold the value |

The SOPS admin password in `helm/forgejo-secrets.sops.yaml` is only the chart's
initial value (`passwordMode: initialOnlyRequireReset`); Helm upgrades do not
reset the account. It is not the break-glass credential.

Seal or rotate, then verify (founder, interactive):

```bash
make forgejo-breakglass-seal     # new password -> OpenBao first, then Forgejo
make forgejo-breakglass-verify   # one local sign-in; writes docs/evidence/<date>-forgejo-breakglass-signin.json
```

Recovery when normal sign-in is broken:

1. `bao kv get -field=PASSWORD platform/workloads/forgejo/break-glass-admin`
   (operator token on `https://bao.coulomb.social`).
2. Sign in at `https://forgejo.coulomb.social/user/login` as `forgejo_admin`
   with local credentials. Local password sign-in stays enabled for this account
   even if RAPPS-WP-0016-T04 restricts it for everyone else.
3. Repair the authentication source or users from Site Administration.
4. If the password itself is lost: with cluster access, run
   `make forgejo-breakglass-seal` again (it sets the password through the
   Forgejo CLI in the pod, so it needs no working sign-in).
5. Afterwards rotate (`make forgejo-breakglass-seal`), verify, and record the use.

Where it is logged: OpenBao audit log (retrieval), Forgejo log and the account's
last-login time (sign-in), the evidence file in `docs/evidence/`, and a State Hub
progress event naming why break-glass was used.

## SMTP (IONOS) — password reset / notifications

Decision: `the-custodian/docs/forgejo-production-decisions.md` (IONOS, 2026-07-07).

Operator provisions a mailbox on `coulomb.social` in the IONOS control panel
(e.g. `forgejo@coulomb.social`). Subdomains use the same IONOS SMTP relay; the
`FROM` address must be a valid mailbox on the zone.

Non-secret Helm values belong in `helm/forgejo-values.yaml` under
`gitea.config.mailer` once ready to enable:

```yaml
gitea:
  config:
    mailer:
      ENABLED: true
      FROM: forgejo@coulomb.social
      PROTOCOL: smtp+starttls
      SMTP_ADDR: smtp.ionos.de    # EU IONOS mailboxes; use smtp.ionos.com for US
      SMTP_PORT: 587
      USER: forgejo@coulomb.social
```

Mailbox password is stored in **OpenBao** and delivered by External Secrets:

| Item | Value |
| --- | --- |
| OpenBao path | `platform/workloads/forgejo/forgejo-mailer` |
| Field | `PASSWD` (synced to Secret key `MAILER_PASSWD`) |
| ExternalSecret | `manifests/forgejo-mailer-externalsecret.yaml` |
| Helm consumption | `gitea.additionalConfigFromEnvs` → `GITEA__mailer__PASSWD` |

**OpenBao note:** `https://bao.coulomb.social` is coulombcore (live, unsealed).
The in-cluster `openbao.openbao.svc` pod on railiance01 is a separate instance
that is **not initialized** yet — ESO uses the coulombcore endpoint interim
until Wave 7 migrates OpenBao custody to railiance01.

Bootstrap (railiance01):

```bash
cd ~/railiance-apps
KUBECONFIG=~/.kube/config-hosteurope make forgejo-openbao-eso-token-apply
KUBECONFIG=~/.kube/config-hosteurope make forgejo-mailer-es-deploy
KUBECONFIG=~/.kube/config-hosteurope make forgejo-mailer-es-status   # expect SecretSynced
KUBECONFIG=~/.kube/config-hosteurope make forgejo-deploy
```

Do not put the SMTP password in `helm/forgejo-secrets.sops.yaml`.

## Coexistence with Gitea

Gitea on coulombcore remains canonical until `RAIL-HO-WP-0005` migration drills
and cutover pass. Do not repoint repo remotes until Wave 1 cutover is approved.

## Package registry (OCI, npm, generic)

See `docs/forgejo-package-registry.md`. Smoke targets:

```bash
make forgejo-smoke
make forgejo-npm-smoke
```

## Related

- Gitea reference: `~/railiance-forge/Makefile` (`gitea-deploy`)
- Drain plan: `the-custodian/docs/coulombcore-drain-placement-plan.md` Wave 1
- Onboarding checklist: `docs/s5-app-onboarding-checklist.md`