diff --git a/kb/decisions/nextcloud-host-piha.md b/kb/decisions/nextcloud-host-piha.md new file mode 100644 index 0000000..9f4840d --- /dev/null +++ b/kb/decisions/nextcloud-host-piha.md @@ -0,0 +1,36 @@ +--- +okf: "0.1" +type: decision +visibility: private +status: active +updated: 2026-07-09 +links: + - ../services/nextcloud.md + - ../runbooks/nextcloud-cutover.md +--- + +# Nextcloud — decyzja: host = PIHA + +## Decyzja: host = PIHA + +Moduł 4 skłaniał się ku SOLARIA (mocniejszy host, bez wpływu na KB — patrz +niżej), ale Oskar zdecydował inaczej: **Nextcloud jest używany aktywnie** +(telefon, sync, rodzina) — sesyjna dostępność SOLARII (sync dogania się +dopiero po wybudzeniu hosta) nie jest akceptowalna dla tego workloadu. +Nextcloud musi być **always-on**, więc ląduje na PIHA mimo ciaśniejszego +RAM/CPU. + +| | PIHA (wybrane) | SOLARIA | +|---|---|---| +| Dostępność | 24/7 (sync zawsze działa) | sesyjna — sync dogania się po wybudzeniu | +| RAM/CPU | ciasno nawet po module 0 (Nextcloud+PHP ≈ 0.5–1 Gi+) | 62 Gi RAM, 24 rdzenie — bez znaczenia | +| Storage | NVMe 477 G (dzielone z resztą) | NVMe 2 T | +| Ingress | npm lokalnie (ten sam host) | npm@PIHA proxuje po LAN do 192.168.31.70:8220 | +| Wpływ na KB | żaden — KB czyta własną kopię z archiwum na PIHA w obu wariantach | jw. | + +`service.yaml` ma `owner_node: piha`; `env.example` ma `LAN_BIND_IP` PIHA +(192.168.31.5) i `TRUSTED_PROXIES` pod docker bridge (npm i nextcloud na +tym samym hoście — patrz komentarz w `env.example`). Compose zostaje +przenośne (ścieżki po konwencji `/opt/homelab/data`), gdyby host kiedyś +się zmienił. + diff --git a/kb/runbooks/nextcloud-cutover.md b/kb/runbooks/nextcloud-cutover.md new file mode 100644 index 0000000..fd43248 --- /dev/null +++ b/kb/runbooks/nextcloud-cutover.md @@ -0,0 +1,60 @@ +--- +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="" \ + --clientsecret="" \ + --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//services.yaml` + topology (dopiero przy deployu). diff --git a/kb/services/nextcloud.md b/kb/services/nextcloud.md new file mode 100644 index 0000000..edb38b5 --- /dev/null +++ b/kb/services/nextcloud.md @@ -0,0 +1,54 @@ +--- +okf: "0.1" +type: service +visibility: private +status: active +updated: 2026-07-09 +links: + - ../decisions/nextcloud-host-piha.md + - ../runbooks/nextcloud-cutover.md +--- + +# Nextcloud (drive / WebDAV) + +Drugi adapter dokumentów filaru KB #2 (moduł 4, `docs/kb/modules/04-nextcloud.md`): +zamiennik Google Drive — dowolne pliki + sync telefon/desktop, źródło dla +ingestu KB (moduł 5) przez WebDAV. + +**Nextcloud = archiwum KOPIA w hybrydzie kb-02** — ingest robi snapshot pliku +do archiwum KB; Nextcloud NIE jest źródłem prawdy (inaczej niż Paperless). +Backup „warto" (dane użytkownika), ale nie jest warunkiem brzegowym KB. + +## Stack + +| Kontener | Obraz | Rola | +|------------------|-------------------------|---------------------------------------| +| `nextcloud` | `nextcloud:34-apache` | app + WebDAV (port 80 → host 8220 na LAN_BIND_IP) | +| `nextcloud-cron` | `nextcloud:34-apache` | joby w tle (`/cron.sh`, ten sam wolumen) | +| `nextcloud-db` | `postgres:16-alpine` | baza (bez portu na hoście) | +| `nextcloud-redis`| `redis:7-alpine` | cache + file locking (bez portu, bez persystencji) | + +Wersja przypięta na `34-apache` (aktualny stable na 2026-07-09, wydany +2026-06-09 — zweryfikowane przez endoflife.date/nextcloud). Nextcloud +wydaje nowy major co ~4 miesiące i nie wspiera przeskakiwania wersji przy +upgrade — **TODO PRZY DEPLOYU**: potwierdzić bieżący stable tuż przed +`docker compose up` i podbić tag, jeśli wyszła nowsza wersja. + +## WebDAV dla ingestu (moduł 5) + +Endpoint: `https://cloud.kapala.org/remote.php/dav/files//`. +Konta OIDC nie mają hasła — dla ingestu wygenerować **app password** +(Settings → Security → Devices & sessions) i trzymać je w sekretach +adaptera ingest, nie w tym repo. + +## Storage i backup + +- `/opt/homelab/data/nextcloud/html` — aplikacja + config + **pliki + użytkowników** (`html/data/`) +- `/opt/homelab/data/nextcloud/db` — Postgres + +TODO DECYZJA OSKARA: backup user-data (mniej krytyczny niż Paperless, bo +KB trzyma kopie zaingestowanych plików): propozycja — rsync/borg +`html/data` + `pg_dump` w tej samej nocnej pętli co backup Paperlessa, +retencja krótsza (np. 7 dziennych + 4 tygodniowe). + diff --git a/services/nextcloud/README.md b/services/nextcloud/README.md deleted file mode 100644 index 2e0f5ae..0000000 --- a/services/nextcloud/README.md +++ /dev/null @@ -1,113 +0,0 @@ -# Nextcloud (drive / WebDAV) - -Drugi adapter dokumentów filaru KB #2 (moduł 4, `docs/kb/modules/04-nextcloud.md`): -zamiennik Google Drive — dowolne pliki + sync telefon/desktop, źródło dla -ingestu KB (moduł 5) przez WebDAV. - -**Nextcloud = archiwum KOPIA w hybrydzie kb-02** — ingest robi snapshot pliku -do archiwum KB; Nextcloud NIE jest źródłem prawdy (inaczej niż Paperless). -Backup „warto" (dane użytkownika), ale nie jest warunkiem brzegowym KB. - -## Decyzja: host = PIHA - -Moduł 4 skłaniał się ku SOLARIA (mocniejszy host, bez wpływu na KB — patrz -niżej), ale Oskar zdecydował inaczej: **Nextcloud jest używany aktywnie** -(telefon, sync, rodzina) — sesyjna dostępność SOLARII (sync dogania się -dopiero po wybudzeniu hosta) nie jest akceptowalna dla tego workloadu. -Nextcloud musi być **always-on**, więc ląduje na PIHA mimo ciaśniejszego -RAM/CPU. - -| | PIHA (wybrane) | SOLARIA | -|---|---|---| -| Dostępność | 24/7 (sync zawsze działa) | sesyjna — sync dogania się po wybudzeniu | -| RAM/CPU | ciasno nawet po module 0 (Nextcloud+PHP ≈ 0.5–1 Gi+) | 62 Gi RAM, 24 rdzenie — bez znaczenia | -| Storage | NVMe 477 G (dzielone z resztą) | NVMe 2 T | -| Ingress | npm lokalnie (ten sam host) | npm@PIHA proxuje po LAN do 192.168.31.70:8220 | -| Wpływ na KB | żaden — KB czyta własną kopię z archiwum na PIHA w obu wariantach | jw. | - -`service.yaml` ma `owner_node: piha`; `env.example` ma `LAN_BIND_IP` PIHA -(192.168.31.5) i `TRUSTED_PROXIES` pod docker bridge (npm i nextcloud na -tym samym hoście — patrz komentarz w `env.example`). Compose zostaje -przenośne (ścieżki po konwencji `/opt/homelab/data`), gdyby host kiedyś -się zmienił. - -## Stack - -| Kontener | Obraz | Rola | -|------------------|-------------------------|---------------------------------------| -| `nextcloud` | `nextcloud:34-apache` | app + WebDAV (port 80 → host 8220 na LAN_BIND_IP) | -| `nextcloud-cron` | `nextcloud:34-apache` | joby w tle (`/cron.sh`, ten sam wolumen) | -| `nextcloud-db` | `postgres:16-alpine` | baza (bez portu na hoście) | -| `nextcloud-redis`| `redis:7-alpine` | cache + file locking (bez portu, bez persystencji) | - -Wersja przypięta na `34-apache` (aktualny stable na 2026-07-09, wydany -2026-06-09 — zweryfikowane przez endoflife.date/nextcloud). Nextcloud -wydaje nowy major co ~4 miesiące i nie wspiera przeskakiwania wersji przy -upgrade — **TODO PRZY DEPLOYU**: potwierdzić bieżący stable tuż przed -`docker compose up` i podbić tag, jeśli wyszła nowsza wersja. - -## 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="" \ - --clientsecret="" \ - --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. - -## WebDAV dla ingestu (moduł 5) - -Endpoint: `https://cloud.kapala.org/remote.php/dav/files//`. -Konta OIDC nie mają hasła — dla ingestu wygenerować **app password** -(Settings → Security → Devices & sessions) i trzymać je w sekretach -adaptera ingest, nie w tym repo. - -## Storage i backup - -- `/opt/homelab/data/nextcloud/html` — aplikacja + config + **pliki - użytkowników** (`html/data/`) -- `/opt/homelab/data/nextcloud/db` — Postgres - -TODO DECYZJA OSKARA: backup user-data (mniej krytyczny niż Paperless, bo -KB trzyma kopie zaingestowanych plików): propozycja — rsync/borg -`html/data` + `pg_dump` w tej samej nocnej pętli co backup Paperlessa, -retencja krótsza (np. 7 dziennych + 4 tygodniowe). - -## 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//services.yaml` + topology (dopiero przy deployu).