11

Rozdział 11 z 11

Cykl wdrożeń, błędy i checklista nowego projektu

Opublikowany

Zestawienie jednorazowe vs powtarzalne, master-tabela błędów, rollback oraz gotowa checklista do wdrożenia CI/CD w kolejnym projekcie.

Czego się nauczysz

  • Jednorazowe vs powtarzalne
  • Najczęstsze błędy i rozwiązania
  • Rollback nieudanego wdrożenia
  • Checklista nowego projektu

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_key przy rozgrzewce cache — baza musi istnieć przed cache:clear (bo tłumaczenia ładują się z bazy).
  • #[ORM\OrderBy(['x' => 'ASC'])] — nie zamieniaj 'ASC' na enum Order::Ascending: jest poprawny w runtime, ale phpstan-doctrine się 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łęzi main (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 na main.

⚠️ Migracje bazy nie cofają się same. Jeśli nieudane wdrożenie wykonało migrację, rozważ doctrine:migrations:migrate prev lub 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>; dig potwierdza.
  • 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.local na serwerze i --env-file w 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.

Narzędzia / paczki

Git Docker Compose GitHub Actions

Spis treści