infra/docs/HANDOFF.md

# HANDOFF.md — przekazanie kontekstu

Dokument jednorazowy. Powstał w rozmowie na claude.ai przed pierwszym uruchomieniem
serwera i przenosi ustalenia do sesji Claude Code na maszynie.

**Czytasz go raz, na starcie pierwszej sesji.** Trwałe zasady są w `CLAUDE.md`,
stan serwera w `docs/SERVER.md`, procedury w `docs/runbooks/`.
Po zakończeniu bootstrapu ten plik można usunąć.

---

## 1. Z kim pracujesz

**Kacper**, `k.kruszka@hotmail.com`. Pracuje z macOS, Windows i iOS.

Kluczowe: **to projekt edukacyjny z produkcyjnymi konsekwencjami.** Kacper uczy się
pracy z Claude i administracji serwerem — więc tłumaczysz co robisz i dlaczego,
nie tylko wykonujesz. Ale docelowo mogą tu stanąć rzeczy komercyjne, więc traktujesz
maszynę jak produkcję od pierwszego dnia.

Prosił wprost, żeby **proaktywnie podpowiadać** o narzędziach, skillach i funkcjach,
które mogą pomóc — nie czekać, aż sam zapyta.

---

## 2. Maszyna

| | |
|---|---|
| OVH VPS-2 2026 | 6 vCore, 12 GB RAM, 100 GB SSD |
| Host | `vps-c936b594.vps.ovh.net`, IPv4 `54.38.159.156` |
| System | Ubuntu 24.04 LTS, świeży |
| Panel OVH | region **CA** — ma znaczenie przy generowaniu tokenów API |
| Snapshot | włączony, 1 slot, ręczny, nadpisywany |
| Domena techniczna | `dfkk.cloud` (OVH, DNS w OVH) |
| Pozostałe domeny | dwie, nazwy jeszcze nieustalone, zostają wolne pod projekty |

---

## 3. Stan na teraz

- Kacper loguje się jako **`ubuntu`** (konto domyślne obrazu OVH, z `sudo`) — roota po SSH nie ma
- Bootstrap **nie został rozpoczęty**
- Pliki repo `infra` wgrane przez `scp` do `/srv/infra`
- Na serwerze jest klucz SSH wgrany przez OVH — **do weryfikacji przy kroku 0**
- **Logowanie hasłem jest nadal włączone.** Windows łączył się hasłem, więc nie ma tam
  jeszcze klucza. Krok 2 bootstrapu musi to domknąć **przed** krokiem 3.
- Nie ma jeszcze: użytkownika `ubuntu`, Dockera, Traefika, Gitei, firewalla, niczego

**Następny krok: `docs/runbooks/00-bootstrap.md`, krok 0.**

---

## 4. Decyzje podjęte i uzasadnienie

Podjęte świadomie, po omówieniu alternatyw. **Nie otwieraj ich ponownie bez powodu** —
jeśli widzisz problem z którąś, powiedz to wprost, ale nie zaczynaj od zera.

| Decyzja | Dlaczego |
|---|---|
| Docker + Traefik, ręcznie | Zamiast panelu Coolify/Dokploy — pełna kontrola i więcej nauki. Świadomy wybór trudniejszej drogi. |
| Gitea self-hosted na tej maszynie | Wybór Kacpra. **Z warunkiem:** mirror repo `infra` na prywatne repo GitHuba, bo inaczej awaria zabiera kod i konfigurację naraz. |
| Certyfikaty przez DNS-01 (API OVH) | Wildcard `*.dfkk.cloud` — nowa subdomena nie wymaga żadnej akcji przy certyfikacie. Możliwe też usługi niepubliczne. |
| Praca przez SSH + tmux | Sesja przeżywa rozłączenie. Ten sam `tmux attach` z Maca, Windowsa i iPhone'a. VS Code Remote SSH jako dodatek, nie zamiennik. |
| Osobny klucz SSH na urządzenie | Zgubiony telefon = usunięcie jednej linii z `authorized_keys`. |
| Konto robocze `ubuntu`, bez tworzenia `deploy` | Obraz OVH daje `ubuntu` z `sudo` i działającym kluczem. Tworzenie nowego konta to dodatkowe ryzyko lockoutu przy marginalnym zysku — realną ochroną jest brak haseł, ufw i fail2ban, nie nietypowa nazwa użytkownika. |
| Kontenery nie publikują portów | Docker omija ufw — opublikowany port jest widoczny z internetu mimo `deny` w firewallu. Wejście wyłącznie przez Traefika. |
| Wersje obrazów przypięte, nigdy `:latest` | Żeby `docker compose pull` nie podmienił działającej aplikacji na zepsutą, i żeby był rollback. |
| Brak serwera pocztowego | OVH blokuje port 25, IP bez reputacji trafia do spamu. Maile przez zewnętrzny SMTP (Resend/Brevo). |
| Backup off-site odłożony | Kacper ma wykupione chmury, wrócimy do restica **zanim** pojawią się pierwsze prawdziwe dane. Do tego czasu snapshot OVH wystarcza. |
| Skille napisane później | Najpierw przejść runbooki ręcznie raz czy dwa, potem zamienić w skille to, co się faktycznie powtarza. |

---

## 5. Decyzje otwarte

- **`sudo` z hasłem czy `NOPASSWD` dla `ubuntu`?** Do rozstrzygnięcia w kroku 2 bootstrapu.
  Rekomendacja z runbooka: `NOPASSWD`, ale z ustawionym hasłem jako furtka przez konsolę KVM.
- **Nazwy dwóch pozostałych domen** — do wpisania w `SERVER.md` gdy będą potrzebne.
- **Gdzie backup off-site** — Kacper ma wykupione chmury, do ustalenia który dostawca.

---

## 6. Rzeczy, o których trzeba pamiętać

Wynikły z rozmowy, łatwo je przeoczyć:

1. **Kacper nie zna jeszcze wszystkich mechanizmów.** Warto przy okazji wyjaśniać —
   np. dlaczego `claude` odpalamy z `/srv/infra` (inaczej `CLAUDE.md` się nie załaduje),
   po co `/context` i `/memory`.
2. **Repo `infra` to kanał między rozmowami.** Ustalenie, które nie trafi do
   `CLAUDE.md`, `SERVER.md` albo runbooka, umiera razem z sesją. Ta zasada jest
   powodem, dla którego `SERVER.md` ma być aktualizowany w tej samej sesji, co zmiana.
3. **`scp` był jednorazowy.** Od momentu postawienia Gitei repo idzie przez git.
   Ręczne kopiowanie plików na serwer to nawyk, przez który po miesiącu nikt nie wie,
   która wersja konfiguracji jest prawdziwa.
4. **Lista braków jest w `docs/SECURITY.md`, sekcja 8.** Najpilniejsze: mirror na GitHub
   i 2FA na koncie OVH — panel OVH może maszynę zreinstalować, więc w praktyce
   jest ważniejszy niż dostęp SSH.

---

## 7. Czego nie robić

- Nie startuj bootstrapu bez potwierdzenia — Kacper może chcieć najpierw przeczytać runbooki
- Nie zmieniaj `sshd_config` bez otwartej drugiej sesji SSH
- Nie zakładaj, że coś działa — sprawdzaj (`curl`, `docker ps`, logi)
- Nie rób `docker system prune -a --volumes` odruchowo
- Nie wracaj do rozstrzygniętych decyzji z sekcji 4 bez konkretnego powodu