deploy/astrololo/README-stan-prezentacji.md

# 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

Kontenery aplikacji działają **jako root**, a eksport ma `root_squash`, więc root
z klienta NIE jest rootem na udziale. Żeby zapis działał, przypinamy cały ruch
z tych hostów do jednego, nieuprzywilejowanego użytkownika — to bezpieczniejsze
niż `no_root_squash`, bo nie oddaje roota.

```bash
# użytkownik, na którego mapujemy (jeśli nie istnieje — utwórz w UI TrueNAS)
sudo chown -R apps:apps /mnt/Tank1/astrololo-state
sudo chmod 770 /mnt/Tank1/astrololo-state
```

> Podstaw swojego użytkownika w miejsce `apps`. Sprawdzisz istniejących:
> `midclt call user.query | python3 -c "import sys,json;[print(u['uid'], u['username']) for u in json.load(sys.stdin)]"`

### 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": "apps",
  "mapall_group": "apps"
}'
```

**Coś zwróciło** — weź `id` z wyniku i zaktualizuj (podstaw `<ID>`):

```bash
midclt call sharing.nfs.update <ID> '{
  "hosts": ["192.168.1.73", "192.168.1.80", "192.168.1.81"],
  "enabled": true,
  "ro": false,
  "mapall_user": "apps",
  "mapall_group": "apps"
}'
```

| 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 pisze jako jeden nieuprzywilejowany użytkownik, niezależnie od UID w kontenerze |

> Podstaw swoje adresy węzłów, jeśli się zmieniły. Aktualne:
> `kubectl get nodes -o wide`

---

### Sprawdź, co serwer FAKTYCZNIE eksportuje

Konfiguracja udziału i stan eksportu to **dwie różne rzeczy**: zapisana
konfiguracja nie znaczy, że usługa ją przeładowała. To jest prawda:

```bash
sudo exportfs -v | grep -A1 astrololo
```

Muszą być **dwa** wpisy: `/mnt/Tank1/astrololo` (z `ro`) oraz
`/mnt/Tank1/astrololo-state` (z `rw`), oba z listą trzech węzłów.

Jeśli `astrololo-state` **nie ma na liście**, mimo że `sharing.nfs.query` go
pokazuje — usługa nie przeładowała eksportów:

```bash
midclt call service.restart nfs
sudo exportfs -v | grep astrololo-state
```

---

## Krok 2 — sprawdź z węzła, ZANIM wdrożysz

To jest ten test, którego zabrakło za pierwszym razem:

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

---

## 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`.