docs(nfs): po zmianie eksportu rollout restart nie wystarcza

Najdroższy czasowo moment pierwszego wdrożenia, więc zapisany wprost. FAKT: eksport poprawiony (mapall_user), usługa NFS zrestartowana, pod zrestartowany przez `rollout restart` — a zapis z poda nadal odbijał się o Permission denied. Jednocześnie ręczne zamontowanie TEGO SAMEGO eksportu z TEGO SAMEGO węzła pozwalało pisać. HIPOTEZA (niepotwierdzona 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. `rollout restart` zostawia stary i nowy pod na chwilę współistniejące — widać to w jego własnym logu jako „1 old replicas are pending termination" — więc montowanie ani na moment nie zostaje bez użytkownika i nowy pod dziedziczy odpowiedź sprzed zmiany. ROZWIĄZANIE (zweryfikowane): zejść do zera replik, poczekać na zniknięcie podów, wrócić do jednej. W ArgoCD ten sam skutek daje force delete poda. Dopisany też test rozdzielający winę serwera od winy klienta: ręczny montaż z węzła z pominięciem Kubernetesa. SERWER-OK przy jednoczesnej odmowie w podzie znaczy, że na NAS-ie nie ma czego poprawiać — i oszczędza rundy zmian w konfiguracji udziału, które niczego nie dają. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
docs(nfs): prawa do udziału opisane zgodnie z tym, co jest naprawdę
2026-08-09 11:53:14 +02:00 · 2026-08-09 11:43:54 +02:00 · 2026-08-07 18:48:44 +02:00 · 2026-08-07 17:46:12 +02:00 · 2026-08-07 13:55:15 +00:00 · 2026-08-07 12:17:39 +00:00
18 changed files with 1201 additions and 11 deletions
@@ -0,0 +1,279 @@
+# Udział na stan prezentacji — `astrololo-state`
+
+Potrzebny do kont zakładanych z ekranu „Konta" (PRE-27). **Bez niego pod
+`presentation` nie wstanie.**
+
+---
+
+## Dlaczego osobny udział, a nie podkatalog
+
+Pierwsza wersja montowała `/mnt/Tank1/astrololo` z `subPath: presentation-state`
+i pod stanął w `CreateContainerConfigError`:
+
+```
+failed to create subPath directory for volumeMount "state" of container "presentation"
+```
+
+Przyczyna była podwójna i za każdym razem ta sama: udział z bazami jest
+wyeksportowany **`ro: true` z `root_squash`** (patrz runbook DAN-25 w repo
+aplikacji). Zatem:
+
+1. kubelet nie mógł utworzyć podkatalogu — bo udział jest tylko do odczytu,
+2. a gdyby nawet mógł, aplikacja i tak nie zapisałaby tam pliku kont.
+
+**Osobny udział rozwiązuje to bez ruszania DAN-25.** Udział z bazami zostaje tylko
+do odczytu; konta dostają własne, małe miejsce. Przy okazji znika `subPath`, czyli
+znika potrzeba, żeby kubelet cokolwiek zakładał — katalog istnieje, bo jest
+korzeniem udziału.
+
+---
+
+## Krok 1 — dataset i udział na TrueNAS
+
+Po SSH na NAS (192.168.1.34). Konwencja jak w DAN-25: **nie edytujemy
+`/etc/exports` ręcznie**, tylko przez `midclt`.
+
+```bash
+# dataset
+sudo zfs create Tank1/astrololo-state
+```
+
+Jeśli `Tank1` nie jest pulą ZFS albo wolisz zwykły katalog:
+
+```bash
+sudo mkdir -p /mnt/Tank1/astrololo-state
+```
+
+### Właściciel i prawa — TU JEST NAJCZĘSTSZY BŁĄD
+
+Kontenery aplikacji działają **jako root** (`uid=0`), a NFS domyślnie stosuje
+**`root_squash`**: root z klienta NIE jest rootem na udziale — ląduje jako
+`nobody`. Świeży dataset ma prawa `drwxrwx--- root root`, czyli **nic dla
+„innych"** — i dlatego zapis odbija się o `Permission denied`, mimo że `ls`
+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
+sudo chmod 770 /mnt/Tank1/astrololo-state
+```
+
+i przy eksporcie podstawiasz go w `mapall_user`. Efekt ten sam, bez oddawania
+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_group": "root"
+}'
+```
+
+**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 |
+
+> 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:
+
+```bash
+ssh 192.168.1.73 'sudo mount -t nfs 192.168.1.34:/mnt/Tank1/astrololo-state /mnt/test \
+  && sudo touch /mnt/test/proba && echo "ZAPIS DZIAŁA" \
+  && sudo rm /mnt/test/proba; sudo umount /mnt/test'
+```
+
+Musi wypisać **`ZAPIS DZIAŁA`**.
+
+| 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ł.
+
+---
+
+## Krok 3 — wdróż i sprawdź
+
+```bash
+kubectl apply -k astrololo
+kubectl -n astrololo rollout status deploy/presentation
+```
+
+Sprawdź, że aplikacja faktycznie umie tam zapisać — załóż konto testowe
+na ekranie „Konta", a potem:
+
+```bash
+kubectl -n astrololo exec deploy/presentation -- ls -l /app/state/
+```
+
+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
+# ID udziału
+midclt call sharing.nfs.query | python3 -c "import sys,json;[print(s['id'], s.get('path')) for s in json.load(sys.stdin)]"
+midclt call sharing.nfs.delete <ID>
+```
+
+---
+
+## Uwaga na przyszłość: DAN-27 uderzy w tę samą ścianę
+
+Zarządzanie plikami baz (wgrywanie, archiwizacja, kasowanie) wymaga zapisu do
+**udziału z bazami** — a ten jest `ro: true`. Ten runbook tego **nie rozwiązuje**
+i celowo nie rusza DAN-25: to osobna decyzja, bo oznacza rezygnację z gwarancji,
+że baz nie da się zmienić przez NFS. Patrz PR `feat/pliki-zapis`.
@@ -3,8 +3,35 @@
 Manifesty k8s składane Kustomize. Obrazy podbija automatycznie image-updater
 (`kustomization.yaml` → `images: newTag`) po każdym buildzie z repo aplikacji.

-Warstwy: `presentation` (NodePort, wejście z przeglądarki) → `logic` → `data`
-(pliki Excel montowane **z NFS**, nie z obrazu).
+Warstwy: `presentation` (wejście z przeglądarki przez **Ingress po https**) →
+`logic` → `data` (pliki Excel montowane **z NFS**, nie z obrazu).
+
+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.
+
+## ⚠️ Udział `astrololo-state` — wymagany przez konta (PRE-27)
+
+Pod `presentation` **nie wstanie bez niego** (`CreateContainerConfigError:
+failed to create subPath directory`). Osobny runbook:
+**[README-stan-prezentacji.md](README-stan-prezentacji.md)**.
+
+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

@@ -50,12 +77,112 @@ trzech** usług naraz, inaczej przestaną się dogadywać.)
 ### Sprawdzenie po wdrożeniu
 ```bash
 kubectl -n astrololo rollout status deploy/presentation deploy/logic deploy/data
-NODE_PORT=$(kubectl -n astrololo get svc presentation -o jsonpath='{.spec.ports[0].nodePort}')
-curl -s -o /dev/null -w "bez hasła: %{http_code}\n"  http://<adres-noda>:$NODE_PORT/
-curl -s -o /dev/null -w "z hasłem: %{http_code}\n" -u astrololo:'<hasło>' http://<adres-noda>:$NODE_PORT/
+curl -s -o /dev/null -w "bez hasła: %{http_code}\n"  https://astrololo.czernobog.pl/
+curl -s -o /dev/null -w "z hasłem: %{http_code}\n" -u astrololo:'<hasło>' https://astrololo.czernobog.pl/
 ```
 Oczekiwane: **401** bez hasła, **200** z hasłem. `/health` zostaje publiczny (sondy k8s).

+## 🔒 TLS — wymagane kroki przed wdrożeniem
+
+Do tej pory Basic Auth szedł siecią po zwykłym http, czyli **hasło dało się
+podsłuchać** (base64 to nie szyfrowanie). Poza tym http blokował dwie funkcje,
+bo przeglądarki udostępniają je wyłącznie w tzw. *secure context*:
+**geolokalizacja** („Tu i teraz") i **kopiowanie do schowka**. Certyfikat załatwia
+oba tematy naraz.
+
+Certyfikat wystawia **własne CA** trzymane w klastrze (cert-manager). Let's Encrypt
+odpada, bo klaster stoi w LAN — walidacja HTTP-01 nie ma jak do niego dojść z
+internetu, a DNS-01 wymagałby trzymania tu tokena API do domeny.
+
+**Kolejność ma znaczenie — oba kroki PRZED synchronizacją ArgoCD.**
+
+### 1. cert-manager (jednorazowo, cały klaster)
+```bash
+kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.21.0/cert-manager.yaml
+kubectl -n cert-manager rollout status deploy/cert-manager deploy/cert-manager-webhook
+```
+Bez tego API odrzuci `Certificate` i `Issuer` jako nieznane rodzaje zasobów,
+a ArgoCD pokaże aplikację jako niezsynchronizowaną.
+
+### 2. DNS: `astrololo.czernobog.pl` → adres Traefika
+```bash
+kubectl -n kube-system get svc traefik -o jsonpath='{.status.loadBalancer.ingress[*].ip}'; echo
+```
+Wpis w routerze / lokalnym DNS-ie (albo doraźnie `/etc/hosts`). **Service
+`presentation` jest teraz `ClusterIP`** — NodePort był drugą, nieszyfrowaną drogą
+do aplikacji, więc został zdjęty. Zanim DNS zacznie odpowiadać, jedyne wejście to:
+```bash
+kubectl -n astrololo port-forward svc/presentation 8000:8000   # awaryjnie, http://localhost:8000
+```
+
+### 3. Zaufanie do własnego CA (raz na urządzenie)
+Bez tego przeglądarka pokaże ostrzeżenie o certyfikacie. Korzeń ważny 10 lat,
+więc import robisz raz:
+```bash
+kubectl -n astrololo get secret astrololo-ca -o jsonpath='{.data.ca\.crt}' \
+  | base64 -d > astrololo-ca.crt
+
+# macOS — do systemowego zaufania (poprosi o hasło administratora)
+sudo security add-trusted-cert -d -r trustRoot \
+  -k /Library/Keychains/System.keychain astrololo-ca.crt
+
+# Linux (Debian/Ubuntu)
+sudo cp astrololo-ca.crt /usr/local/share/ca-certificates/ && sudo update-ca-certificates
+```
+Firefox ma własny magazyn — tam import przez *Ustawienia → Prywatność →
+Wyświetl certyfikaty → Organy certyfikacji*.
+
+### Sprawdzenie samego TLS
+```bash
+# certyfikat wystawiony i gotowy
+kubectl -n astrololo get certificate
+# oczekiwane: astrololo-ca True, astrololo-tls True
+
+# http odsyła na https
+curl -sI http://astrololo.czernobog.pl/ | head -2       # 301 + Location: https://...
+
+# HSTS obecny
+curl -skI -u astrololo:'<hasło>' https://astrololo.czernobog.pl/ | grep -i strict-transport
+```
+
+### Odnawianie
+Certyfikat serwera żyje 90 dni i odnawia się sam 30 dni przed końcem. Termin jest
+krótki **celowo** — odnawianie sprawdza się wtedy w praktyce co kwartał, a nie
+dopiero za dziesięć lat, gdy nikt nie będzie pamiętał, jak to było skonfigurowane.
+
+## ⚠️ Sekret `astrololo-link` — szyfrowanie między warstwami
+
+Token międzywarstwowy mówi **kto** pyta, ale nie ukrywa **czego dotyczy odpowiedź**
+— a płyną nią surowe wiersze oryginalnych baz. Kto podsłuchał ruch wewnątrz sieci
+(drugi pod, mirror portu na switchu, zrzut z węzła), miał je w całości. Łącza są
+więc szyfrowane **AES-256-GCM**, osobnym kluczem na każdą parę rozmówców.
+
+```bash
+kubectl -n astrololo create secret generic astrololo-link \
+  --from-literal=LINK_KEY_PRESENTATION_LOGIC="$(openssl rand -hex 32)" \
+  --from-literal=LINK_KEY_LOGIC_DATA="$(openssl rand -hex 32)"
+```
+
+Kluczy **nikt nigdy nie musi oglądać** — służą tylko usługom. Rozdzielenie jest
+celowe: przejęcie klucza prezentacji nie daje dostępu do warstwy danych, gdzie
+leżą całe bazy. Logika trzyma oba, bo rozmawia w obie strony; prezentacja i dane
+dostają przez `secretKeyRef` wyłącznie swój.
+
+**Pody nie wstaną bez tych kluczy** (`LINK_ENCRYPTION_REQUIRED=true`) — i tak ma
+być. Usługa, która wstała i po cichu nie szyfruje, jest gorsza niż pod w CrashLoop,
+bo awarii nie widać.
+
+### Wymiana kluczy
+```bash
+kubectl -n astrololo create secret generic astrololo-link \
+  --from-literal=LINK_KEY_PRESENTATION_LOGIC="$(openssl rand -hex 32)" \
+  --from-literal=LINK_KEY_LOGIC_DATA="$(openssl rand -hex 32)" \
+  --dry-run=client -o yaml | kubectl apply -f -
+kubectl -n astrololo rollout restart deploy/presentation deploy/logic deploy/data
+```
+Restart **wszystkich trzech naraz** — w trakcie wymiany warstwy chwilowo się nie
+dogadują (klucze muszą być zgodne po obu stronach łącza).
+
 ## Klucze do modeli w chmurze — sekret `astrololo-llm` (opcjonalny)

 Domyślnie działa **model lokalny** i nic nie opuszcza sieci. Żeby móc wybrać w UI
@@ -94,8 +221,12 @@ gdzie faktycznie stoi Ollama/vLLM. Konfiguracja jest **per dostawca**
 > Retention — patrz LOG-32.

 ## Czego to nie załatwia
- **Brak TLS** — Basic Auth idzie po sieci w postaci łatwej do podsłuchania. Przy
-  niezaufanej sieci potrzebny ingress z certyfikatem.
+- **Własne CA to nie to samo co publiczne zaufanie** — każde nowe urządzenie
+  wymaga importu korzenia (krok 3 powyżej). Gdyby aplikacja miała kiedyś wyjść
+  na świat, właściwą drogą jest Let's Encrypt przez DNS-01.
+- **Szyfrowane są ciała żądań, nie nagłówki** — ścieżka (`/search`) i token
+  międzywarstwowy jadą czytelnie. Sam token nikomu nic nie daje: bez klucza łącza
+  każde żądanie kończy się odmową. Pełne ukrycie metadanych wymagałoby mTLS.
 - **NFS `192.168.1.34:/mnt/Tank1/astrololo`** — kto ma dostęp do share'u, bierze
  pliki baz **z pominięciem całej aplikacji**. Do zamknięcia po stronie infrastruktury
  (eksport tylko dla IP węzłów, `root_squash`, najlepiej read-only).
@@ -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
@@ -29,6 +33,17 @@ spec:
            - name: INTERNAL_TOKEN
              valueFrom:
                secretKeyRef: { name: astrololo-auth, key: INTERNAL_TOKEN }
+            # Szyfrowanie łącza między warstwami (PRE-16). OSOBNY klucz na każdą
+            # parę rozmówców: przejęcie klucza prezentacji nie otwiera warstwy
+            # danych, gdzie leżą całe bazy. Sekret tworzony POZA repo — patrz README.
+            - name: LINK_KEY_LOGIC_DATA
+              valueFrom:
+                secretKeyRef: { name: astrololo-link, key: LINK_KEY_LOGIC_DATA }
+            # 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ę.
+            - name: LINK_ENCRYPTION_REQUIRED
+              value: "true"
          volumeMounts:
            - name: cache
              mountPath: /app/.cache
@@ -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
@@ -0,0 +1,75 @@
+# Wejście do aplikacji po HTTPS (PRE-16).
+#
+# Poza bezpieczeństwem — Basic Auth po zwykłym http leci siecią czytelny dla
+# każdego, kto słucha — TLS naprawia DWIE funkcje zepsute dziś z tego samego
+# powodu: geolokalizacja przeglądarki („Tu i teraz") oraz kopiowanie promptu do
+# schowka działają wyłącznie w tzw. secure context i po http po prostu odmawiają.
+---
+apiVersion: traefik.io/v1alpha1
+kind: Middleware
+metadata:
+  name: security-headers
+  namespace: astrololo
+spec:
+  headers:
+    stsSeconds: 31536000                  # HSTS: rok
+    stsIncludeSubdomains: false           # dotyczy tylko tego hosta
+    stsPreload: false                     # preload to wpis na listę w przeglądarkach
+                                          # — praktycznie nieodwracalny, nie wchodzimy
+    forceSTSHeader: true                  # nagłówek także przy odpowiedziach z backendu
+    contentTypeNosniff: true
+    frameDeny: true
+    referrerPolicy: same-origin
+---
+apiVersion: traefik.io/v1alpha1
+kind: Middleware
+metadata:
+  name: redirect-https
+  namespace: astrololo
+spec:
+  redirectScheme:
+    scheme: https
+    permanent: true
+---
+apiVersion: networking.k8s.io/v1
+kind: Ingress
+metadata:
+  name: astrololo
+  namespace: astrololo
+  annotations:
+    traefik.ingress.kubernetes.io/router.entrypoints: websecure
+    traefik.ingress.kubernetes.io/router.middlewares: astrololo-security-headers@kubernetescrd
+spec:
+  tls:
+    - hosts: [astrololo.czernobog.pl]
+      secretName: astrololo-tls           # wypełnia cert-manager (tls.yaml)
+  rules:
+    - host: astrololo.czernobog.pl
+      http:
+        paths:
+          - path: /
+            pathType: Prefix
+            backend:
+              service: { name: presentation, port: { number: 8000 } }
+---
+# Osobny Ingress wyłącznie na porcie 80 — istnieje po to, żeby odesłać na https.
+# Rozdzielone świadomie: gdyby przekierowanie wisiało na tym samym routerze, co
+# wejście po https, odsyłałoby samo do siebie w kółko. Backend jest tu formalnością,
+# bo żadne żądanie do niego nie dojdzie.
+apiVersion: networking.k8s.io/v1
+kind: Ingress
+metadata:
+  name: astrololo-redirect
+  namespace: astrololo
+  annotations:
+    traefik.ingress.kubernetes.io/router.entrypoints: web
+    traefik.ingress.kubernetes.io/router.middlewares: astrololo-redirect-https@kubernetescrd
+spec:
+  rules:
+    - host: astrololo.czernobog.pl
+      http:
+        paths:
+          - path: /
+            pathType: Prefix
+            backend:
+              service: { name: presentation, port: { number: 8000 } }
@@ -5,10 +5,15 @@ resources:
  - data.yaml
  - logic.yaml
  - presentation.yaml
+  - 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
@@ -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
@@ -26,6 +30,20 @@ spec:
            - name: INTERNAL_TOKEN
              valueFrom:
                secretKeyRef: { name: astrololo-auth, key: INTERNAL_TOKEN }
+            # Szyfrowanie łącza między warstwami (PRE-16). OSOBNY klucz na każdą
+            # parę rozmówców: przejęcie klucza prezentacji nie otwiera warstwy
+            # danych, gdzie leżą całe bazy. Sekret tworzony POZA repo — patrz README.
+            - name: LINK_KEY_PRESENTATION_LOGIC
+              valueFrom:
+                secretKeyRef: { name: astrololo-link, key: LINK_KEY_PRESENTATION_LOGIC }
+            - name: LINK_KEY_LOGIC_DATA
+              valueFrom:
+                secretKeyRef: { name: astrololo-link, key: LINK_KEY_LOGIC_DATA }
+            # 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ę.
+            - name: LINK_ENCRYPTION_REQUIRED
+              value: "true"

            # --- Model językowy (LOG-31) ---
            # Domyślnie LOKALNY: prompt niesie oryginalne opisy z baz, więc nic nie
@@ -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
@@ -30,9 +34,62 @@ spec:
              value: "astrololo"
            - name: RATE_LIMIT_PER_MIN
              value: "120"                       # 0 = bez limitu
+            # Aplikacja stoi za Ingressem, więc bezpośrednim rozmówcą jest zawsze
+            # pod Traefika. Bez tego limit żądań liczyłby WSZYSTKICH do jednego
+            # wiadra i pierwsza osoba, która go wyklika, odcięłaby pozostałych.
+            # Włączać wyłącznie gdy ruch faktycznie idzie przez proxy — inaczej
+            # nagłówek staje się furtką do ominięcia limitu.
+            - name: TRUST_PROXY
+              value: "true"
+            # Szyfrowanie łącza między warstwami (PRE-16). OSOBNY klucz na każdą
+            # parę rozmówców: przejęcie klucza prezentacji nie otwiera warstwy
+            # danych, gdzie leżą całe bazy. Sekret tworzony POZA repo — patrz README.
+            - name: LINK_KEY_PRESENTATION_LOGIC
+              valueFrom:
+                secretKeyRef: { name: astrololo-link, key: LINK_KEY_PRESENTATION_LOGIC }
+            # 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:
+            # OSOBNY UDZIAŁ, nie podkatalog udziału z bazami. Pierwsza wersja
+            # montowała /mnt/Tank1/astrololo z subPath — i nie wstała:
+            # „failed to create subPath directory”. Powód był podwójny i oba razy
+            # ten sam brak: udział z bazami jest wyeksportowany `ro: true`
+            # z `root_squash` (DAN-25), więc (1) kubelet nie mógł utworzyć
+            # podkatalogu, a (2) gdyby nawet mógł, aplikacja i tak nie zapisałaby
+            # tam pliku kont.
+            #
+            # Osobny udział rozwiązuje to bez naruszania DAN-25: udział z bazami
+            # ZOSTAJE tylko do odczytu, a konta mają własne, małe miejsce.
+            # Przy okazji znika subPath, czyli znika potrzeba, żeby kubelet
+            # cokolwiek zakładał — katalog istnieje, bo jest korzeniem udziału.
+            - name: state
+              mountPath: /app/state
          resources:
            requests: { cpu: "100m", memory: "128Mi" }
            limits:   { cpu: "300m", memory: "256Mi" }
+      volumes:
+        - name: state
+          nfs:
+            server: 192.168.1.34
+            # Udział WYŁĄCZNIE na stan prezentacji (konta z PRE-27). Wymaga
+            # utworzenia na TrueNAS — patrz README-stan-prezentacji.md.
+            path: /mnt/Tank1/astrololo-state
 ---
 apiVersion: v1
 kind: Service
@@ -40,7 +97,10 @@ metadata:
  name: presentation
  namespace: astrololo
 spec:
-  type: NodePort                                  # wejście z przeglądarki
+  # Wejście z przeglądarki idzie teraz WYŁĄCZNIE przez Ingress po https
+  # (ingress.yaml). NodePort był drugą, nieszyfrowaną drogą do środka — czyli
+  # obejściem całego PRE-16 — więc znika.
+  type: ClusterIP
  selector: { app: presentation }
  ports: [{ port: 8000, targetPort: 8000 }]

@@ -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 }]
@@ -0,0 +1,65 @@
+# Certyfikat dla wejścia do aplikacji (PRE-16).
+#
+# Dlaczego WŁASNE CA, a nie Let's Encrypt: klaster stoi w LAN (traefik trzyma
+# LoadBalancera na 192.168.1.x), więc walidacja HTTP-01 nie ma jak dojść z
+# internetu, a DNS-01 wymagałby trzymania w klastrze tokena API do domeny.
+# Własne CA nie potrzebuje niczego z zewnątrz, a certyfikaty odnawia samo.
+#
+# WYMAGANIE WSTĘPNE: cert-manager musi być w klastrze PRZED synchronizacją tego
+# katalogu — inaczej API odrzuci poniższe obiekty jako nieznane rodzaje zasobów.
+# Instalacja jednorazowa: patrz README.md.
+#
+# Wszystko jest w namespace `astrololo` (Issuer, nie ClusterIssuer) świadomie:
+# ArgoCD ma tu włączone `prune`, a zasoby o zasięgu całego klastra chcemy trzymać
+# poza aplikacją, która może zostać skasowana.
+---
+apiVersion: cert-manager.io/v1
+kind: Issuer
+metadata:
+  name: selfsigned
+  namespace: astrololo
+spec:
+  selfSigned: {}
+---
+# Korzeń zaufania. TO JEST certyfikat, który raz importujesz do przeglądarki
+# i systemu — patrz README. Stąd długi termin ważności: importu nie chcemy
+# powtarzać co kwartał.
+apiVersion: cert-manager.io/v1
+kind: Certificate
+metadata:
+  name: astrololo-ca
+  namespace: astrololo
+spec:
+  isCA: true
+  commonName: astrololo internal CA
+  secretName: astrololo-ca                # tu lądują klucz i certyfikat korzenia
+  duration: 87600h                        # 10 lat
+  renewBefore: 8760h                      # odnowienie na rok przed końcem
+  privateKey: { algorithm: ECDSA, size: 256 }
+  issuerRef: { name: selfsigned, kind: Issuer, group: cert-manager.io }
+---
+apiVersion: cert-manager.io/v1
+kind: Issuer
+metadata:
+  name: astrololo-ca
+  namespace: astrololo
+spec:
+  ca: { secretName: astrololo-ca }
+---
+# Właściwy certyfikat serwera. Krótki termin CELOWO: przy 90 dniach odnawianie
+# jest sprawdzane w praktyce co kwartał, więc awaria wyjdzie od razu, a nie za
+# dziesięć lat, gdy nikt już nie będzie pamiętał, jak to działa.
+apiVersion: cert-manager.io/v1
+kind: Certificate
+metadata:
+  name: astrololo-tls
+  namespace: astrololo
+spec:
+  secretName: astrololo-tls               # tego szuka Ingress
+  commonName: astrololo.czernobog.pl
+  dnsNames:
+    - astrololo.czernobog.pl
+  duration: 2160h                         # 90 dni
+  renewBefore: 720h                       # 30 dni zapasu
+  privateKey: { algorithm: ECDSA, size: 256, rotationPolicy: Always }
+  issuerRef: { name: astrololo-ca, kind: Issuer, group: cert-manager.io }
@@ -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.
@@ -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 }]
@@ -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" }
@@ -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
@@ -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 }]
@@ -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
@@ -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 }]
@@ -0,0 +1,4 @@
+apiVersion: v1
+kind: Namespace
+metadata:
+  name: conjurer