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
4d4ede9e92
commit
14473c5108
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