docs(pliki): runbook otwarcia udziału z bazami na zapis (zgubiony przy merge'u)

Treść powstała jako commit na gałęzi feat/pliki-zapis JUŻ PO zmergowaniu jej
PR-a, więc nigdy nie trafiła na master — został tam wyłącznie manifest.
Sam manifest jest w porządku (readOnly zdjęte), brakowało tylko opisu, co z tym
zrobić po stronie NAS-a.

Runbook zawiera: komendy midclt otwierające udział z bazami na zapis, sprawdzenie
przez exportfs (bo konfiguracja udziału i stan eksportu to dwie różne rzeczy),
ostrzeżenie, że przeładowanie musi iść przez zero replik zamiast rollout restart,
oraz listę kontrolną po wdrożeniu — z wyszukiwaniem jako punktem NAJWAŻNIEJSZYM,
bo to jedyne miejsce, w którym ta zmiana mogłaby przejść niezauważona.

Osobno wyliczone, co świadomie tracimy: DAN-25 dawał gwarancję, że baz nie da się
zmienić przez NFS, i tych dwóch rzeczy nie da się mieć naraz.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

astrololo/README-pliki.md

@@ -0,0 +1,133 @@
+# Zarządzanie plikami baz — otwarcie udziału na zapis (DAN-27)
+
+Ekran „Pliki" pozwala wgrywać bazy, archiwizować je i (dla administratora)
+kasować, a stan użycia jest **klikany**, więc musi być trwały. Wymaga to zapisu
+do udziału z bazami — a ten jest dziś wyeksportowany tylko do odczytu.
+
+---
+
+## Co świadomie tracimy
+
+DAN-25 dawał gwarancję, że **baz nie da się zmienić przez NFS**. DAN-27 tę
+gwarancję z definicji znosi — nie da się mieć obu naraz.
+
+**Co zostaje:**
+
+| zabezpieczenie | działa nadal |
+|---|---|
+| eksport zawężony do trzech węzłów k8s | ✅ |
+| token międzywarstwowy | ✅ |
+| szyfrowane łącze prezentacja ↔ logika ↔ dane | ✅ |
+| kasowanie plików wyłącznie z konta administracyjnego (PRE-27) | ✅ |
+| dziennik audytowy (kto, kiedy, co) | ✅ |
+
+Ryzyko, które przybywa: **przejęcie warstwy danych pozwala teraz nie tylko
+odczytać bazy, ale i je zmienić.**
+
+---
+
+## Krok 1 — otwórz udział na zapis
+
+```bash
+midclt call sharing.nfs.query '[["path","=","/mnt/Tank1/astrololo"]]' \
+  | python3 -c "import sys,json;[print(s['id'], '| ro:', s['ro'], '| mapall:', s.get('mapall_user')) for s in json.load(sys.stdin)]"
+```
+
+Weź `id` i podstaw za `<ID>`:
+
+```bash
+midclt call sharing.nfs.update <ID> '{"ro": false, "mapall_user": "root", "mapall_group": "root"}'
+```
+
+> **Dlaczego `mapall_user`, skoro katalog ma `drwxrwxrwx`?** Samo `ro: false`
+> wystarczyłoby do zapisu — zmapowany `nobody` mieści się w prawach „innych".
+> Ale nowe pliki należałyby wtedy do `nobody`, a istniejące bazy do `root`.
+> Mieszana własność zemści się przy pierwszym zaostrzeniu praw. `mapall_user:
+> root` daje spójność i jest tym samym ustawieniem, co na udziale `astrololo-state`.
+
+```bash
+midclt call service.restart nfs
+```
+
+Sprawdź, że zmiana **faktycznie trafiła do jądra** — sama konfiguracja to za mało:
+
+```bash
+sudo exportfs -v | grep -A1 "Tank1/astrololo "
+```
+
+Przy `/mnt/Tank1/astrololo` musi być `rw`, nie `ro`.
+
+---
+
+## Krok 2 — zmerguj oba PR-y
+
+* aplikacja: `feat/zarzadzanie-plikami`
+* deploy: `feat/pliki-zapis` (zdejmuje `readOnly` z montowania w podzie)
+
+Bez tego drugiego pod nadal montuje udział tylko do odczytu, choćby serwer
+pozwalał pisać.
+
+---
+
+## Krok 3 — przeładuj warstwę danych PRZEZ ZERO REPLIK
+
+> ⚠️ **`rollout restart` NIE WYSTARCZY.** Stary i nowy pod na chwilę
+> współistnieją, więc montowanie NFS ani na moment nie zostaje bez użytkownika
+> i nowy pod dziedziczy uprawnienia sprzed zmiany eksportu. To kosztowało
+> najwięcej czasu przy udziale `astrololo-state` — patrz
+> [README-stan-prezentacji.md](README-stan-prezentacji.md).
+
+```bash
+kubectl -n astrololo scale deploy/data --replicas=0
+kubectl -n astrololo wait --for=delete pod -l app=data --timeout=90s
+kubectl -n astrololo scale deploy/data --replicas=1
+kubectl -n astrololo rollout status deploy/data
+```
+
+---
+
+## Krok 4 — sprawdź, w tej kolejności
+
+**Czy warstwa danych może pisać:**
+
+```bash
+kubectl -n astrololo exec deploy/data -- sh -c 'touch /app/data_files/proba && echo ZAPIS-OK && rm /app/data_files/proba'
+```
+
+**Czy powstał plik stanu i czy bazy zostały przyjęte jako aktywne:**
+
+```bash
+kubectl -n astrololo exec deploy/data -- sh -c 'cat /app/data_files/.files-state.json' | head -20
+```
+
+Oczekiwane: każda baza ze `"status": "active"`. Przy pierwszym uruchomieniu bazy
+zastane na udziale są przyjmowane automatycznie — **bez tego wyszukiwanie
+przestałoby cokolwiek znajdować**, bo plik bez wpisu w rejestrze nie bierze
+udziału w wynikach.
+
+**Czy wyszukiwanie NADAL DZIAŁA** — to jest najważniejszy sprawdzian tego
+wdrożenia, bo właśnie tu zmiana mogłaby przejść niezauważona:
+
+```bash
+kubectl -n astrololo logs deploy/data --tail=20
+```
+
+a potem w przeglądarce: zakładka **Sygnifikatory**, dowolne wyszukanie. Musi
+zwracać wyniki jak przedtem. Jeśli nagle nic nie znajduje — zajrzyj do
+`.files-state.json` z komendy wyżej.
+
+**Czy ekran „Pliki" działa:** zakładka **Pliki**, lista baz, przełącznik przy
+każdej. Wgraj testowy plik, zarchiwizuj go, skasuj.
+
+---
+
+## Odkręcenie
+
+```bash
+midclt call sharing.nfs.update <ID> '{"ro": true, "mapall_user": null, "mapall_group": null}'
+midclt call service.restart nfs
+```
+
+plus cofnięcie deploy `feat/pliki-zapis`. Ekran „Pliki" zostanie, ale wgrywanie
+i kasowanie przestaną działać — a stan użycia przestanie się zapisywać, więc bazy
+będą przyjmowane od nowa przy każdym starcie (czyli wszystkie aktywne).

astrololo/README-postgres.md

@@ -0,0 +1,284 @@
+# Postgres — lustro baz w SQL (DAN-28)
+
+Runbook krok po kroku. Zakłada, że nie pamiętasz nic z rozmowy, w której to
+powstało.
+
+---
+
+## Co to jest — i czego to NIE jest
+
+Postgres trzyma **lustro** plików Excela, żeby wyszukiwanie było szybsze i mądrzejsze.
+
+> **ŹRÓDŁEM PRAWDY SĄ PLIKI EXCELA NA NFS.** Utrata tej bazy **nie jest utratą
+> danych** — odbudowuje się z plików. Dlatego kopie zapasowe Postgresa są tu
+> **opcjonalne**, a wolumen stoi na `local-path` zamiast na NFS.
+
+Po co w ogóle Postgres, skoro danych jest mało (~54 tys. wierszy)? Nie dla skali —
+przy takim rozmiarze SQLite bywa szybszy. Dla **wyszukiwania w polskim,
+nieznormalizowanym tekście**: `pg_trgm` (dopasowanie mimo literówek) i `unaccent`
+(ogonki) nie mają w SQLite taniego zamiennika.
+
+---
+
+## Część 1 — co zrobiłem za Ciebie (w repo)
+
+Nic z tego nie wymaga Twojej ręki, ale wiedz, co jest gdzie:
+
+| plik | co w nim jest |
+|---|---|
+| `astrololo/postgres.yaml` | PVC (5 Gi, `local-path`), ConfigMap z SQL-em inicjalizującym, Deployment (`Recreate`), Service `ClusterIP` |
+| `astrololo/kustomization.yaml` | `postgres.yaml` dopisany **przed** `data.yaml` |
+| `astrololo/data.yaml` | `SQL_URL` z sekretu; `DATA_PROVIDER` **zostaje `excel`** |
+| repo aplikacji: `services/data/requirements.txt` | sterownik `psycopg[binary]` |
+
+Decyzje, które w tych plikach zapadły — żeby nie trzeba było ich odtwarzać z głowy:
+
+* **`local-path`, nie NFS.** Postgres zakłada semantykę blokad i `fsync`, której NFS
+  nie gwarantuje — to klasyczne źródło uszkodzenia bazy przy nagłym restarcie.
+  Ceną jest przywiązanie do węzła; przy luście odtwarzalnym z Excela to nie boli.
+* **`strategy: Recreate`.** Wolumen jest `ReadWriteOnce`, a dwa procesy Postgresa
+  na jednym katalogu danych to uszkodzona baza. Rolling próbowałby wstać z nowym
+  podem, zanim stary zejdzie.
+* **`PGDATA` w podkatalogu** (`…/data/pgdata`). Katalog główny wolumenu potrafi
+  zawierać wpisy systemu plików, a `initdb` odmawia pracy w niepustym katalogu.
+* **Wersja przypięta (`postgres:17`) i POZA image-updaterem.** Podbicie majora
+  wymaga migracji katalogu danych — nie może się zdarzyć samo, w nocy, przy okazji
+  builda aplikacji.
+* **`DATA_PROVIDER` zostaje na `excel`.** Postgres można wdrożyć i obejrzeć **bez
+  żadnego ryzyka** dla działającego wyszukiwania. Przełączenie na `sql` to osobna,
+  późniejsza decyzja — po wdrożeniu lustra.
+
+---
+
+## Część 2 — co musisz zrobić Ty
+
+### Krok 0. Sprawdź, że klaster ma `local-path`
+
+```bash
+kubectl get storageclass
+```
+
+Oczekiwany wynik: linia z `local-path` i dopiskiem `(default)`. W k3s jest
+domyślnie. **Jeśli jej nie ma — zatrzymaj się tutaj** i daj znać; bez niej PVC
+zawiśnie w `Pending`.
+
+### Krok 1. Utwórz sekret `astrololo-postgres`
+
+Ta sama konwencja co `astrololo-auth`: **sekretu nie ma w repo**, bo to repo
+GitOps i cokolwiek by tu wpadło, zostałoby w historii gita na zawsze.
+
+```bash
+PGPASS="$(openssl rand -base64 24 | tr -d '/+=' | head -c 32)"
+
+kubectl -n astrololo create secret generic astrololo-postgres \
+  --from-literal=POSTGRES_PASSWORD="$PGPASS" \
+  --from-literal=SQL_URL="postgresql+psycopg://astrololo:${PGPASS}@postgres:5432/astrololo"
+
+unset PGPASS
+```
+
+Hasła **nie musisz nigdzie zapisywać ani nigdy oglądać** — używają go tylko usługi
+między sobą. Gdybyś kiedyś go potrzebował:
+
+```bash
+kubectl -n astrololo get secret astrololo-postgres \
+  -o jsonpath='{.data.POSTGRES_PASSWORD}' | base64 -d; echo
+```
+
+> **Dlaczego dwa klucze, skoro hasło jest w obu?** `POSTGRES_PASSWORD` czyta sam
+> Postgres przy inicjalizacji, `SQL_URL` czyta warstwa danych. Rozdzielone, bo to
+> dwa różne formaty i dwóch różnych odbiorców — sklejanie DSN-a w manifeście
+> wymagałoby wstawienia tam hasła.
+
+### Krok 2. Wdróż
+
+Jeśli ArgoCD pilnuje katalogu `astrololo`, wystarczy **zmergować PR** — reszta
+zrobi się sama. Ręcznie:
+
+```bash
+kubectl apply -k astrololo
+```
+
+### Krok 3. Sprawdź, że wstało
+
+```bash
+kubectl -n astrololo rollout status deploy/postgres
+kubectl -n astrololo get pvc postgres-data
+```
+
+Oczekiwane: `deployment "postgres" successfully rolled out` i PVC w stanie `Bound`.
+
+### Krok 4. Sprawdź, że rozszerzenia się założyły
+
+To jest **najważniejszy sprawdzian tego wdrożenia** — bez tych rozszerzeń cały
+sens stawiania Postgresa znika.
+
+```bash
+kubectl -n astrololo exec deploy/postgres -- \
+  psql -U astrololo -d astrololo -c "\dx"
+```
+
+Na liście muszą być **`pg_trgm`** i **`unaccent`**. Sprawdź też, że działają:
+
+```bash
+kubectl -n astrololo exec deploy/postgres -- psql -U astrololo -d astrololo -c \
+  "SELECT unaccent('różdżka')                              AS bez_ogonkow,
+          similarity(unaccent('różdżka'), 'rozdzka')       AS po_zdjeciu_ogonkow,
+          similarity('kowalski', 'kowlaski') > 0.3         AS literowka_lapana;"
+```
+
+Oczekiwane **dokładnie**:
+
+```
+ bez_ogonkow | po_zdjeciu_ogonkow | literowka_lapana
+-------------+--------------------+------------------
+ rozdzka     |                  1 | t
+```
+
+Pierwsza kolumna pokazuje, że `unaccent` zna polskie znaki; druga, że po zdjęciu
+ogonków słowa są **identyczne** (stąd równo `1`); trzecia, że `pg_trgm` łapie
+przestawione litery. Jeśli druga kolumna nie jest równa `1`, rozszerzenia są, ale
+reguły `unaccent` nie obsługują polskich znaków — daj znać, bo to zmienia sposób
+budowania indeksów.
+
+### Krok 5. Sprawdź, że warstwa danych ma połączenie
+
+```bash
+kubectl -n astrololo rollout restart deploy/data
+kubectl -n astrololo rollout status deploy/data
+kubectl -n astrololo logs deploy/data --tail=30 | grep -i -E "sql|postgres|error" || echo "brak wzmianek — OK"
+```
+
+Na tym etapie warstwa danych **nadal czyta Excela** (`DATA_PROVIDER=excel`).
+Postgres tylko stoi i czeka. Aplikacja ma działać dokładnie jak przedtem —
+i to jest oczekiwany wynik tego wdrożenia.
+
+---
+
+## Część 3 — obsługa na co dzień
+
+### Zajrzeć do bazy
+
+```bash
+kubectl -n astrololo exec -it deploy/postgres -- psql -U astrololo -d astrololo
+```
+
+Przydatne w środku: `\dt mirror.*` (tabele lustra), `\dx` (rozszerzenia),
+`\l` (bazy), `\q` (wyjście).
+
+### Podłączyć narzędzie graficzne z laptopa
+
+Baza **celowo nie jest wystawiona poza klaster**. Na czas jednej sesji:
+
+```bash
+kubectl -n astrololo port-forward deploy/postgres 5432:5432
+```
+
+i łączysz się na `localhost:5432`, użytkownik `astrololo`, baza `astrololo`,
+hasło jak w kroku 1. Po zamknięciu terminala tunel znika.
+
+### Dodanie rozszerzenia do ISTNIEJĄCEJ bazy
+
+> ⚠️ **Pułapka.** Skrypty z `/docker-entrypoint-initdb.d/` uruchamiają się
+> **wyłącznie przy pierwszej inicjalizacji**, na pustym katalogu danych. Dopisanie
+> rozszerzenia do ConfigMapy **nie zrobi nic**, jeśli baza już istnieje.
+
+```bash
+kubectl -n astrololo exec deploy/postgres -- \
+  psql -U astrololo -d astrololo -c "CREATE EXTENSION IF NOT EXISTS nazwa;"
+```
+
+### Kopia zapasowa (opcjonalna — patrz nagłówek)
+
+```bash
+kubectl -n astrololo exec deploy/postgres -- \
+  pg_dump -U astrololo -d astrololo -Fc > astrololo-$(date +%F).dump
+```
+
+Odtworzenie:
+
+```bash
+kubectl -n astrololo exec -i deploy/postgres -- \
+  pg_restore -U astrololo -d astrololo --clean --if-exists < astrololo-2026-08-06.dump
+```
+
+### Wyczyścić lustro i wczytać od nowa
+
+```bash
+kubectl -n astrololo exec deploy/postgres -- psql -U astrololo -d astrololo -c \
+  "DROP SCHEMA mirror CASCADE; CREATE SCHEMA mirror;"
+```
+
+Po tym warstwa danych odbuduje lustro z plików Excela (gdy lustro będzie już
+zaimplementowane — dziś ta komenda tylko czyści pusty schemat).
+
+### Podbicie wersji Postgresa
+
+**Nie robi się tego przez zmianę tagu w manifeście.** Major wymaga migracji
+katalogu danych. Ponieważ to lustro:
+
+1. `kubectl -n astrololo scale deploy/data --replicas=0`
+2. skasuj Deployment i **PVC** (`kubectl -n astrololo delete deploy/postgres pvc/postgres-data`)
+3. zmień tag obrazu w `postgres.yaml`, wdróż ponownie
+4. `kubectl -n astrololo scale deploy/data --replicas=1` — lustro odbuduje się z Excela
+
+To jest właśnie ta sytuacja, w której „lustro, nie źródło prawdy" oszczędza dzień
+pracy.
+
+---
+
+## Co zostało sprawdzone przed oddaniem, a co nie
+
+**Sprawdzone:** `kubectl kustomize astrololo` składa komplet 21 zasobów bez błędu;
+YAML wszystkich manifestów parsuje się poprawnie; audyt odwołań do sekretów
+potwierdza, że jedyne brakujące to `astrololo-postgres` (oba klucze); DSN
+`postgresql+psycopg://…` jest poprawnie rozpoznawany przez SQLAlchemy 2.0
+z zainstalowanym `psycopg` 3.
+
+**NIE sprawdzone, bo nie było na czym:** skrypt inicjalizujący nie został
+uruchomiony przeciwko prawdziwemu Postgresowi (na maszynie, na której to
+powstawało, nie ma Dockera). Składnia jest prosta i przejrzana, ale **krok 4 jest
+tu prawdziwym testem** — jeśli coś ma nie zadziałać, to właśnie tam.
+
+---
+
+## Część 4 — typowe problemy
+
+| objaw | przyczyna | co zrobić |
+|---|---|---|
+| PVC wisi w `Pending` | brak `local-path` albo brak miejsca na węźle | `kubectl get storageclass`, `kubectl describe pvc postgres-data` |
+| pod w `CrashLoopBackOff`, w logach `directory not empty` | `PGDATA` wskazuje katalog główny wolumenu | sprawdź, czy `PGDATA` to `…/data/pgdata` (jest w manifeście) |
+| pod nie startuje, `secret not found` | nie wykonany krok 1 | utwórz sekret i `kubectl -n astrololo rollout restart deploy/postgres` |
+| `\dx` nie pokazuje `pg_trgm` | baza założona przed dodaniem ConfigMapy | patrz „Dodanie rozszerzenia do istniejącej bazy" |
+| warstwa danych: `ModuleNotFoundError: psycopg` | obraz zbudowany przed dodaniem sterownika | poczekaj na build z CI albo `kubectl -n astrololo rollout restart deploy/data` po nowym obrazie |
+| `password authentication failed` | `SQL_URL` w sekrecie nie zgadza się z `POSTGRES_PASSWORD` | odtwórz sekret krokiem 1 (oba klucze naraz) i zrestartuj **oba** deploymenty |
+
+Gdy nic nie pasuje — pierwsze dwie komendy do wklejenia:
+
+```bash
+kubectl -n astrololo describe pod -l app=postgres | tail -30
+kubectl -n astrololo logs deploy/postgres --tail=50
+```
+
+---
+
+## Część 5 — pełne odtworzenie ręczne, bez ArgoCD i bez repo
+
+Gdyby trzeba było postawić to od zera na czystym klastrze:
+
+```bash
+kubectl create namespace astrololo
+
+PGPASS="$(openssl rand -base64 24 | tr -d '/+=' | head -c 32)"
+kubectl -n astrololo create secret generic astrololo-postgres \
+  --from-literal=POSTGRES_PASSWORD="$PGPASS" \
+  --from-literal=SQL_URL="postgresql+psycopg://astrololo:${PGPASS}@postgres:5432/astrololo"
+unset PGPASS
+
+kubectl apply -f astrololo/postgres.yaml
+kubectl -n astrololo rollout status deploy/postgres
+kubectl -n astrololo exec deploy/postgres -- psql -U astrololo -d astrololo -c "\dx"
+```
+
+Reszta aplikacji wymaga jeszcze sekretów `astrololo-auth` i `astrololo-link` —
+patrz [README.md](README.md).

astrololo/README-stan-prezentacji.md

@@ -44,116 +44,46 @@ Jeśli `Tank1` nie jest pulą ZFS albo wolisz zwykły katalog:
 sudo mkdir -p /mnt/Tank1/astrololo-state
 ```
 
-### Właściciel i prawa — TU JEST NAJCZĘSTSZY BŁĄD
+### Właściciel i prawa
 
-Kontenery aplikacji działają **jako root** (`uid=0`), a NFS domyślnie stosuje
+Kontenery aplikacji działają **jako root**, a eksport ma `root_squash`, więc root
-**`root_squash`**: root z klienta NIE jest rootem na udziale — ląduje jako
+z klienta NIE jest rootem na udziale. Żeby zapis działał, przypinamy cały ruch
-`nobody`. Świeży dataset ma prawa `drwxrwx--- root root`, czyli **nic dla
+z tych hostów do jednego, nieuprzywilejowanego użytkownika — to bezpieczniejsze
-„innych"** — i dlatego zapis odbija się o `Permission denied`, mimo że `ls`
+niż `no_root_squash`, bo nie oddaje roota.
-w podzie pokazuje `root root`.
-
-To myli, bo `ls` pokazuje właściciela KATALOGU, a nie to, kim jest dla serwera
-proces, który próbuje pisać.
-
-Do wyboru dwa rozwiązania. Oba trzeba ustawić **przy eksporcie** (niżej), tu
-tylko przygotowujemy katalog.
-
-**A. Prościej — bez zakładania użytkownika.** Katalog zostaje `root:root 770`,
-a przy eksporcie ustawiamy `mapall_user: "root"`. To wyłącza squash **dla tego
-jednego udziału**. Zasięg jest wąski: eksportowany jest wyłącznie ten katalog,
-montują go tylko trzy węzły k8s, leży w nim jeden plik. Nic nie trzeba robić —
-świeży dataset ma już właściwe prawa.
-
-**B. Czyściej — dedykowany użytkownik.** Zakładasz w UI TrueNAS
-nieuprzywilejowanego użytkownika (np. `astrololo`), a potem:
 
 ```bash
-sudo chown -R astrololo:astrololo /mnt/Tank1/astrololo-state
+# użytkownik, na którego mapujemy (jeśli nie istnieje — utwórz w UI TrueNAS)
+sudo chown -R apps:apps /mnt/Tank1/astrololo-state
 sudo chmod 770 /mnt/Tank1/astrololo-state
 ```
 
-i przy eksporcie podstawiasz go w `mapall_user`. Efekt ten sam, bez oddawania
+> Podstaw swojego użytkownika w miejsce `apps`. Sprawdzisz istniejących:
-roota — kosztem jednego użytkownika więcej do pamiętania.
-
-> Istniejących użytkowników sprawdzisz przez:
 > `midclt call user.query | python3 -c "import sys,json;[print(u['uid'], u['username']) for u in json.load(sys.stdin)]"`
 
-> **Czego NIE robić:** `chmod 777`. Zadziała, ale uczyni katalog zapisywalnym dla
-> każdego lokalnego użytkownika NAS-a — a leżą tam hashe haseł, więc jest to plik
-> wrażliwszy niż same bazy Excela.
-
 ### Eksport NFS
 
-> **Najpierw sprawdź, czy udziału już nie ma.** `sharing.nfs.create` odmawia
-> z komunikatem `Export conflict`, jeśli ten sam katalog jest już eksportowany —
-> wtedy trzeba go **zaktualizować**, nie tworzyć.
-
-```bash
-midclt call sharing.nfs.query '[["path","=","/mnt/Tank1/astrololo-state"]]' \
-  | python3 -m json.tool
-```
-
-**Pusta lista `[]`** — udziału nie ma, twórz:
-
 ```bash
 midclt call sharing.nfs.create '{
   "path": "/mnt/Tank1/astrololo-state",
   "comment": "astrololo — stan prezentacji (konta PRE-27)",
   "hosts": ["192.168.1.73", "192.168.1.80", "192.168.1.81"],
-  "enabled": true,
   "ro": false,
-  "mapall_user": "root",
+  "mapall_user": "apps",
-  "mapall_group": "root"
+  "mapall_group": "apps"
 }'
 ```
 
-**Coś zwróciło** — weź `id` z wyniku i zaktualizuj (podstaw `<ID>`):
-
-```bash
-midclt call sharing.nfs.update <ID> '{
-  "hosts": ["192.168.1.73", "192.168.1.80", "192.168.1.81"],
-  "enabled": true,
-  "ro": false,
-  "mapall_user": "root",
-  "mapall_group": "root"
-}'
-```
-
-> Wybrałeś wariant B? Podstaw swojego użytkownika zamiast `root` w obu polach.
-
 | ustawienie | po co |
 |---|---|
 | `hosts` zawężone | te same trzy węzły k8s co w DAN-25 — nikt inny nie zamontuje |
 | `ro: false` | **musi być zapisywalny**, inaczej konta się nie zapiszą |
-| `mapall_user` | cały ruch z tych hostów pisze jako JEDEN użytkownik, niezależnie od UID w kontenerze — bez tego `root_squash` zamienia roota z poda na `nobody`, który nie ma praw do katalogu |
+| `mapall_user` | cały ruch pisze jako jeden nieuprzywilejowany użytkownik, niezależnie od UID w kontenerze |
 
 > Podstaw swoje adresy węzłów, jeśli się zmieniły. Aktualne:
 > `kubectl get nodes -o wide`
 
 ---
 
-### Sprawdź, co serwer FAKTYCZNIE eksportuje
-
-Konfiguracja udziału i stan eksportu to **dwie różne rzeczy**: zapisana
-konfiguracja nie znaczy, że usługa ją przeładowała. To jest prawda:
-
-```bash
-sudo exportfs -v | grep -A1 astrololo
-```
-
-Muszą być **dwa** wpisy: `/mnt/Tank1/astrololo` (z `ro`) oraz
-`/mnt/Tank1/astrololo-state` (z `rw`), oba z listą trzech węzłów.
-
-Jeśli `astrololo-state` **nie ma na liście**, mimo że `sharing.nfs.query` go
-pokazuje — usługa nie przeładowała eksportów:
-
-```bash
-midclt call service.restart nfs
-sudo exportfs -v | grep astrololo-state
-```
-
----
-
 ## Krok 2 — sprawdź z węzła, ZANIM wdrożysz
 
 To jest ten test, którego zabrakło za pierwszym razem:
@@ -164,18 +94,8 @@ ssh 192.168.1.73 'sudo mount -t nfs 192.168.1.34:/mnt/Tank1/astrololo-state /mnt
   && sudo rm /mnt/test/proba; sudo umount /mnt/test'
 ```
 
-Musi wypisać **`ZAPIS DZIAŁA`**.
+Musi wypisać **`ZAPIS DZIAŁA`**. Jeśli zamiast tego widzisz `Permission denied` —
-
+wróć do praw katalogu i `mapall_user` w kroku 1.
-| co widzisz | co to znaczy |
-|---|---|
-| `Permission denied` przy `touch` | montowanie działa, brakuje praw — wróć do właściciela katalogu i `mapall_user` |
-| `access denied by server while mounting` | serwer nie wpuszcza w ogóle: sprawdź `exportfs -v` (czy eksport istnieje i przeładowany), `enabled: true` w udziale oraz czy adres węzła jest na liście `hosts` |
-| `No such file or directory` | katalog `/mnt/Tank1/astrololo-state` nie istnieje na NAS-ie |
-| montuje się tylko z `-o vers=3` | negocjacja wersji: dopisz `mountOptions` w manifeście albo włącz NFSv4 w `midclt call nfs.config` |
-
-Adresy węzłów sprawdzisz przez `kubectl get nodes -o wide` — jeśli któryś się
-zmienił od czasu DAN-25, lista `hosts` jest nieaktualna i to wystarczy, żeby
-serwer odmówił.
 
 ---
 
@@ -197,70 +117,6 @@ Oczekiwane: plik `accounts.json`.
 
 ---
 
-## Jeśli mimo wszystko `Permission denied`
-
-Trzy komendy, w tej kolejności:
-
-```bash
-kubectl -n astrololo exec deploy/presentation -- sh -c 'id; ls -ld /app/state; touch /app/state/proba && echo ZAPIS-OK || echo ZAPIS-NIE'
-```
-
-```bash
-midclt call sharing.nfs.query '[["path","=","/mnt/Tank1/astrololo-state"]]' \
-  | python3 -c "import sys,json;[print('ro:', s['ro'], '| mapall:', s.get('mapall_user'), '| hosts:', s['hosts']) for s in json.load(sys.stdin)]"
-```
-
-```bash
-sudo ls -ld /mnt/Tank1/astrololo-state
-```
-
-Zestaw, który DZIAŁA: kontener jako `uid=0(root)`, udział z `ro: false`
-i `mapall: root`, katalog `drwxrwx--- root root`.
-
-### ⚠️ Po zmianie eksportu `rollout restart` NIE WYSTARCZA
-
-To kosztowało najwięcej czasu przy pierwszym wdrożeniu, więc zapisane wprost.
-
-**Objaw:** eksport poprawiony, `service.restart nfs` wykonany, pod zrestartowany —
-a zapis z poda nadal odbija się o `Permission denied`. Przy czym **ręczne
-zamontowanie tego samego eksportu z tego samego węzła działa** i pozwala pisać.
-
-**Co z tym zrobić:** doprowadzić do stanu, w którym ŻADEN pod nie trzyma tego
-montowania.
-
-```bash
-kubectl -n astrololo scale deploy/presentation --replicas=0
-kubectl -n astrololo wait --for=delete pod -l app=presentation --timeout=90s
-kubectl -n astrololo scale deploy/presentation --replicas=1
-kubectl -n astrololo rollout status deploy/presentation
-```
-
-`rollout restart` tego nie osiąga, bo stary i nowy pod na chwilę WSPÓŁISTNIEJĄ —
-w logu widać `1 old replicas are pending termination`. Montowanie ani na moment
-nie zostaje bez użytkownika. (W ArgoCD ten sam skutek daje `force delete` poda.)
-
-**Dlaczego (hipoteza, nie potwierdzona u źródła):** jądro współdzieli strukturę
-montowania NFS między montowania tego samego eksportu na węźle, razem z cache
-odpowiedzi ACCESS. Nowy pod podpina się do żywego montowania i dziedziczy
-odpowiedź sprzed zmiany eksportu.
-
-**Test, który rozstrzyga, czy winny jest serwer czy klient** — montaż ręczny
-z węzła, z pominięciem Kubernetesa:
-
-```bash
-ssh <węzeł> 'sudo mkdir -p /mnt/t && sudo mount -t nfs 192.168.1.34:/mnt/Tank1/astrololo-state /mnt/t \
-  && sudo touch /mnt/t/proba && echo SERWER-OK || echo SERWER-NIE; sudo umount /mnt/t'
-```
-
-`SERWER-OK` przy jednoczesnym `Permission denied` w podzie znaczy, że konfiguracja
-NAS-a jest dobra i **nie ma czego na nim poprawiać** — problem jest po stronie
-klienta.
-
-Osobno pamiętaj: sama zmiana konfiguracji udziału nie przeładowuje eksportów.
-Po każdej zmianie `midclt call service.restart nfs`.
-
----
-
 ## Odkręcenie
 
 ```bash

astrololo/README.md

@@ -23,15 +23,11 @@ Ten plik **celowo nie jest w `kustomization.yaml`**: resource stoi w ns `argocd`
 (poza namespace docelowym aplikacji), a to konfiguracja kontrolera, który wdraża tę
 aplikację — nakładamy go ręcznie, w repo trzymamy dla odtwarzalności i historii.
 
-## ⚠️ Udział `astrololo-state` — wymagany przez konta (PRE-27)
+## Pliki baz — udział otwarty na zapis (DAN-27)
 
-Pod `presentation` **nie wstanie bez niego** (`CreateContainerConfigError:
+Runbook: **[README-pliki.md](README-pliki.md)**. Ekran „Pliki" wymaga zapisu do
-failed to create subPath directory`). Osobny runbook:
+udziału z bazami, więc znosi gwarancję z DAN-25, że baz nie da się zmienić przez
-**[README-stan-prezentacji.md](README-stan-prezentacji.md)**.
+NFS. Co zostaje z zabezpieczeń i jak to wdrożyć — w runbooku.
-
-Krótko: udział z bazami jest wyeksportowany `ro` (DAN-25), więc konta nie mogą tam
-mieszkać — dostają własny, mały udział `/mnt/Tank1/astrololo-state`, zapisywalny,
-zawężony do tych samych węzłów.
 
 ## ⚠️ Sekret `astrololo-auth` — utwórz PRZED wdrożeniem
 

astrololo/data.yaml

@@ -44,12 +44,31 @@ spec:
             # zdążyłby wypuścić zapytanie jawnym tekstem, zanim dostanie odmowę.
             - name: LINK_ENCRYPTION_REQUIRED
               value: "true"
+            # Lustro baz w SQL (DAN-28). DSN w SEKRECIE, bo niesie hasło —
+            # w manifeście zostałoby w historii gita na zawsze.
+            #
+            # Sam adres nie przełącza jeszcze warstwy na SQL: o tym decyduje
+            # DATA_PROVIDER, które celowo zostaje na `excel`, dopóki lustro nie
+            # jest zaimplementowane i sprawdzone. Dzięki temu Postgres można
+            # wdrożyć i obejrzeć BEZ ryzyka dla działającego wyszukiwania.
+            - name: SQL_URL
+              valueFrom:
+                secretKeyRef: { name: astrololo-postgres, key: SQL_URL }
           volumeMounts:
             - name: cache
               mountPath: /app/.cache
+            # ZAPISYWALNY od DAN-27. Wcześniej read-only, bo warstwa danych tylko
+            # czytała bazy — teraz ekran „Pliki" pozwala je wgrywać, archiwizować
+            # i (dla administratora) kasować, a stan użycia jest KLIKANY, więc musi
+            # przetrwać restart poda.
+            #
+            # ŚWIADOMY KOSZT: znika jedna warstwa obrony w głąb. Przejęcie warstwy
+            # danych pozwala teraz nie tylko odczytać bazy, ale i je zmienić.
+            # Zostaje reszta: token międzywarstwowy, szyfrowane łącze, ograniczenie
+            # eksportu NFS do konkretnych hostów (DAN-25) i to, że kasować może
+            # wyłącznie konto administracyjne (PRE-27).
             - name: excel
               mountPath: /app/data_files
-              readOnly: true
           resources:
             requests: { cpu: "100m", memory: "256Mi" }
             limits:   { cpu: "500m", memory: "512Mi" }

astrololo/kustomization.yaml

@@ -2,6 +2,7 @@ apiVersion: kustomize.config.k8s.io/v1beta1
 kind: Kustomization
 resources:
   - namespace.yaml
+  - postgres.yaml # lustro baz Excela w SQL (DAN-28) — sekret astrololo-postgres POZA repo
   - data.yaml
   - logic.yaml
   - presentation.yaml
@@ -14,6 +15,6 @@ images:
   - name: gitea.czernobog.pl/gitea/astrololo-logic
     newTag: baf4e0e3
   - name: gitea.czernobog.pl/gitea/astrololo-render
-    newTag: aec3f843
+    newTag: latest
   - name: gitea.czernobog.pl/gitea/astrololo-presentation
     newTag: a8339659

astrololo/postgres.yaml

@@ -0,0 +1,150 @@
+# Postgres — lustro baz Excela w SQL (DAN-28).
+#
+# DLACZEGO POSTGRES, A NIE SQLITE. Nie ze względu na skalę: dzisiejszy zbiór to
+# ~54 tys. wierszy, przy których SQLite bywa szybszy. Powodem jest WYSZUKIWANIE
+# w nieznormalizowanym, polskim tekście — `pg_trgm` (dopasowanie rozmyte, literówki)
+# i `unaccent` (ogonki) nie mają w SQLite taniego zamiennika, a to jest główna
+# funkcja programu, nie dodatek. Drugi powód: `pg_advisory_lock` sprawia, że model
+# sesji z atomowym commitem przestaje zakładać „jedna replika na zawsze".
+#
+# TO LUSTRO, NIE ŹRÓDŁO PRAWDY. Źródłem są pliki Excela na NFS. Utrata tej bazy
+# NIE JEST utratą danych — odbudowuje się z plików. Dlatego kopie zapasowe są tu
+# OPCJONALNE, a wolumen może stać na local-path.
+---
+apiVersion: v1
+kind: PersistentVolumeClaim
+metadata:
+  name: postgres-data
+  namespace: astrololo
+spec:
+  accessModes: [ReadWriteOnce]
+  # local-path (domyślny provisioner k3s), NIE NFS. Postgres zakłada semantykę
+  # blokad i fsync, której NFS nie gwarantuje — to klasyczne źródło uszkodzenia
+  # bazy przy nagłym restarcie. Ceną jest przywiązanie do węzła; przy luście
+  # odtwarzalnym z Excela to akceptowalne.
+  storageClassName: local-path
+  resources:
+    requests:
+      storage: 5Gi
+---
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: postgres-init
+  namespace: astrololo
+data:
+  # UWAGA: skrypty z /docker-entrypoint-initdb.d/ uruchamiają się WYŁĄCZNIE przy
+  # pierwszej inicjalizacji, na pustym katalogu danych. Dopisanie tu rozszerzenia
+  # PO utworzeniu bazy nic nie zrobi — trzeba je wtedy założyć ręcznie (patrz
+  # README-postgres.md, sekcja „Dodanie rozszerzenia do istniejącej bazy").
+  01-extensions.sql: |
+    -- Dopasowanie rozmyte: similarity(), operator %, indeksy GIN po trigramach.
+    -- To jest powód, dla którego stoi tu Postgres, a nie SQLite.
+    CREATE EXTENSION IF NOT EXISTS pg_trgm;
+    -- Zdejmowanie ogonków: „różdżka" ma się znaleźć na „rozdzka".
+    CREATE EXTENSION IF NOT EXISTS unaccent;
+
+    -- Schemat na lustro. Osobny, żeby purge i odbudowa nie musiały ruszać
+    -- niczego w `public` i żeby `DROP SCHEMA mirror CASCADE` był bezpiecznym
+    -- „wyczyść wszystko i wczytaj od nowa".
+    CREATE SCHEMA IF NOT EXISTS mirror;
+
+    -- Rejestr luster: co, z jakiego pliku, o jakim skrócie i kiedy wczytane.
+    -- Zgodność pliku z tabelą poznajemy po sha256 — nazwa pliku nie wystarcza,
+    -- bo treść potrafi się zmienić bez zmiany nazwy.
+    CREATE TABLE IF NOT EXISTS mirror.registry (
+      table_name   text PRIMARY KEY,
+      source_path  text NOT NULL UNIQUE,
+      sha256       text NOT NULL,
+      row_count    integer NOT NULL DEFAULT 0,
+      loaded_at    timestamptz NOT NULL DEFAULT now(),
+      active       boolean NOT NULL DEFAULT false
+    );
+    CREATE INDEX IF NOT EXISTS registry_active_idx ON mirror.registry (active);
+---
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: postgres
+  namespace: astrololo
+spec:
+  replicas: 1
+  # Recreate, NIE RollingUpdate: wolumen jest ReadWriteOnce, a dwa procesy
+  # Postgresa na jednym katalogu danych to uszkodzona baza. Rolling próbowałby
+  # wstać z nowym podem, zanim stary zejdzie.
+  strategy:
+    type: Recreate
+  selector:
+    matchLabels: { app: postgres }
+  template:
+    metadata:
+      labels: { app: postgres }
+    spec:
+      containers:
+        - name: postgres
+          # Wersja PRZYPIĘTA i celowo poza image-updaterem: podbicie majora
+          # Postgresa wymaga migracji katalogu danych, więc nie może się zdarzyć
+          # samo, w nocy, przy okazji builda aplikacji.
+          image: postgres:17
+          ports: [{ containerPort: 5432, name: postgres }]
+          env:
+            - name: POSTGRES_DB
+              value: astrololo
+            - name: POSTGRES_USER
+              value: astrololo
+            - name: POSTGRES_PASSWORD
+              valueFrom:
+                secretKeyRef: { name: astrololo-postgres, key: POSTGRES_PASSWORD }
+            # PGDATA w PODKATALOGU montowanego wolumenu. Katalog główny wolumenu
+            # potrafi zawierać wpisy systemu plików (np. lost+found), a initdb
+            # odmawia inicjalizacji w niepustym katalogu.
+            - name: PGDATA
+              value: /var/lib/postgresql/data/pgdata
+            # C.UTF-8 zamiast pl_PL.UTF-8: dopasowanie tekstu robimy przez
+            # unaccent i pg_trgm, nie przez collation, a locale pl_PL wymagałoby
+            # obrazu z wygenerowanymi lokalizacjami. Gdyby kiedyś potrzebne było
+            # polskie SORTOWANIE, dokłada się collation ICU na konkretnej kolumnie.
+            - name: POSTGRES_INITDB_ARGS
+              value: "--encoding=UTF8 --locale=C.UTF-8"
+          volumeMounts:
+            - name: data
+              mountPath: /var/lib/postgresql/data
+            - name: init
+              mountPath: /docker-entrypoint-initdb.d
+              readOnly: true
+          # pg_isready, nie zwykły TCP: gniazdo słucha, zanim baza przyjmuje
+          # zapytania, więc sonda po porcie przepuściłaby ruch za wcześnie.
+          readinessProbe:
+            exec:
+              command: ["pg_isready", "-U", "astrololo", "-d", "astrololo", "-q"]
+            initialDelaySeconds: 5
+            periodSeconds: 5
+          livenessProbe:
+            exec:
+              command: ["pg_isready", "-U", "astrololo", "-d", "astrololo", "-q"]
+            initialDelaySeconds: 30
+            periodSeconds: 20
+            failureThreshold: 6
+          resources:
+            requests: { cpu: "100m", memory: "256Mi" }
+            limits:   { cpu: "1000m", memory: "1Gi" }
+      volumes:
+        - name: data
+          persistentVolumeClaim:
+            claimName: postgres-data
+        - name: init
+          configMap:
+            name: postgres-init
+---
+apiVersion: v1
+kind: Service
+metadata:
+  name: postgres
+  namespace: astrololo
+spec:
+  # ClusterIP i tylko ClusterIP. Baza nie ma żadnego powodu być widoczna poza
+  # klastrem; dostęp z zewnątrz robi się przez `kubectl port-forward` na czas
+  # jednej sesji (patrz README-postgres.md).
+  type: ClusterIP
+  selector: { app: postgres }
+  ports: [{ port: 5432, targetPort: 5432 }]