feat(astrololo): Postgres jako lustro baz w SQL + runbook (DAN-28)

Manifest, wpięcie w kustomization i runbook krok po kroku.

DECYZJE ZAPISANE W MANIFEŚCIE, ŻEBY NIE TRZEBA ICH BYŁO 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 akceptowalne.

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 wolumenu: katalog główny potrafi zawierać wpisy systemu
plików, a initdb odmawia pracy w niepustym katalogu.

Wersja PRZYPIĘTA i poza image-updaterem: podbicie majora wymaga migracji katalogu
danych, więc nie może się zdarzyć samo, w nocy, przy okazji builda aplikacji.

C.UTF-8 zamiast pl_PL.UTF-8: dopasowanie tekstu robimy przez unaccent i pg_trgm,
nie przez collation, a pl_PL wymagałby obrazu z wygenerowanymi lokalizacjami.

DATA_PROVIDER zostaje na `excel`. Postgres można wdrożyć i obejrzeć BEZ ryzyka
dla działającego wyszukiwania; przełączenie to osobna, późniejsza decyzja.

SPRAWDZONE PRZED ODDANIEM: `kubectl kustomize astrololo` składa komplet 21
zasobów bez błędu, YAML parsuje się poprawnie, audyt odwołań potwierdza, że
jedynym brakującym sekretem jest astrololo-postgres (oba klucze), a DSN
postgresql+psycopg:// jest rozpoznawany przez SQLAlchemy z psycopg 3.

NIE SPRAWDZONE: skrypt inicjalizujący nie biegł przeciwko prawdziwemu Postgresowi
— na maszynie, na której to powstawało, nie ma Dockera. Zapisane wprost
w runbooku; krok 4 jest tam prawdziwym testem.

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

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.md

@@ -8,6 +8,30 @@ Warstwy: `presentation` (wejście z przeglądarki przez **Ingress po https**)
 
 Adres aplikacji: **https://astrololo.czernobog.pl** — patrz [TLS](#-tls--wymagane-kroki-przed-wdrożeniem).
 
+## Co śledzi image-updater — [`image-updater.yaml`](image-updater.yaml)
+
+Lista obrazów podbijanych automatycznie jest **jawna** i żyje w CRD `ImageUpdater`
+(ns `argocd`). Obraz, którego na niej nie ma, **nigdy się nie podbije**, choćby CI
+go budowało — tak przez chwilę wisiał `render` na `:latest`, zanim dopisaliśmy go do
+listy. Dodając nową usługę, dopisz jej wpis w `image-updater.yaml` i nałóż:
+
+```bash
+kubectl apply -f astrololo/image-updater.yaml
+```
+
+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.
+
+## Postgres — lustro baz w SQL (DAN-28)
+
+Osobny runbook: **[README-postgres.md](README-postgres.md)** — co zrobiono w repo,
+co musisz zrobić ręcznie (sekret `astrololo-postgres`), jak sprawdzić rozszerzenia
+`pg_trgm`/`unaccent` i jak odtworzyć całość bez ArgoCD.
+
+Postgres trzyma LUSTRO plików Excela, nie źródło prawdy — jego utrata nie jest
+utratą danych, więc kopie zapasowe są opcjonalne.
+
 ## ⚠️ Sekret `astrololo-auth` — utwórz PRZED wdrożeniem
 
 Aplikacja wystawia treść **oryginalnych baz interpretacyjnych**, dlatego wymaga

astrololo/data.yaml

@@ -9,6 +9,10 @@ spec:
   template:
     metadata: { labels: { app: data } }
     spec:
+      # LOG-33: pody nie rozmawiają z API Kubernetesa, więc token konta
+      # serwisowego jest im niepotrzebny — a zamontowany byłby gotowym
+      # punktem wyjścia do klastra dla kogoś, kto przejmie kontener.
+      automountServiceAccountToken: false
       imagePullSecrets: [{ name: gitea-registry }]
       containers:
         - name: data
@@ -40,6 +44,16 @@ 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

astrololo/image-updater.yaml

@@ -0,0 +1,44 @@
+# Konfiguracja argocd-image-updater dla astrololo — ŹRÓDŁO PRAWDY tego, CO śledzimy.
+#
+# Model v1.x: osobny CRD `ImageUpdater` w ns `argocd` (nie adnotacje na Application).
+# Lista `images` jest JAWNA — obraz, którego tu NIE MA, nigdy nie zostanie podbity,
+# choćby CI go budowało. Tak przez chwilę wisiał `render` na `:latest` (PRE-24):
+# usługa istniała i budowała tag SHA, ale updater jej nie znał, więc kustomization
+# jej nie ruszał. Dopisanie wpisu = wejście usługi do rotacji.
+#
+# ⚠️ TEGO PLIKU NIE MA w astrololo/kustomization.yaml i NIE MA GO TAM MIEĆ:
+#   1. resource żyje w ns `argocd`, a Application astrololo celuje w ns `astrololo`
+#      — auto-sync przez kustomize próbowałby zapisać poza swój namespace docelowy;
+#   2. to konfiguracja kontrolera, który wdraża tę właśnie aplikację — niech app
+#      nie zarządza narzędziem, które ją wdraża.
+# Plik jest trzymany w repo dla odtwarzalności i historii; nakłada się go RĘCZNIE:
+#   kubectl apply -f astrololo/image-updater.yaml
+#
+# Strategia `newest-build`: updater bierze obraz o NAJNOWSZYM znaczniku czasu builda
+# i zapisuje jego tag SHA do kustomization (write-back git). Uwaga na reprodukowalne
+# buildy — identyczny `created` na kilku tagach potrafi zablokować wybór najnowszego.
+apiVersion: argocd-image-updater.argoproj.io/v1alpha1
+kind: ImageUpdater
+metadata:
+  name: astrololo
+  namespace: argocd
+spec:
+  applicationRefs:
+    - namePattern: astrololo
+      images:
+        - alias: data
+          imageName: gitea.czernobog.pl/gitea/astrololo-data
+        - alias: logic
+          imageName: gitea.czernobog.pl/gitea/astrololo-logic
+        - alias: presentation
+          imageName: gitea.czernobog.pl/gitea/astrololo-presentation
+        - alias: render
+          imageName: gitea.czernobog.pl/gitea/astrololo-render
+  commonUpdateSettings:
+    updateStrategy: newest-build
+  writeBackConfig:
+    method: git:secret:argocd/git-creds
+    gitConfig:
+      repository: https://gitea.czernobog.pl/gitea/deploy.git
+      branch: master
+      writeBackTarget: kustomization:/astrololo

astrololo/kustomization.yaml

@@ -2,15 +2,19 @@ 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
-  - tls.yaml                # certyfikat z własnego CA (wymaga cert-managera)
-  - ingress.yaml            # wejście po https + przekierowanie z http
+  - render.yaml # składanie raportu PDF (PRE-24), osobny obraz z TeX Live
+  - tls.yaml # certyfikat z własnego CA (wymaga cert-managera)
+  - ingress.yaml # wejście po https + przekierowanie z http
 images:
   - name: gitea.czernobog.pl/gitea/astrololo-data
-    newTag: 877ec91f
+    newTag: baf4e0e3
   - name: gitea.czernobog.pl/gitea/astrololo-logic
-    newTag: 163ace42
+    newTag: baf4e0e3
+  - name: gitea.czernobog.pl/gitea/astrololo-render
+    newTag: aec3f843
   - name: gitea.czernobog.pl/gitea/astrololo-presentation
-    newTag: 163ace42
+    newTag: a8339659

astrololo/logic.yaml

@@ -9,6 +9,10 @@ spec:
   template:
     metadata: { labels: { app: logic } }
     spec:
+      # LOG-33: pody nie rozmawiają z API Kubernetesa, więc token konta
+      # serwisowego jest im niepotrzebny — a zamontowany byłby gotowym
+      # punktem wyjścia do klastra dla kogoś, kto przejmie kontener.
+      automountServiceAccountToken: false
       imagePullSecrets: [{ name: gitea-registry }]
       containers:
         - name: logic

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 }]

astrololo/presentation.yaml

@@ -9,6 +9,10 @@ spec:
   template:
     metadata: { labels: { app: presentation } }
     spec:
+      # LOG-33: pody nie rozmawiają z API Kubernetesa, więc token konta
+      # serwisowego jest im niepotrzebny — a zamontowany byłby gotowym
+      # punktem wyjścia do klastra dla kogoś, kto przejmie kontener.
+      automountServiceAccountToken: false
       imagePullSecrets: [{ name: gitea-registry }]
       containers:
         - name: presentation
@@ -46,11 +50,36 @@ spec:
             # Bez klucza usługa ma NIE wstać, a klient ma nie wysłać niczego.
             # Sam serwer broni się fail-closed, ale to za mało: klient bez klucza
             # zdążyłby wypuścić zapytanie jawnym tekstem, zanim dostanie odmowę.
+            # Usługa składająca PDF (PRE-24) — osobny komponent.
+            - name: RENDER_URL
+              value: "http://render:8004"        # discovery po nazwie Service
+            # Trzeci klucz łącza: prezentacja ↔ render. Osobny, bo tym łączem
+            # idzie CAŁY raport (dane urodzeniowe + opisy z baz).
+            - name: LINK_KEY_PRESENTATION_RENDER
+              valueFrom:
+                secretKeyRef: { name: astrololo-link, key: LINK_KEY_PRESENTATION_RENDER }
             - name: LINK_ENCRYPTION_REQUIRED
               value: "true"
+            # Konta zakładane z ekranu „Konta" (PRE-26). Konto administracyjne
+            # zostaje w APP_USER/APP_PASSWORD powyżej — celowo, bo dzięki temu
+            # NIE DA SIĘ go skasować ani ograniczyć z aplikacji.
+            - name: ACCOUNTS_FILE
+              value: "/app/state/accounts.json"
+          volumeMounts:
+            # subPath, NIE cały udział: prezentacja dostaje wyłącznie własny
+            # podkatalog i nie widzi baz interpretacyjnych. Zamontowanie tu całego
+            # /mnt/Tank1/astrololo obeszłoby bokiem zamknięcie dostępu z DAN-25.
+            - name: state
+              mountPath: /app/state
+              subPath: presentation-state
           resources:
             requests: { cpu: "100m", memory: "128Mi" }
             limits:   { cpu: "300m", memory: "256Mi" }
+      volumes:
+        - name: state
+          nfs:
+            server: 192.168.1.34
+            path: /mnt/Tank1/astrololo
 ---
 apiVersion: v1
 kind: Service

astrololo/render.yaml

@@ -0,0 +1,73 @@
+# Usługa render — składanie raportu PDF (PRE-24).
+#
+# OSOBNY komponent, nie część prezentacji, z tego samego powodu co silnik
+# swisseph (LOG-27): obraz dźwiga TeX Live, czyli setki megabajtów. W obrazie
+# produktu spowalniałby każdy build i deploy; tak aktualizuje się niezależnie,
+# a jego awaria nie kładzie aplikacji — psuje się tylko przycisk „Pobierz PDF".
+#
+# Rozmawia WYŁĄCZNIE z prezentacją, po szyfrowanym łączu z własnym, trzecim
+# kluczem. Wystawiona jako ClusterIP — bez NodePort i bez Ingressu, bo nie ma
+# powodu, żeby ktokolwiek sięgał do niej z zewnątrz.
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: render
+  namespace: astrololo
+spec:
+  replicas: 1
+  selector: { matchLabels: { app: render } }
+  template:
+    metadata: { labels: { app: render } }
+    spec:
+      # LOG-33: pody nie rozmawiają z API Kubernetesa, więc token konta
+      # serwisowego jest im niepotrzebny — a zamontowany byłby gotowym
+      # punktem wyjścia do klastra dla kogoś, kto przejmie kontener.
+      automountServiceAccountToken: false
+      imagePullSecrets: [{ name: gitea-registry }]
+      containers:
+        - name: render
+          image: gitea.czernobog.pl/gitea/astrololo-render:latest
+          ports: [{ containerPort: 8004 }]
+          env:
+            # Token międzywarstwowy (LOG-32) — ta usługa dostaje CAŁY raport:
+            # dane urodzeniowe i opisy z baz.
+            - name: INTERNAL_TOKEN
+              valueFrom:
+                secretKeyRef: { name: astrololo-auth, key: INTERNAL_TOKEN }
+            # Szyfrowanie łącza (PRE-16/PRE-24). OSOBNY klucz na parę rozmówców:
+            # przejęcie klucza renderu nie może otwierać łącza do logiki ani danych.
+            - name: LINK_KEY_PRESENTATION_RENDER
+              valueFrom:
+                secretKeyRef: { name: astrololo-link, key: LINK_KEY_PRESENTATION_RENDER }
+            - name: LINK_ENCRYPTION_REQUIRED
+              value: "true"
+          # XeLaTeX na obszernym raporcie potrafi zjeść sporo pamięci i CPU,
+          # ale tylko na chwilę — stąd wyraźna różnica między request a limit.
+          resources:
+            requests: { cpu: "100m", memory: "256Mi" }
+            limits:   { cpu: "1500m", memory: "1Gi" }
+          # Kompilacja pisze wyłącznie do katalogu tymczasowego, który sprząta po
+          # sobie. Dajemy na to emptyDir i zamykamy resztę systemu plików —
+          # raport nie ma prawa zostawić śladu w kontenerze.
+          volumeMounts:
+            - { name: tmp, mountPath: /tmp }
+          securityContext:
+            readOnlyRootFilesystem: true
+            allowPrivilegeEscalation: false
+          readinessProbe:
+            httpGet: { path: /health, port: 8004 }
+            initialDelaySeconds: 5
+            periodSeconds: 15
+      volumes:
+        - name: tmp
+          emptyDir: { sizeLimit: 512Mi }
+---
+apiVersion: v1
+kind: Service
+metadata:
+  name: render
+  namespace: astrololo
+spec:
+  type: ClusterIP            # tylko dla prezentacji, bez wejścia z zewnątrz
+  selector: { app: render }
+  ports: [{ port: 8004, targetPort: 8004 }]

conjurer/DEPLOY-BOT.md

@@ -0,0 +1,106 @@
+# Production ("deploy") Conjurer bot
+
+A second Conjurer bot that runs **alongside** the test `bot` in the `conjurer`
+namespace, sharing the same librarian / musician / radio and the shared
+`CONJURER_API_KEY`. It differs from the test bot only in:
+
+- its Discord token: the **`deploy-conjurer-netrc`** secret (already created),
+- distinct names/labels (`deploy-bot`) and NodePort **32443**,
+- **`/data` on NFS (RWX)** instead of a block PVC — so you can seed/upload files
+  while it runs and back it up concurrently.
+
+Files: `deploy-bot.yaml` (Deployment + Service), `deploy-bot-backup.yaml`
+(daily backup CronJob). Both are wired into `kustomization.yaml`.
+
+## Update channel — only on `[deploy]`
+
+Unlike the test bot (which tracks every build), the production bot updates **only
+when you promote a version**. It runs a **separate image**,
+`conjurer-bot-deploy`, which the conjurer CI tags **only when the commit message
+contains `[deploy]`** (it re-tags the already-built `conjurer-bot:<sha>` — same
+bytes). The image-updater's `deploy-bot` alias then bumps this bot's tag.
+
+So: normal commits update the test bot + librarian; a commit with `[deploy]` in
+its message is the one that also rolls the production bot.
+
+**Already bootstrapped:** the channel was seeded by the first `[deploy]` commit
+(the merge of conjurer#20), which promoted `conjurer-bot-deploy:fbd1ec9f` — the
+tag pinned in `kustomization.yaml`. From here the image-updater keeps it current
+on each future `[deploy]` commit. Note the librarian is shared and still tracks
+latest, so mind large bot⇄librarian version skews.
+
+If you ever need to seed a tag by hand:
+```bash
+docker pull gitea.czernobog.pl/gitea/conjurer-bot:<sha>
+docker tag  gitea.czernobog.pl/gitea/conjurer-bot:<sha> \
+            gitea.czernobog.pl/gitea/conjurer-bot-deploy:<sha>
+docker push gitea.czernobog.pl/gitea/conjurer-bot-deploy:<sha>
+```
+
+## One-time setup
+
+1. **Secret** — already exists as `deploy-conjurer-netrc` (a netrc carrying the
+   deploy Discord token, key `.netrc`). Nothing to do; the Deployment mounts it
+   at `/secrets/.netrc`.
+
+2. **NFS export** — create the data + backup dirs on the NFS server
+   (`192.168.1.34`, adjust to your real export):
+   ```
+   /mnt/Tank1/conjurer_swap/deploy-bot/data
+   /mnt/Tank1/conjurer_swap/deploy-bot/backups
+   ```
+
+## Seeding / uploading config & state into /data
+
+Because `/data` is a plain NFS export, you upload files by copying them onto the
+share — **no `kubectl cp`, no scaling the bot down**. From the PVE box that holds
+`/srv/data` (mount the same export there, or rsync over it):
+
+```bash
+# on a host that can see the NFS export:
+rsync -a /srv/data/ 192.168.1.34:/mnt/Tank1/conjurer_swap/deploy-bot/data/
+```
+
+The bot roots everything under `CONJURER_DATA_DIR=/data`, so these land where it
+expects them:
+
+```
+accident_log.json  Conjurer_graphics/  music/  pamiec.json
+pamiec_muzyki.json  settings.json  system_gpt_settings.json  transcripts/
+```
+
+Upload as much or as little as you like — the bot seeds any missing JSON on
+first run. Live-editing `pamiec.json` while the bot writes to it can race; prefer
+seeding before first start or during a brief `kubectl -n conjurer scale
+deploy/deploy-bot --replicas=0` window.
+
+## Backups (production only)
+
+`deploy-bot-backup` runs daily (04:17) and writes to the `backups` export:
+
+- `current/` — a full rsync mirror of `/data` (incl. music/graphics), always
+  the latest state,
+- `snapshots/deploy-state-<date>.tgz` — dated archives of the critical small
+  state (both memories, settings, accident log, transcripts), kept
+  `RETENTION_DAYS` (30) days.
+
+The test bot is deliberately **not** backed up (amnesia there is fine).
+
+Restore example:
+```bash
+tar xzf snapshots/deploy-state-2026-08-03-0417.tgz -C /mnt/.../deploy-bot/data/
+```
+
+## Routing librarian / musician callbacks
+
+**Librarian — handled automatically.** Each bot advertises its own
+`CONJURER_SELF_CALLBACK` (test `…:32442`, this bot `…:32443`) on every query and
+ping, and the librarian answers each result/pong back to the bot that asked. One
+librarian serves both bots — no `CONJURER_MAIN_BOT` repointing needed. (The
+librarian keeps `CONJURER_MAIN_BOT: http://bot:5000` only as a fallback for a bot
+that doesn't send a callback.)
+
+**Musician — still single-target.** The musician pushes "now playing" events to
+its one `CONJURER_MAIN_BOT` (currently the test bot, `192.168.1.73:32442`). Only
+one bot gets radio events; repoint the musician's `CONJURER_MAIN_BOT` to
+`192.168.1.73:32443` if the production bot should show them instead.

conjurer/bot.yaml

@@ -0,0 +1,62 @@
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: bot
+  namespace: conjurer
+spec:
+  replicas: 1                     # NIGDY więcej — jedna sesja gateway na token
+  strategy: { type: Recreate }    # NIE RollingUpdate — dwa pody = wojna o sesję Discord
+  selector: { matchLabels: { app: bot } }
+  template:
+    metadata: { labels: { app: bot } }
+    spec:
+      imagePullSecrets: [{ name: gitea-registry }]
+      containers:
+        - name: bot
+          image: gitea.czernobog.pl/gitea/conjurer-bot:c8aae106
+          ports: [{ containerPort: 5000 }]
+          env:
+            - { name: CONJURER_DATA_DIR,      value: "/data" }
+            - { name: CONJURER_DISCORD_HOST,  value: "0.0.0.0" }
+            - { name: CONJURER_DISCORD_PORT,  value: "5000" }
+            - { name: CONJURER_API_KEY,  value: "d97008b3-7a5a-11f1-acd1-000b0e0f00ed" }
+            - { name: CONJURER_NETRC_FILE, value: "/secrets/.netrc" }
+            # ↓ NAZWY PODSTAW WG WYNIKU grepa z 0.2 ↓
+            - { name: CONJURER_LIBRARIAN_SERVICE, value: "http://librarian:5001" }
+            - { name: CONJURER_MUSICIAN_SERVICE,  value: "http://192.168.1.89:5000" }
+            - { name: CONJURER_RADIO_SERVICE,     value: "http://192.168.1.79:5005" }
+            - { name: CONJURER_FILE_SERVICE,     value: "http://192.168.1.89:5000" }
+
+            - { name: CONJURER_RADIO_HARBOR,      value: "http://192.168.1.79:54321" }
+            # Where the librarian sends THIS bot's results/pongs back to (its own
+            # NodePort). Lets one librarian serve both bots - see deploy-bot.yaml.
+            - { name: CONJURER_SELF_CALLBACK,     value: "http://192.168.1.73:32442" }
+          volumeMounts:
+            - { name: data,  mountPath: /data }
+            - { name: netrc, mountPath: /secrets, readOnly: true }
+          resources:
+            requests: { cpu: "200m", memory: "256Mi" }
+            limits:   { cpu: "2",    memory: "1Gi" }
+      volumes:
+        - name: data
+          persistentVolumeClaim: { claimName: bot-data }
+        - name: netrc
+          secret: { secretName: conjurer-netrc }
+---
+apiVersion: v1
+kind: PersistentVolumeClaim
+metadata: { name: bot-data, namespace: conjurer }
+spec:
+  accessModes: [ReadWriteOnce]
+  resources: { requests: { storage: 2Gi } }
+---
+apiVersion: v1
+kind: Service
+metadata: { name: bot, namespace: conjurer }
+spec:
+  type: NodePort                  # radio/musician z Dockera muszą go dosięgnąć
+  selector: { app: bot }
+  # nodePort PRZYPIĘTY na sztywno. Bez tego k8s losuje port z 30000-32767 przy
+  # (od)tworzeniu Service, a musician/betoniarka z Dockera adresują bota po
+  # http://192.168.1.73:32442 na sztywno - rozjazd = wyniki/eventy giną w locie.
+  ports: [{ port: 5000, targetPort: 5000, nodePort: 32442 }]

conjurer/conjurer-imageupdater.yaml

@@ -0,0 +1,22 @@
+apiVersion: argocd-image-updater.argoproj.io/v1alpha1
+kind: ImageUpdater
+metadata:
+  name: conjurer
+  namespace: argocd
+spec:
+  commonUpdateSettings:
+    updateStrategy: "newest-build"
+  writeBackConfig:
+    method: "git:secret:argocd/git-creds"
+    gitConfig:
+      repository: "https://gitea.czernobog.pl/gitea/deploy.git"
+      branch: "master"                       # ← gałąź repo deploy
+      writeBackTarget: "kustomization:/conjurer"
+  applicationRefs:
+    - namePattern: "conjurer"
+      images:
+        - { alias: "librarian",  imageName: "gitea.czernobog.pl/gitea/conjurer-librarian" }
+        - { alias: "bot",        imageName: "gitea.czernobog.pl/gitea/conjurer-bot" }
+        # Production bot tracks its own image, which only gets new tags on
+        # [deploy] commits (conjurer CI) - so it updates only on promoted builds.
+        - { alias: "deploy-bot", imageName: "gitea.czernobog.pl/gitea/conjurer-bot-deploy" }

conjurer/deploy-bot-backup.yaml

@@ -0,0 +1,65 @@
+# Daily backup of the PRODUCTION ("deploy") bot's /data.
+#
+# Only production is backed up - the test bot's amnesia is fine, this bot's is
+# not (pamiec.json / pamiec_muzyki.json are the conversation & music memory).
+# Both volumes are NFS (RWX), so this runs while the bot is live - no RWO clash.
+#
+# Two-part backup:
+#   * a full, space-efficient MIRROR (rsync --delete) of everything, incl. music
+#     and graphics - always the current state,
+#   * dated SNAPSHOTS of just the small critical state (the memories, settings,
+#     accident log, transcripts) so you can roll back to a point in time.
+# Snapshots older than RETENTION_DAYS are pruned.
+apiVersion: batch/v1
+kind: CronJob
+metadata:
+  name: deploy-bot-backup
+  namespace: conjurer
+spec:
+  schedule: "17 4 * * *"          # every day at 04:17
+  concurrencyPolicy: Forbid
+  successfulJobsHistoryLimit: 3
+  failedJobsHistoryLimit: 3
+  jobTemplate:
+    spec:
+      backoffLimit: 2
+      template:
+        spec:
+          restartPolicy: Never
+          containers:
+            - name: backup
+              image: alpine:3.20
+              command: ["/bin/sh", "-c"]
+              args:
+                - |
+                  set -eu
+                  apk add --no-cache rsync >/dev/null
+                  STAMP="$(date +%F-%H%M)"
+                  mkdir -p /backup/current /backup/snapshots
+                  echo "[$STAMP] mirroring /data -> /backup/current"
+                  rsync -a --delete /data/ /backup/current/
+                  echo "[$STAMP] snapshotting critical state"
+                  tar czf "/backup/snapshots/deploy-state-$STAMP.tgz" -C /data \
+                      accident_log.json pamiec.json pamiec_muzyki.json \
+                      settings.json system_gpt_settings.json transcripts \
+                      2>/dev/null || echo "  (some files absent - skipped)"
+                  echo "[$STAMP] pruning snapshots older than ${RETENTION_DAYS}d"
+                  find /backup/snapshots -name 'deploy-state-*.tgz' -type f \
+                      -mtime +"${RETENTION_DAYS}" -delete
+                  echo "[$STAMP] backup done"
+              env:
+                - { name: RETENTION_DAYS, value: "30" }
+              volumeMounts:
+                - { name: data,   mountPath: /data,   readOnly: true }
+                - { name: backup, mountPath: /backup }
+          volumes:
+            # Same export the bot mounts (read-only here).
+            - name: data
+              nfs:
+                server: 192.168.1.34
+                path: /mnt/Tank1/conjurer_swap/deploy-bot/data
+            # Backup target - ADJUST to your export.
+            - name: backup
+              nfs:
+                server: 192.168.1.34
+                path: /mnt/Tank1/conjurer_swap/deploy-bot/backups

conjurer/deploy-bot.yaml

@@ -0,0 +1,80 @@
+# Production ("deploy") Conjurer bot.
+#
+# Same infrastructure as the test `bot` (shares librarian / musician / radio and
+# the CONJURER_API_KEY), with three deliberate differences:
+#   1. its Discord token comes from the `deploy-conjurer-netrc` secret,
+#   2. distinct names/labels so it coexists with the test bot in this namespace,
+#   3. /data is an NFS volume (RWX) instead of a block PVC - so config/state can
+#      be uploaded while the bot runs (just copy onto the share) and backed up
+#      concurrently (see deploy-bot-backup.yaml). The test bot keeps its RWO PVC.
+#
+# ┌─ IMPORTANT: librarian & musician call ONE bot back ─────────────────────────┐
+# │ The librarian (CONJURER_MAIN_BOT) and musician push search results and      │
+# │ "now playing" events to a SINGLE bot address - currently the test bot's     │
+# │ NodePort 192.168.1.73:32442. Only one bot can receive them. To make the     │
+# │ PRODUCTION bot the one that gets librarian results / radio events, repoint   │
+# │ those services' CONJURER_MAIN_BOT to this bot's NodePort (…:32443 below).    │
+# └─────────────────────────────────────────────────────────────────────────────┘
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: deploy-bot
+  namespace: conjurer
+spec:
+  replicas: 1                     # NIGDY więcej — jedna sesja gateway na token
+  strategy: { type: Recreate }    # NIE RollingUpdate — dwa pody = wojna o sesję Discord
+  selector: { matchLabels: { app: deploy-bot } }
+  template:
+    metadata: { labels: { app: deploy-bot } }
+    spec:
+      imagePullSecrets: [{ name: gitea-registry }]
+      containers:
+        - name: bot
+          # SEPARATE image from the test bot: conjurer-bot-deploy only gets a new
+          # tag when a commit message contains [deploy] (see the conjurer CI), so
+          # this bot updates only on versions you explicitly promote. Tag is
+          # managed by the image-updater (kustomization images:).
+          image: gitea.czernobog.pl/gitea/conjurer-bot-deploy:c8aae106
+          ports: [{ containerPort: 5000 }]
+          env:
+            - { name: CONJURER_DATA_DIR,      value: "/data" }
+            - { name: CONJURER_DISCORD_HOST,  value: "0.0.0.0" }
+            - { name: CONJURER_DISCORD_PORT,  value: "5000" }
+            - { name: CONJURER_API_KEY,  value: "d97008b3-7a5a-11f1-acd1-000b0e0f00ed" }
+            - { name: CONJURER_NETRC_FILE, value: "/secrets/.netrc" }
+            - { name: CONJURER_LIBRARIAN_SERVICE, value: "http://librarian:5001" }
+            - { name: CONJURER_MUSICIAN_SERVICE,  value: "http://192.168.1.89:5000" }
+            - { name: CONJURER_RADIO_SERVICE,     value: "http://192.168.1.79:5005" }
+            - { name: CONJURER_FILE_SERVICE,      value: "http://192.168.1.89:5000" }
+            - { name: CONJURER_RADIO_HARBOR,      value: "http://192.168.1.79:54321" }
+            # This bot's own callback (its NodePort). The librarian records it per
+            # query and answers results/pongs HERE - so it serves this bot AND the
+            # test bot from one instance, no CONJURER_MAIN_BOT repointing needed.
+            - { name: CONJURER_SELF_CALLBACK,     value: "http://192.168.1.73:32443" }
+          volumeMounts:
+            - { name: data,  mountPath: /data }
+            - { name: netrc, mountPath: /secrets, readOnly: true }
+          resources:
+            requests: { cpu: "200m", memory: "256Mi" }
+            limits:   { cpu: "2",    memory: "1Gi" }
+      volumes:
+        # /data on NFS (RWX): lets you seed/upload files while the bot runs (copy
+        # straight onto the export from the PVE box that holds /srv/data) and lets
+        # the backup CronJob read it concurrently. ADJUST server/path to your
+        # actual export - mirrors the librarian's 192.168.1.34 Tank1 layout.
+        - name: data
+          nfs:
+            server: 192.168.1.34
+            path: /mnt/Tank1/conjurer_swap/deploy-bot/data
+        - name: netrc
+          secret: { secretName: deploy-conjurer-netrc }
+---
+apiVersion: v1
+kind: Service
+metadata: { name: deploy-bot, namespace: conjurer }
+spec:
+  type: NodePort                  # so librarian/musician COULD reach it if repointed
+  selector: { app: deploy-bot }
+  # Distinct pinned nodePort (test bot owns 32442). Point librarian/musician
+  # CONJURER_MAIN_BOT at 192.168.1.73:32443 to route their callbacks here.
+  ports: [{ port: 5000, targetPort: 5000, nodePort: 32443 }]

conjurer/kustomization.yaml

@@ -0,0 +1,19 @@
+apiVersion: kustomize.config.k8s.io/v1beta1
+kind: Kustomization
+resources:
+  - namespace.yaml
+  - librarian.yaml
+  - bot.yaml
+  - deploy-bot.yaml
+  - deploy-bot-backup.yaml
+images:
+  - name: gitea.czernobog.pl/gitea/conjurer-librarian
+    newTag: ae1bd677
+  - name: gitea.czernobog.pl/gitea/conjurer-bot
+    newTag: fbd1ec9f
+  # Production bot channel - only bumped when a [deploy]-tagged build appears.
+  # Bootstrapped to fbd1ec9f: that's the image the first [deploy] build (merge
+  # of conjurer#20) promoted to conjurer-bot-deploy. From here the image-updater
+  # keeps it current across future [deploy] commits.
+  - name: gitea.czernobog.pl/gitea/conjurer-bot-deploy
+    newTag: fbd1ec9f

conjurer/librarian.yaml

@@ -0,0 +1,67 @@
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: librarian
+  namespace: conjurer
+spec:
+  replicas: 1
+  selector: { matchLabels: { app: librarian } }
+  template:
+    metadata: { labels: { app: librarian } }
+    spec:
+      imagePullSecrets: [{ name: gitea-registry }]
+      # On SIGTERM the librarian checkpoints the running search and exits within
+      # CONJURER_LIBRARIAN_GRACEFUL_TIMEOUT (default 45s). Give k8s enough grace
+      # to let that finish before it SIGKILLs - otherwise a long scan's checkpoint
+      # is cut short and the search restarts from scratch instead of resuming.
+      terminationGracePeriodSeconds: 60
+      containers:
+        - name: librarian
+          image: gitea.czernobog.pl/gitea/conjurer-librarian:e243777e
+          ports: [{ containerPort: 5001 }]
+          env:
+            - { name: CONJURER_LIBRARIAN_HOST,      value: "0.0.0.0" }
+            - { name: CONJURER_LIBRARIAN_PORT,      value: "5001" }
+            - { name: CONJURER_LIBRARIAN_DB_PATH,   value: "/doi/" }
+            - { name: CONJURER_API_KEY,  value: "d97008b3-7a5a-11f1-acd1-000b0e0f00ed" }
+            - { name: CONJURER_LIBRARIAN_MAXTHREADS,  value: "40" }
+            - { name: CONJURER_CROSSREF_MAILTO,  value: "mtuszowski@gmail.com" }
+            - { name: CONJURER_LIBRARIAN_CHUNK,  value: "_chunk.txt" }
+            # Librarian jest W TYM SAMYM klastrze/namespace co bot - gada z nim
+            # po DNS Service'u, nie przez nodePort węzła (ten zostaje tylko dla
+            # zewnętrznych musician/betoniarka z Dockera). Odporne na przetasowania.
+            - { name: CONJURER_MAIN_BOT,  value: "http://bot:5000" }
+
+            - { name: CONJURER_LIBRARIAN_STATE_DIR, value: "/lib_temp_files" }
+
+          volumeMounts:
+            - { name: doi,   mountPath: /doi, readOnly: true }
+            - { name: state, mountPath: /lib_temp_files }
+          resources:
+            requests: { cpu: "100m", memory: "512Mi" }
+            # Headroom bump: the work-queue OOM is fixed in code, but a deep
+            # search still pulls up to 15000 Crossref records into RAM and the
+            # accumulating result JSONs are loaded whole. 2Gi gives margin so a
+            # big search isn't OOM-killed. Tune down if the node is tight.
+            limits:   { cpu: "1",    memory: "2Gi" }
+      volumes:
+        - name: doi
+          nfs:
+            server: 192.168.1.34
+            path: /mnt/Tank1/conjurer_swap/librarian_data/base_it1
+        - name: state
+          persistentVolumeClaim: { claimName: librarian-state }
+---
+apiVersion: v1
+kind: PersistentVolumeClaim
+metadata: { name: librarian-state, namespace: conjurer }
+spec:
+  accessModes: [ReadWriteOnce]
+  resources: { requests: { storage: 1Gi } }
+---
+apiVersion: v1
+kind: Service
+metadata: { name: librarian, namespace: conjurer }
+spec:
+  selector: { app: librarian }
+  ports: [{ port: 5001, targetPort: 5001 }]

conjurer/namespace.yaml

@@ -0,0 +1,4 @@
+apiVersion: v1
+kind: Namespace
+metadata:
+  name: conjurer