---
okf: "0.1"
type: runbook
visibility: private
status: active
updated: 2026-07-09
links:
  - ../services/nextcloud.md
  - ../decisions/nextcloud-host-piha.md
---

# Nextcloud — OIDC i cutover checklist

## OIDC przez Forgejo (krok po-deployowy, occ)

Mechanizm: oficjalna appka **`user_oidc`** (utrzymywana przez Nextcloud GmbH —
wybieramy ją zamiast community `sociallogin`). Konfiguruje się ją przez `occ`
po pierwszym starcie — NIE przez env, stąd kroki w checkliście:

```bash
# w kontenerze nextcloud, jako www-data:
docker exec -u www-data nextcloud php occ app:install user_oidc
docker exec -u www-data nextcloud php occ user_oidc:provider forgejo \
  --clientid="<CLIENT_ID>" \
  --clientsecret="<CLIENT_SECRET>" \
  --discoveryuri="https://forgejo.kapala.org/.well-known/openid-configuration" \
  --scope="openid profile email" \
  --unique-uid=0 \
  --mapping-display-name=name --mapping-email=email --mapping-uid=preferred_username
```

Rejestracja w Forgejo (Settings → Applications, wzorzec jak Vikunja):

- Redirect URI: `https://cloud.kapala.org/apps/user_oidc/code`
- Confidential client; scope `openid profile email`

`forgejo.kapala.org` jest przypięte w compose przez `extra_hosts` do
`192.168.31.5` (npm@PIHA) — OIDC discovery po LAN, lekcja z Vikunji.
`--unique-uid=0` + mapping `preferred_username` daje czytelne loginy
(np. `oskar`) zamiast hashowanych ID — istotne dla WebDAV-owych URL-i.

## Cutover checklist (przy deployu — NIE teraz)

1. Host = PIHA (decyzja podjęta); `LAN_BIND_IP`/`TRUSTED_PROXIES` w `.env`
   już pod nią — `TRUSTED_PROXIES` doprecyzować przez `docker network
   inspect` na żywym hoście (patrz komentarz w `env.example`).
2. Port wolny na żywym hoście: `ss -tlnp | grep 8220`.
3. `mkdir -p /opt/homelab/data/nextcloud/{html,db}` na PIHA.
4. `.env` z `env.example`.
5. DNS: rekord A `cloud.kapala.org` w Cloudflare → `100.108.208.3`
   (Tailscale PIHA, DNS Only) — ten sam wzorzec co `ha.kapala.org` /
   `immich.kapala.org` (`docs/sessions/2026-06-30-kapala-cloudflare-wildcard-mesh.md`);
   wildcard `*.kapala.org` już pokrywa tę subdomenę, nowy cert niepotrzebny.
   Plus vhost w npm@PIHA (HTTPS → `192.168.31.5:8220`, Advanced puste).
6. `docker compose up -d`; pierwszy start instaluje NC (2–3 min),
   potem `./healthcheck.sh`.
7. Kroki `occ` dla `user_oidc` (wyżej) + rejestracja appki w Forgejo +
   testowy login OIDC.
8. Test sync klientem (telefon) + test WebDAV (`curl -u user:app-password`).
9. Wpis w `hosts/<node>/services.yaml` + topology (dopiero przy deployu).