infra/cloud/README.md

# cloud

The single central hub. One deployment, internet-facing.

## What runs here

nginx-proxy, wireguard-server, keycloak, oauth2-proxy, portainer, influxdb, grafana, node-red, rabbitmq, postfix, gitea, jenkins, mlflow, jupyterhub, frost, sql.

See [`../docs/architecture.md`](../docs/architecture.md) for the full network topology and ingress table.

Every human-accessible UI is gated by **Keycloak SSO** (wbd realm). Apps with native OIDC (gitea, grafana, node-red, jenkins, jupyterhub) speak OIDC directly; apps without (mlflow, portainer, rabbitmq) are gated by an `oauth2-proxy` sidecar via nginx `auth_request`. See the [`Keycloak bootstrap`](#keycloak-realm-bootstrap-one-time) section below.

## Run

```bash
cp .env.example .env     # fill in real secrets first
./deploy.sh              # one-shot bring-up: containers + cert + smoke test
```

`deploy.sh` is idempotent — rerun any time. It will:

1. **Preflight** — check `.env` has all required vars
2. **Validate** `docker compose config`
3. **Bring up** containers, wait for `sql` healthcheck, wait for nginx :80
4. **Inspect cert** — figure out whether the current cert is self-signed, staging, or prod
5. **Issue / renew** the SAN cert via certbot only when needed (initial issuance, or when `ACME_CA_URI` no longer matches the current issuer); reload nginx
6. **Status** — show `docker compose ps`
7. **Smoke test** every `*.wbd-rd.nl` vhost over loopback

The script reissues the cert **only** when the CA in `.env` changes (e.g. staging → prod) or when only the bootstrap dummy is present — it does not waste Let's Encrypt rate limits on repeated runs.

### Staging → prod flip

1. Verify everything works with the staging cert (browser will warn — that's normal)
2. Edit `.env`: change `ACME_CA_URI` to `https://acme-v02.api.letsencrypt.org/directory`
3. `./deploy.sh` — script detects the CA change and force-renews against prod

## Ingress (host port bindings)

| Port | Container |
|---|---|
| tcp/80, 443 | nginx-proxy |
| tcp/8883 | nginx-proxy (MQTT-TLS via stream block) |
| udp/51820 | wireguard-server |

Everything else stays on the internal `app` / `data` / `mgmt` networks.

## Keycloak realm bootstrap (one-time)

After `deploy.sh` succeeds, Keycloak is up at `https://auth.wbd-rd.nl/` with only the master realm. You need to create the `wbd` realm + per-app OIDC clients before SSO works. Driven entirely by `kcadm.sh` inside the keycloak container, so it's reproducible:

```bash
cd cloud
set -a && . ./.env && set +a

KC="docker compose exec -T keycloak /opt/keycloak/bin/kcadm.sh"

# 1. Authenticate against master realm
$KC config credentials --server http://localhost:8080 --realm master \
  --user "$KEYCLOAK_ADMIN" --password "$KEYCLOAK_ADMIN_PASSWORD"

# 2. Create the realm
$KC create realms -r master \
  -s realm=wbd -s enabled=true -s displayName="WBD R&D" \
  -s registrationAllowed=false -s resetPasswordAllowed=true -s rememberMe=true

# 3. Create an OIDC client per app. Pattern:
#       clientId    = stable lowercase name (matches *_OAUTH_CLIENT_ID in .env)
#       redirectUri = the app's documented OIDC callback URL
#    Hardcoded audience mapper is critical for oauth2-proxy clients — without
#    it the access token's aud will be [realm-management, account] and
#    oauth2-proxy will 500 on the callback.

create_client() {
  local CID=$1 REDIRECT=$2 SECRET=$3
  local ID=$($KC create clients -r wbd \
    -s clientId=$CID -s enabled=true -s protocol=openid-connect \
    -s publicClient=false -s standardFlowEnabled=true \
    -s "redirectUris=[\"$REDIRECT\"]" \
    -s "attributes.\"post.logout.redirect.uris\"=\"https://${REDIRECT#https://*/}*\"" \
    ${SECRET:+-s secret="$SECRET"} -i)
  $KC create clients/$ID/protocol-mappers/models -r wbd \
    -s name=audience-self -s protocol=openid-connect \
    -s protocolMapper=oidc-audience-mapper \
    -s "config.\"included.client.audience\"=$CID" \
    -s "config.\"access.token.claim\"=true" -s "config.\"id.token.claim\"=false"
  echo "$CID -> $ID"
}

create_client gitea         "https://git.wbd-rd.nl/user/oauth2/keycloak/callback" "$GITEA_OAUTH_CLIENT_SECRET"
create_client grafana       "https://dash.wbd-rd.nl/login/generic_oauth"          "$GRAFANA_OAUTH_CLIENT_SECRET"
create_client node-red      "https://flow.wbd-rd.nl/auth/strategy/callback/"      "$NODERED_OAUTH_CLIENT_SECRET"
create_client jenkins       "https://ci.wbd-rd.nl/securityRealm/finishLogin"      "$JENKINS_OAUTH_CLIENT_SECRET"
create_client jupyterhub    "https://hub.wbd-rd.nl/hub/oauth_callback"            "$JUPYTERHUB_OAUTH_CLIENT_SECRET"
create_client mlflow        "https://ml.wbd-rd.nl/oauth2/callback"                "$MLFLOW_OAUTH_CLIENT_SECRET"
create_client portainer-ce  "https://ops.wbd-rd.nl/oauth2/callback"               "$PORTAINER_OAUTH_CLIENT_SECRET"
create_client rabbitmq      "https://mq.wbd-rd.nl/oauth2/callback"                "$RABBITMQ_OAUTH_CLIENT_SECRET"

# 4. Create the realm role used for cross-app admin promotion
$KC create roles -r wbd -s name=app-admin \
  -s "description=Grants admin perms across all wbd-realm apps that recognise this role"

# 5. Create the first operator user and grant realm-admin + app-admin
$KC create users -r wbd \
  -s username=r.de.ren -s email=r.de.ren@brabantsedelta.nl -s emailVerified=true \
  -s firstName=R -s lastName='de Ren' -s enabled=true \
  -s 'requiredActions=["UPDATE_PASSWORD"]'
$KC set-password -r wbd --username r.de.ren --new-password '<initial-temp-password>' --temporary
$KC add-roles -r wbd --uusername r.de.ren --cclientid realm-management --rolename realm-admin
$KC add-roles -r wbd --uusername r.de.ren --rolename app-admin

# 6. Final per-app wiring
#    - Gitea: run `gitea admin user create --admin --username r.de.ren ...` then
#             `gitea admin auth add-oauth --name keycloak ...` (see stacks/gitea/README.md)
#    - Everything else picks up its OIDC config from .env on next start.

docker compose restart grafana node-red jenkins jupyterhub
```

After that, every vhost in the smoke-test table redirects unauthenticated users to Keycloak. New teammates: add a user in `https://auth.wbd-rd.nl/admin/wbd/console/` → Users → Add user; default permissions are viewer/read-only across all apps until you also assign them the `app-admin` realm role.

## Adding a new stack

1. Create `stacks/<name>/` with `compose.yml`, `.env.example`, `README.md`.
2. Uncomment (or add) the `include:` entry in `compose.yml`.
3. Add the stack's env vars to `.env.example`.
4. `docker compose pull && docker compose up -d`.