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

## 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
      MAILER_TYPE: smtp
      HOST: smtp.ionos.com:587   # or smtp.ionos.de:587 for EU accounts
      IS_TLS_ENABLED: true
      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 | `MAILER_PASSWD` |
| ExternalSecret | `manifests/forgejo-mailer-externalsecret.yaml` |
| Helm consumption | `gitea.additionalConfigFromEnvs` → `GITEA__mailer__PASSWD` |

Bootstrap (railiance01):

```bash
cd ~/railiance-platform
KUBECONFIG=~/.kube/config-hosteurope make openbao-configure-external-secrets-forgejo

cd ~/railiance-apps
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.

## 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`