# 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 │ └── / └── data/ # bind-mounty z danymi (backupowane) └── / ``` 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: `-` — `moja-apka-web`, `moja-apka-db` - sieć wewnętrzna: `-internal` - subdomena: `.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 - `-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.