feat(kb): SPLIT nextcloud -> service + decision + runbook
kb/services/nextcloud.md (Stack, WebDAV dla ingestu, Storage i backup) kb/decisions/nextcloud-host-piha.md (decyzja: host = PIHA) kb/runbooks/nextcloud-cutover.md (OIDC przez Forgejo + cutover checklist) Tresc sekcji nietknieta; kontrola multizbioru linii == oryginal. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
oskar
parent
f869f18dcd
commit
8b1a84064f
36
kb/decisions/nextcloud-host-piha.md
Normal file
36
kb/decisions/nextcloud-host-piha.md
Normal file
|
|
@ -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ł.
|
||||||
|
|
||||||
60
kb/runbooks/nextcloud-cutover.md
Normal file
60
kb/runbooks/nextcloud-cutover.md
Normal file
|
|
@ -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="<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).
|
||||||
54
kb/services/nextcloud.md
Normal file
54
kb/services/nextcloud.md
Normal file
|
|
@ -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/<user>/`.
|
||||||
|
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).
|
||||||
|
|
||||||
|
|
@ -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="<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.
|
|
||||||
|
|
||||||
## WebDAV dla ingestu (moduł 5)
|
|
||||||
|
|
||||||
Endpoint: `https://cloud.kapala.org/remote.php/dav/files/<user>/`.
|
|
||||||
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/<node>/services.yaml` + topology (dopiero przy deployu).
|
|
||||||
Loading…
Reference in a new issue