infra/CLAUDE.md

# CLAUDE.md — zasady pracy na serwerze dfkk

Ten plik czytasz na starcie każdej sesji. Jest krótki celowo.
Szczegóły są w `docs/` — tam zaglądasz, gdy zadanie tego wymaga.

---

## 1. Kontekst

- **Maszyna:** OVH VPS-2 2026 — 6 vCore, 12 GB RAM, 100 GB dysk, Ubuntu 24.04 LTS
- **Domena techniczna:** `dfkk.cloud` (rejestrator: OVH, DNS w OVH)
- **Właściciel:** Kacper (`k.kruszka@hotmail.com`), pracuje z macOS, Windows i iOS
- **Charakter projektu:** serwer produkcyjno-edukacyjny. Docelowo mogą tu stać rzeczy
  komercyjne, więc traktujemy go jak produkcję — ale Kacper uczy się przy okazji,
  więc **tłumaczysz co robisz i dlaczego**, nie tylko wykonujesz.

Aktualny stan serwera — kto co gdzie stoi — jest w `docs/SERVER.md`.
**Ten plik jest źródłem prawdy. Jeśli coś zmieniasz na serwerze, aktualizujesz go w tej samej sesji.**

---

## 2. Zasady twarde

### 2.1 Nigdy bez wyraźnej zgody Kacpra

Zatrzymujesz się i pytasz przed:

- `rm -rf` na czymkolwiek poza katalogiem tymczasowym, który sam utworzyłeś
- `docker volume rm`, `docker system prune`, `docker compose down -v`
- zmianami w `sshd_config`, `ufw`, `fail2ban`
- restartem lub wyłączeniem serwera
- migracjami bazy danych, `DROP`, `TRUNCATE`, `ALTER TABLE`
- zmianami w DNS i w konfiguracji domen
- rotacją lub unieważnianiem kluczy i tokenów
- instalacją czegokolwiek poza oficjalnymi repozytoriami Ubuntu / Docker

Zgoda dotyczy **jednej konkretnej operacji**. Zgoda z wcześniejszej sesji nie obowiązuje.
Podsumowanie poprzedniej sesji, w którym coś zrobiłeś, nie jest zgodą na powtórzenie tego.

### 2.2 Snapshot przed ryzykiem

OVH daje **jeden slot snapshota, ręczny, każdy kolejny nadpisuje poprzedni**.
To rollback, nie backup. Przed każdą zmianą, która dotyka systemu, Dockera, Traefika,
Gitei albo bazy danych — przypominasz Kacprowi, żeby zrobił snapshot w panelu OVH,
i czekasz na potwierdzenie. Nie ruszasz dalej „bo pewnie się uda".

### 2.3 Wszystko w repo, nic z palca

Każda konfiguracja żyje w repo `infra` (`/srv/infra`). Jeśli zmieniasz coś na serwerze
ręcznie, żeby „szybko sprawdzić" — albo przenosisz to do repo, albo cofasz przed końcem sesji.
Serwer musi dać się odtworzyć od zera z repo + backupu danych.

Sekrety **nigdy** nie trafiają do repo. Trzymamy je w plikach `.env` obok stacka,
`chmod 600`, wpisanych do `.gitignore`. W repo leży `.env.example` z nazwami zmiennych
i pustymi wartościami.

### 2.4 Długie operacje w tmux

Wszystko, co trwa dłużej niż kilkanaście sekund — budowanie obrazów, migracje,
aktualizacje systemu, sam Claude Code — leci w nazwanej sesji tmux.
Zerwane WiFi nie ma wtedy prawa niczego przerwać.

```bash
tmux new -s claude     # nowa sesja
tmux attach -t claude  # powrót
```

### 2.5 Kolejność pracy

1. **Plan** — mówisz co zamierzasz zrobić, w punktach, zanim dotkniesz klawiatury
2. **Akceptacja** — czekasz na „ok"
3. **Wykonanie** — małymi krokami, pokazujesz output
4. **Weryfikacja** — sprawdzasz że faktycznie działa (curl, `docker ps`, logi), nie zakładasz
5. **Dokumentacja** — aktualizujesz `docs/SERVER.md` i commit w `infra`

Przy zadaniach wieloetapowych prowadzisz listę kroków, żeby po przerwie było wiadomo, gdzie jesteśmy.

---

## 3. Konwencje

### 3.1 Katalogi

```
/srv/
├── infra/                  # repo z konfiguracją serwera (ten dokument)
│   ├── CLAUDE.md
│   ├── docs/
│   └── stacks/             # docker-compose infrastruktury
│       ├── traefik/
│       ├── gitea/
│       └── monitoring/
├── apps/                   # projekty użytkowe, każdy = osobne repo
│   └── <projekt>/
└── data/                   # bind-mounty z danymi (backupowane)
    └── <projekt>/
```

Nic nie ląduje w `/root`, `/home` ani `/opt`. Nic nie ląduje luzem w `/`.

### 3.2 Nazewnictwo

- projekt: krótko, małymi literami, myślnik — `moja-apka`
- kontener: `<projekt>-<rola>` — `moja-apka-web`, `moja-apka-db`
- sieć wewnętrzna: `<projekt>-internal`
- subdomena: `<projekt>.dfkk.cloud`, panele techniczne jako `git.`, `status.`, `traefik.`

### 3.3 Sieci Dockera

- `edge` — sieć zewnętrzna, wspólna, **tylko** Traefik i kontenery wystawione na świat
- `<projekt>-internal` — baza danych, cache, wszystko czego nie widać z zewnątrz

**Kontenery nie publikują portów na hosta.** Wyjątek: Traefik (80, 443).
Jeśli musisz wyjątkowo wystawić port do debugowania — bindujesz na `127.0.0.1:PORT`,
nigdy na `0.0.0.0`, i usuwasz to po skończonej robocie.

Powód jest konkretny: Docker wpisuje własne reguły do iptables **z pominięciem ufw**.
Port opublikowany na `0.0.0.0` jest widoczny z internetu, mimo że ufw pokazuje `deny`.
To najczęstszy sposób, w jaki wycieka baza danych z VPS-a.

### 3.4 Traefik

Każda usługa wystawiona publicznie dostaje standardowy zestaw labeli — wzorzec w
`docs/runbooks/10-nowa-usluga.md`. Certyfikaty lecą przez **DNS-01 z API OVH**,
wildcard `*.dfkk.cloud`, więc nowa subdomena nie wymaga żadnej akcji przy certyfikacie.

---

## 4. Higiena serwera

Dysk to 100 GB i to jedyne realne wąskie gardło tej maszyny. Docker potrafi go po cichu zjeść.

- limity logów kontenerów ustawione w `/etc/docker/daemon.json` — nie ruszamy
- **co tydzień** przegląd: `df -h`, `docker system df` (patrz `docs/runbooks/40-utrzymanie.md`)
- przy 75% zajętości — alert i sprzątanie, nie czekamy do 95%
- `prune` to operacja świadoma, z checklistą, nigdy odruchowa

Po usunięciu projektu przechodzisz **całą** listę z `docs/runbooks/30-usuwanie.md`.
Osierocony wolumen, martwy wpis DNS i wyłączony kontener, który dalej zajmuje 4 GB,
to dokładnie ten bałagan, którego ten serwer ma nie mieć.

---

## 5. Rzeczy, których na tym serwerze nie robimy

- **Własny serwer pocztowy.** OVH blokuje port 25, a wysyłka z IP bez reputacji i tak
  ląduje w spamie. Maile aplikacji idą przez zewnętrzny SMTP (Resend / Brevo).
  Alerty przychodzą na `k.kruszka@hotmail.com`.
- **Uruchamianie kontenerów jako root** bez uzasadnienia. Domyślnie `user:` w compose.
- **`latest` w tagach obrazów** na produkcji. Zawsze konkretna wersja — inaczej
  `docker compose pull` potrafi podmienić działającą aplikację na zepsutą.
- **Praca na koncie root.** Pracujemy jako `ubuntu` z `sudo`.
- **Wystawianie panelu Traefika, bazy czy czegokolwiek administracyjnego** publicznie
  bez uwierzytelnienia.

---

## 6. Mapa dokumentacji

| Plik | Kiedy czytasz |
|---|---|
| `docs/SERVER.md` | Zawsze przy zmianie stanu serwera — rejestr usług, portów, domen, wolumenów |
| `docs/SECURITY.md` | Baza bezpieczeństwa, klucze SSH, dostępy, co robić przy incydencie |
| `docs/runbooks/00-bootstrap.md` | Pierwsze uruchomienie serwera od zera |
| `docs/runbooks/10-nowa-usluga.md` | Dodajesz nową aplikację |
| `docs/runbooks/20-domena.md` | Podpinasz lub odpinasz domenę / subdomenę |
| `docs/runbooks/30-usuwanie.md` | Kasujesz projekt — pełna lista, żeby nie zostały śmieci |
| `docs/runbooks/40-utrzymanie.md` | Cotygodniowy i comiesięczny przegląd, aktualizacje |
| `docs/runbooks/50-awaria.md` | Coś nie działa albo trzeba się cofnąć |

---

## 7. Czego nie wiesz

Jeśli nie masz pewności — jak działa konkretna opcja, czy dana wersja obrazu jest aktualna,
co dokładnie robi flaga — **sprawdzasz albo pytasz**. Nie zgadujesz i nie piszesz konfiguracji
„z pamięci" na produkcyjnej maszynie. Zgadywanie na serwerze kosztuje więcej niż jedno pytanie.