infra/docs/runbooks/50-awaria.md

Runbook 50 — awaria i rollback

Do czytania, gdy coś nie działa. Zasada nadrzędna: najpierw diagnoza, potem zmiany. Chaotyczne restartowanie wszystkiego zaciera ślady i zamienia jeden problem w trzy.

---

Kolejność diagnozy

Idź od zewnątrz do środka. Zatrzymaj się na pierwszym kroku, który zawiedzie — tam jest problem, dalej nie ma sensu szukać.

# 1. Czy maszyna żyje?
ping <IP>
ssh ubuntu@<IP>

# 2. Czy nie brakuje zasobów? (najczęstsza przyczyna)
df -h /
free -h
uptime

# 3. Czy Docker działa?
sudo systemctl status docker
docker ps

# 4. Czy Traefik żyje?
docker logs traefik --tail=50

# 5. Czy konkretna usługa żyje?
cd /srv/apps/<projekt>
docker compose ps
docker compose logs --tail=100

---

Typowe przyczyny, w kolejności prawdopodobieństwa

Objaw	Sprawdź najpierw
Wszystko przestało działać naraz	df -h — pełny dysk zatrzymuje wszystko
Jedna usługa w restart loop	docker compose logs — zwykle brak zmiennej w .env lub zajęty port
502 z Traefika	kontener działa, ale zły port w labelu loadbalancer.server.port
404 z Traefika	zła reguła Host() albo brak traefik.enable=true
Błąd certyfikatu	logi Traefika, klucze API OVH, limity Let's Encrypt
Usługa wolna, serwer obciążony	docker stats — który kontener zjada CPU/RAM
Kontener zabity bez śladu	OOM killer: dmesg -T | grep -i oom

---

Pełny dysk — najczęstsza awaria tej maszyny

Przy 100 GB to realne ryzyko. Objawy bywają mylące: bazy przestają zapisywać, Docker nie startuje kontenerów, logi się urywają.

df -h /
sudo du -h --max-depth=1 /var | sort -hr | head
sudo du -h --max-depth=1 /srv | sort -hr | head
docker system df

Szybkie odzyskanie miejsca, od najbezpieczniejszego:

sudo journalctl --vacuum-size=200M
docker builder prune -f
docker image prune -a -f

Dopiero potem szukaj przyczyny — zwykle jest to jeden kontener logujący bez limitu albo rosnąca baza. Limity logów są w /etc/docker/daemon.json.

---

Rollback

Poziom 1 — konfiguracja usługi

cd /srv/apps/<projekt>
git log --oneline -10
git revert <commit>
docker compose up -d

Poziom 2 — wersja obrazu

Cofnij tag w compose.yaml do poprzedniej działającej wersji, docker compose up -d. Dlatego przypinamy wersje — z :latest nie masz do czego wrócić.

Poziom 3 — snapshot OVH

Przywrócenie snapshota cofa całą maszynę do stanu z chwili jego zrobienia. Wszystko, co powstało później — inne projekty, dane, commity — znika.

Zanim to zrobisz:

• Czy problem faktycznie wymaga cofnięcia całej maszyny?
• Co powstało od czasu snapshota i czego nieodwracalnie stracisz?
• Czy dasz radę wyciągnąć potrzebne dane przed przywróceniem?
• Data snapshota — jest w SERVER.md

To ostateczność. W większości przypadków szybciej jest naprawić usługę.

---

Odzyskanie dostępu po zablokowaniu SSH

Jeśli błąd w sshd_config albo ufw odciął Cię od maszyny:

1. Panel OVH → Twój VPS → konsola KVM
2. Logowanie jako root lub ubuntu (dlatego ubuntu ma ustawione hasło — przez konsolę klucz SSH nie pomoże)
3. Napraw konfigurację, sudo sshd -t, restart usługi
4. Test z zewnątrz przed zamknięciem konsoli

To jest powód, dla którego przy każdej zmianie w SSH trzymamy otwartą drugą sesję.

---

Utrata Gitei

Gitea stoi na tym samym serwerze, którym zarządza — więc jej awaria zabiera kod i konfigurację naraz. Dlatego:

• repo infra jest zmirrorowane na prywatne repo GitHuba
• na maszynie zawsze jest aktualna kopia robocza /srv/infra
• odtworzenie: sklonuj infra z GitHuba, postaw Traefika i Gitea z 00-bootstrap.md, krok 13, przywróć dane repozytoriów z backupu

Jeśli mirror na GitHub nie jest jeszcze skonfigurowany — to najpilniejsza rzecz z listy braków w SECURITY.md.

---

Po każdej awarii

• Wpis w dzienniku zmian w SERVER.md: co się stało, co pomogło
• Jeśli przyczyna była systemowa — dopisz punkt kontrolny do 40-utrzymanie.md
• Jeśli dało się temu zapobiec regułą — dopisz ją do CLAUDE.md

Runbooki mają rosnąć razem z doświadczeniem. Awaria, z której nic nie wynikło dla dokumentacji, powtórzy się.