Rozdział 11: Cykl wdrożeń, błędy i checklista nowego projektu
Ostatni rozdział to ściąga do codziennej pracy i do powtórzenia schematu w kolejnych projektach. Zbieramy w jednym miejscu: co robisz jednorazowo, a co przy każdym wdrożeniu, listę typowych błędów oraz gotową checklistę nowego projektu z parametrami do podmiany.
Po tym rozdziale potrafisz samodzielnie powtórzyć całe CI/CD w nowej aplikacji, korzystając z tego samego schematu.
Jednorazowe vs powtarzalne — pełne zestawienie
🔁 Jednorazowe (konfiguracja projektu/serwera)
| Czynność | Gdzie | Rozdział |
|---|---|---|
| Repo na GitHubie + klucz SSH lokalny | 💻🐙 | 2 |
Workflow CI (ci.yml) |
🐙 | 3 |
| Zakup i konfiguracja VPS + klucz SSH | 🖥️ | 4 |
| Domena + rekordy DNS | 🐙 | 5 |
| Provisioning (Docker/Nginx/SSL) | 🖥️ | 6 |
| Deploy Key (repo prywatne) + klon | 🖥️🐙 | 7 |
| Workflow Deploy + 3 sekrety + env + build frontu | 🐙 | 8 |
| Cron backupu | 🖥️ | 10 |
♻️ Powtarzalne (każde wdrożenie)
# 💻 lokalnie — to robisz na co dzień
git add .
git commit -m "feat: opis zmiany"
git push origin main
# → CI testuje, Deploy wdraża; (opcjonalnie) weryfikujesz stronę
To wszystko. Reszta dzieje się automatycznie.
Najczęstsze błędy — jedna tabela (master troubleshooting)
| Objaw | Najczęstsza przyczyna | Rozwiązanie / gdzie szukać |
|---|---|---|
CI czerwony: relation "trans_key" does not exist |
cache rozgrzewany przed utworzeniem bazy | kolejność kroków w CI (Rozdz. 3): migracje → cache:clear |
| CI czerwony: php-cs-fixer o wersji PHP | brak PHP_CS_FIXER_IGNORE_ENV |
dodaj zmienną (Rozdz. 3) |
CI czerwony: PHPStan „internal error" na OrderBy |
enum w #[ORM\OrderBy] wywala phpstan-doctrine |
zostaw stringi 'ASC'/'DESC' (patrz niżej) |
Deploy czerwony: ssh handshake/permission denied |
zły/niepełny VPS_SSH_KEY |
wklej cały prywatny <KLUCZ_LOKALNY> (Rozdz. 8) |
Deploy: git pull pyta o login |
prywatne repo bez Deploy Key w remote | klon przez git@github.com:... (Rozdz. 7) |
| Strona 502 | kontenery nie wstały | docker compose ... logs app na serwerze (Rozdz. 9) |
| Strona 500 | błąd aplikacji/migracji/env | logi app; sprawdź migracje i .env.local |
| Baza pusta/„password failed" | brak --env-file .env.local |
dodaj flagę do komend compose (Rozdz. 8/10) |
| Strona bez stylów (goły HTML) | front nie zbudowany/niezsynchronizowany | build w obrazie + cp public/build (Rozdz. 8) |
| Certbot: challenge failed | DNS nie wskazuje na serwer | dig +short <DOMENA> = <VPS_IP>, potem powtórz certbota (Rozdz. 5/6) |
🎯 Pułapki specyficzne dla FactoryCode (warto znać):
trans_keyprzy rozgrzewce cache — baza musi istnieć przedcache:clear(bo tłumaczenia ładują się z bazy).#[ORM\OrderBy(['x' => 'ASC'])]— nie zamieniaj'ASC'na enumOrder::Ascending: jest poprawny w runtime, alephpstan-doctrinesię na nim wywraca (CI pada). Deprecacja o „ASC as order by direction" jest nieszkodliwa (INFO).
Dlaczego deploy nie czeka na CI
W naszym układzie CI i Deploy startują równolegle po każdym pushu na main. Deploy nie czeka na zielone CI. To świadomy wybór:
- Prostota: dwa niezależne pliki, bez powiązań między workflowami.
- Te same bramki lokalnie: przed pushem uruchamiasz
make check, więc CI zwykle tylko to potwierdza. - Szybki rollback: gdy coś przejdzie mimo to, cofasz zmianę (sekcja niżej).
Koszt: jeśli wypchniesz kod, który nie przechodzi testów, trafi on na produkcję, a CI zaświeci się na czerwono dopiero po fakcie.
Jeśli chcesz, żeby deploy ruszał tylko po zielonym CI, zmień trigger w deploy.yml:
on:
workflow_run:
workflows: ["CI"]
types: [completed]
branches: [main]
jobs:
deploy:
if: ${{ github.event.workflow_run.conclusion == 'success' }}
runs-on: ubuntu-latest
🧩 Uniwersalnie: w małym projekcie z jedną osobą równoległy układ wystarcza. Gdy w projekcie pracuje więcej osób albo awaria jest kosztowna, uzależnij deploy od CI.
Jak cofnąć nieudane wdrożenie (rollback)
Najprostszy rollback przy tym układzie (serwer trzyma repo i buduje z niego):
# 💻 lokalnie — cofnij ostatni commit i wypchnij; deploy wdroży poprzedni stan
git revert HEAD
git push origin main
albo, awaryjnie, na serwerze przełącz kod na poprzedni commit i przebuduj:
# 🖥️ na serwerze
cd <APP_DIR>
git log --oneline -5 # znajdź dobry commit
git checkout <hash_dobrego_commita>
docker compose --env-file .env.local -f compose.yaml -f compose.prod.yaml up -d --build
⚠️ Po
git checkout <hash>kod na serwerze nie jest już na gałęzimain(tzw. detached HEAD). Gdy naprawisz błąd w repo, wróć na gałąź, zanim zrobisz kolejny push:cd <APP_DIR> && git checkout main. Inaczej następny automatyczny deploy (git pull origin main) zadziała na odłączonym commicie, a nie namain.
⚠️ Migracje bazy nie cofają się same. Jeśli nieudane wdrożenie wykonało migrację, rozważ
doctrine:migrations:migrate prevlub przywrócenie bazy z backupu (Rozdz. 10). Testuj migracje wcześniej.
Checklista nowego projektu (powtórzenie schematu) 🧩
Zakładając CI/CD w kolejnym projekcie, przejdź tę listę. W nawiasach parametry do ustalenia (patrz tabela w README).
Przygotowanie
- Projekt działa lokalnie (np. w Dockerze).
- Ustal parametry:
<REPO>,<DOMENA>,<APP_DIR>, nazwy kontenerów, komendy QA. - Repo na GitHubie; para kluczy
<KLUCZ_LOKALNY>wygenerowana.
CI
- Skopiuj
ci.yml; podmień komendy bramek i usługi (baza) na swój stack. - Push → CI zielony.
Infrastruktura (jednorazowo)
- VPS (Ubuntu LTS) + klucz SSH; zapisz
<VPS_IP>. - Domena → rekordy A/CNAME na
<VPS_IP>;digpotwierdza. - Dostosuj
setup-vps.sh(APP_DIR,REPO_URL, Nginx); uruchom na serwerze. - (Repo prywatne) Deploy Key + klon przez SSH.
CD
- Skopiuj
deploy.yml; dostosuj ścieżki, nazwy kontenerów, kroki stacku (migracje, build frontu). - Dodaj 3 sekrety:
VPS_HOST,VPS_USER,VPS_SSH_KEY. - Zadbaj o
.env.localna serwerze i--env-filew komendach compose. - (Front budowany) build w obrazie + sync assetów.
Uruchomienie i utrzymanie
- Pierwszy deploy (pusty commit) → zielony.
- Weryfikacja: HTTP 200, SSL, przekierowanie HTTP→HTTPS, assety 200.
- Cron backupu bazy; test ręczny backupu.
- (Opcjonalnie) backup off-site, poczta + SPF/DKIM.
Co jest 🧩 uniwersalne, a co 🎯 do podmiany — ostatnie przypomnienie
| Element | Uniwersalny? | Co podmieniasz |
|---|---|---|
Szkielet ci.yml / deploy.yml |
🧩 tak | komendy bramek, kroki stacku, ścieżki |
appleboy/ssh-action + 3 sekrety |
🧩 tak | wartości sekretów |
| Provisioning (Docker/Nginx/SSL) | 🧩 tak | APP_DIR, REPO_URL, domena/email |
| Deploy Key (prywatne repo) | 🧩 tak | (nic — procedura ta sama) |
Backup pg_dump + cron |
🧩 tak | nazwy plików/katalogów, nazwa serwisu bazy |
| Bramki jakości, migracje, build frontu | 🎯 nie | zależne od frameworka/stacku |
Podsumowanie całego tutoriala
- ✅ CI testuje kod przy każdym push (jakość).
- ✅ CD wdraża aplikację na VPS po push na
main(automatyzacja). - ✅ Infrastruktura: VPS + Docker + Nginx + SSL + DNS, postawiona skryptem.
- ✅ Bezpieczeństwo: sekrety poza kodem, Deploy Key read-only, backup bazy.
- ✅ Powtarzalność: znasz podział uniwersalne/specyficzne i masz checklistę do kolejnych projektów.
Gratulacje — przeszedłeś od zera do w pełni zautomatyzowanego wdrożenia i potrafisz powtórzyć ten schemat. 🎉
Wróć do spisu: README — spis rozdziałów.