Rozwiązaniem jest globalny CLAUDE.md — trwały plik instrukcji, który uczy Claude'a, po które narzędzie sięgnąć w zależności od typu zapytania. Ten wpis opisuje mój setup, drzewo decyzyjne, które zbudowałem, i jak możesz stworzyć własne dla swojego stosu technologicznego.

Problem: za dużo narzędzi, brak strategii#

Serwery MCP dają Claude Code supermoce: automatyzację przeglądarki, śledzenie błędów, wyszukiwanie dokumentacji, integrację z IDE. Ale więcej narzędzi oznacza więcej wyborów, a bez wskazówek Claude podejmuje rozsądne, ale nieoptymalne decyzje.

Typowe problemy, które zaobserwowałem:

• Złe narzędzie do zadania — odpytywanie Context7 o "najnowszą wersję Symfony" (ma tylko dokumentację, nie metadane o wydaniach) zamiast Perplexity
• Droga ścieżka zamiast taniej — używanie Grepa do szukania route'ów Symfony w wielu plikach zamiast zapytania JetBrains MCP o strukturalną listę
• Pominięcie specjalisty — brak sprawdzenia Sentry przy błędzie produkcyjnym, kiedy stack trace natychmiast ujawniłby przyczynę
• Zbędne zapytania — próbowanie wielu narzędzi po kolei, kiedy pamięć mogłaby od razu skierować do właściwego

Rozwiązaniem są jawne reguły routingu zapisane w globalnym CLAUDE.md. Claude czyta ten plik na początku każdej sesji, więc drzewo decyzyjne jest zawsze dostępne.

Mój stos MCP#

Oto sześć serwerów MCP, których używam, i w czym każdy jest najlepszy.

Context7 — dokumentacja bibliotek i frameworków#

Context7 serwuje wersjonowaną dokumentację z przykładami kodu. Podajesz nazwę biblioteki i pytanie, a on zwraca odpowiednią sekcję z oficjalnej dokumentacji.

Workflow: resolve-library-id (znajdź bibliotekę) → query-docs (pobierz dokumentację do konkretnego pytania). Obsługuje wersjonowane zapytania — mogę odpytać /sylius/sylius/v1.14.6 bezpośrednio, nie tylko "latest".

Najlepszy do:

• Sygnatur metod i przykładów konfiguracji
• Poradników migracji między wersjami frameworków
• Wzorców z oficjalnej dokumentacji (formularze Symfony, mapowania Doctrine, filtry API Platform)

Nie radzi sobie z:

• Aktualnymi numerami wersji i datami wydań (ma dokumentację, nie metadane)
• Funkcjami języka PHP (PHP nie jest biblioteką z wersjonowaną dokumentacją w Context7)
• Poradnikami bezpieczeństwa i CVE
• Czymkolwiek wymagającym informacji w czasie rzeczywistym

Perplexity — aktualne fakty i research#

Perplexity to wyszukiwarka z AI w czterech trybach: search (wyniki z cytatami ze źródeł), ask (odpowiedzi AI przez sonar-pro), research (dogłębna analiza wieloźródłowa, 30+ sekund) i reason (logiczne rozumowanie krok po kroku).

Najlepszy do:

• Najnowszych numerów wersji, dat wydań, harmonogramów EOL
• Poradników bezpieczeństwa i szczegółów CVE
• Funkcji języka PHP i RFC (property hooks, asymmetric visibility — tego nie ma w Context7)
• Cen usług zewnętrznych (koszty API, porównania hostingów)
• Ogólnych dobrych praktyk programistycznych i benchmarków

Kluczowa rola: Perplexity wypełnia każdą lukę Context7. Kiedy Context7 nic nie zwraca albo zwraca nieaktualne dane, Perplexity prawie zawsze ma odpowiedź.

JetBrains — inteligencja kodu na poziomie IDE#

To serwer MCP, który oszczędza najwięcej tokenów. JetBrains MCP łączy Claude Code z indeksem Twojego IDE — tym samym, który napędza autouzupełnianie, go-to-definition i refaktoryzację. Bazowy JetBrains MCP dostarcza generyczne narzędzia (wyszukiwanie plików, lookup symboli, wyszukiwanie tekstowe, komendy terminala), a pluginy frameworkowe rozszerzają go o specjalistyczne narzędzia — plugin Symfony dodaje listowanie route'ów, wyszukiwanie serwisów, inspekcję encji Doctrine i analizę Twiga.

Mój typowy workflow: Wklejam link do ticketu Jira do konwersacji. Claude czyta zadanie przez Atlassian MCP, a potem używa JetBrains MCP do szybkiego rekonesansu kodu — znajdując odpowiednie serwisy, sprawdzając definicje route'ów, inspekcjonując pola encji — zanim napisze choćby jedną linię kodu. Ten krok "najpierw przeanalizuj" wyłapuje nieporozumienia wcześnie i daje Claude'owi kontekst do zadawania lepszych pytań wyjaśniających.

Możliwości specyficzne dla Symfony (przez plugin Symfony):

• list_symfony_routes_controllers — wszystkie route'y z kontrolerem, ścieżką, metodami. Jedno wywołanie zamiast grepowania atrybutów w dziesiątkach plików
• locate_symfony_service — znajdź definicję dowolnego serwisu po pełnej nazwie klasy
• list_doctrine_entity_fields — pola encji, typy i relacje w ustrukturyzowanym formacie
• list_symfony_commands, list_symfony_forms — komendy konsolowe i typy formularzy w jednym widoku

Przykład oszczędności tokenów: Znalezienie wszystkich route'ów pasujących do /api/ w projekcie Symfony:

• Bez JetBrains: Grep po #[Route w src/Controller/, odczyt każdego pasującego pliku, parsowanie atrybutów route'ów, konfrontacja z _routes.yaml. Łatwo 5-10 wywołań narzędzi i tysiące tokenów treści plików.
• Z JetBrains: Jedno wywołanie list_symfony_routes_controllers zwraca strukturalną, filtrowalną listę. Gotowe.

Przydatny też do: Indeksowane wyszukiwanie tekstowe (search_in_files_by_text), wyszukiwanie plików po nazwie, lookup symboli, uruchamianie komend terminala w IDE, budowanie i testowanie.

Chrome DevTools — automatyzacja przeglądarki#

Chrome DevTools MCP pozwala Claude'owi sterować przeglądarką: nawigować po URL-ach, klikać elementy, wypełniać formularze, robić zrzuty ekranu, inspekcjonować żądania sieciowe, uruchamiać JavaScript i wykonywać audyty Lighthouse.

Najlepszy do:

• Wizualnego testowania zmian UI po modyfikacji szablonów lub CSS
• Audytów wydajności i dostępności Lighthouse
• Debugowania problemów frontendowych (błędy w konsoli, żądania sieciowe)
• Weryfikacji responsywności przy różnych szerokościach viewportu

Sentry — śledzenie błędów produkcyjnych#

Sentry MCP łączy Claude'a z systemem śledzenia błędów. Może wyszukiwać issues, pobierać stack trace'y, analizować błędy z AI Sentry (Seer) i sprawdzać informacje o wydaniach i wdrożeniach.

Workflow, który sprawia, że to jest wartościowe:

1. Zauważasz błąd (lub zgłasza go użytkownik)
2. Claude odpytuje Sentry: "wyszukaj błędy 500 z ostatnich 24 godzin"
3. Sentry zwraca stack trace, liczbę dotkniętych użytkowników, timestampy first/last seen
4. Claude czyta odpowiedni plik źródłowy, identyfikuje przyczynę i proponuje fix
5. Cały cykl debugowania odbywa się bez opuszczania terminala

Najlepszy do:

• Badania błędów produkcyjnych z pełnymi stack trace'ami
• Rozumienia częstotliwości i wzorców błędów (czy jest nowy? czy się pogarsza?)
• Korelowania błędów z ostatnimi wdrożeniami

Atlassian/Jira — zarządzanie zadaniami#

Jira MCP zapewnia pełne zarządzanie cyklem życia issues: tworzenie, odczyt, edycję, przejścia statusów, komentowanie i wyszukiwanie JQL.

Najlepszy do:

• Czytania specyfikacji zadań przed rozpoczęciem pracy
• Aktualizowania statusu issues w trakcie pracy
• Dodawania technicznych komentarzy do issues dla widoczności zespołu
• Wyszukiwania JQL do znajdowania powiązanych issues lub sprawdzania bieżącego sprintu

Drzewo decyzyjne#

Sercem globalnego CLAUDE.md jest tablica routingu, która mapuje typy zapytań na najlepsze narzędzie. Oto faktyczna treść z mojego pliku:

## Search & Research — Tool Decision Tree

### When to use Context7
**Best for**: library/framework API docs with clean code examples
- Versioned library docs (Sylius, Doctrine, API Platform, Symfony, GitHub Actions)
- Official method signatures, configuration examples, how-to patterns
- Concise, authoritative answers directly from official source
- `resolve-library-id` first, then `query-docs`
- **Fails for**: current version/release info, PHP language features,
  security CVEs, pricing, general programming

### When to use Perplexity
**Best for**: anything current, factual, or not a library doc
- Latest versions, release dates, EOL schedules
- Security advisories, CVEs, vulnerability details
- PHP language features (property hooks, new syntax)
- External service pricing
- General programming best practices, benchmarks
- Supplement when Context7 fails or for real-world context

### When to use WebSearch
- Official blog posts / release announcements
- As last resort or to supplement

Kluczowy wzorzec: każda sekcja zaczyna się od "best for" (kiedy wybrać to narzędzie) i kończy "fails for" (kiedy je pominąć). Claude korzysta z obu sygnałów — routingu pozytywnego i negatywnego.

Tablica benchmarków#

Przepuściłem te same 10 typów zapytań przez Context7, Perplexity i WebSearch i oceniłem wyniki. Ta tablica znajduje się w globalnym CLAUDE.md, żeby Claude mógł się do niej odwoływać przy podejmowaniu decyzji:

Wzorzec jest czytelny: Context7 jest doskonały do wersjonowanej dokumentacji, ale dostaje zero w czymkolwiek wymagającym aktualnych lub rzeczywistych danych. Perplexity pokrywa niemal wszystko. WebSearch jest najsilniejszy w blogpostach i ogłoszeniach o wydaniach.

Umieszczenie tej tabeli w globalnym CLAUDE.md daje Claude'owi ilościową podstawę do wyboru narzędzia, nie tylko reguły.

Jak działa globalna pamięć#

Claude Code obsługuje globalny plik instrukcji w ~/.claude/CLAUDE.md. Ten plik jest ładowany na początku każdej konwersacji, niezależnie od projektu. To właściwe miejsce na reguły routingu narzędzi, bo serwery MCP są konfigurowane globalnie, nie per projekt.

Porównanie z projektowym AGENTS.md:

Struktura globalnego CLAUDE.md#

Globalny CLAUDE.md działa najlepiej, gdy jest ustrukturyzowany jak podręcznik referencyjny, nie narracja. Claude skanuje go na początku sesji — czytelne nagłówki i jawne reguły sprawiają, że ten skan jest skuteczny.

Wskazówki z mojego doświadczenia:

1. Zacznij od reguły decyzyjnej, nie od opisu. "Best for: versioned library docs" jest bardziej użyteczne niż "Context7 is a documentation server that..."
2. Uwzględnij tryby awarii. "Fails for: current versions" zapobiega próbom użycia Context7 do zapytań, z którymi sobie nie radzi.
3. Dodaj inwentarz serwerów. Wymień każdy serwer MCP z jego narzędziami — Claude może się do tego odwołać, gdy potrzebuje funkcji, której jeszcze nie używał.
4. Używaj konkretnych przykładów. "Latest Symfony version → Perplexity" jest lepsze niż "use Perplexity for current data."
5. Aktualizuj przy zmianach narzędzi. Dodałeś nowy serwer MCP? Zaktualizuj plik. Usunąłeś jeden? Usuń jego wpis. Nieaktualne reguły routingu są gorsze niż brak reguł.

Zbuduj własne drzewo#

Konkretne serwery MCP nie mają znaczenia — liczy się wzorzec. Niezależnie od tego, czy używasz Cursora, Windsurf czy Claude Code, czy piszesz w Pythonie czy Go, zasada jest ta sama: naucz swojego asystenta AI, po które narzędzie sięgnąć.

Krok po kroku:

1. Wymień swoje serwery MCP (lub równoważne integracje narzędziowe) i do czego każdy służy
2. Zidentyfikuj nakładanie się — gdzie dwa narzędzia mogą odpowiedzieć na to samo zapytanie? (Context7 i Perplexity obsługują dokumentację Symfony, ale z różnymi mocnymi stronami)
3. Zbenchmarkuj — przepuść te same 5-10 reprezentatywnych zapytań przez każde nakładające się narzędzie. Oceń wyniki. To daje dane, nie przeczucie.
4. Napisz reguły routingu — dla każdego narzędzia napisz sekcje "best for" i "fails for" z konkretnymi typami zapytań
5. Dołącz benchmark — tablica daje Twojemu AI ilościowy punkt odniesienia, nie tylko instrukcje
6. Iteruj — pierwsza wersja nie będzie idealna. Kiedy Claude wybierze złe narzędzie, zaktualizuj plik. Po kilku sesjach routing się doszlifuje.

Mój globalny CLAUDE.md zaczął się jako lista serwerów MCP z jednolinijkowymi opisami. Po kilku tygodniach obserwacji, gdzie Claude podejmował nieoptymalne wybory, ewoluował w drzewo decyzyjne opisane powyżej. Tablica benchmarków była największą pojedynczą poprawą — zamieniła niejasne reguły "preferuj X nad Y" w konkretne dane, na podstawie których Claude mógł działać.

Inwestycja jest niewielka (godzina na konfigurację, kilka minut na aktualizację) a zwrot się kumuluje: mniej zmarnowanych tokenów, szybsze odpowiedzi i mniej czasu na korygowanie wyborów narzędzi w trakcie konwersacji.

holas.pl jest stroną statyczną z jednym wyjątkiem: formularzem kontaktowym. Każdy wpis blogowy, strona kategorii i strona statyczna to wstępnie wyrenderowany plik HTML serwowany przez nginx. Formularz kontaktowy to jedyny endpoint uruchamiający PHP.

To jedno wyjście rodzi konkretne pytanie bezpieczeństwa: jak chronić formularz na stronie statycznej przed botami i atakami CSRF, gdy nie ma sesji?

Problem CSRF na stronach statycznych#

Standardowa ochrona CSRF działa przez osadzenie tokena w formularzu powiązanego z sesją użytkownika. Przy przesyłaniu formularza serwer weryfikuje, czy token pasuje do tego z sesji.

Strony statyczne nie mają sesji. Strona kontaktowa jest generowana raz podczas ddev build i serwowana jako plik. Nie może generować tokena per użytkownik w czasie renderowania. Wbudowana csrf_protection Symfony jest więc jawnie wyłączona w formularzu kontaktowym:

public function configureOptions(OptionsResolver $resolver): void
{
    $resolver->setDefaults([
        'csrf_protection' => false,  // celowe — strona statyczna, brak sesji
    ]);
}

Wyłączenie ochrony CSRF to właściwa decyzja. Alternatywa — dodanie dynamicznego endpointu PHP tylko do generowania tokenów dla formularza — przywróciłaby problem PHP-przy-każdym-żądaniu dla strony, która poza tym go nie potrzebuje.

Cloudflare Turnstile jako zamiennik#

Cloudflare Turnstile to alternatywa dla CAPTCHA działająca po stronie klienta, potwierdzająca człowieczeństwo użytkownika i dostarczająca jednorazowy token weryfikowalny po stronie serwera. Zastępuje CSRF jako warstwa zapobiegania botom.

Przepływ formularza:

1. Strona kontaktowa jest serwowana jako statyczny HTML z osadzonym widżetem Turnstile (klucz strony jest wbudowany podczas buildu)
2. Turnstile uruchamia swoje wyzwanie niewidocznie; po sukcesie wywołuje window.onTurnstileSuccess(token), który zapisuje token do ukrytego pola
3. contact.js przechwytuje zdarzenie submit formularza i wysyła dane przez fetch() zamiast standardowego wysłania formularza
4. Endpoint PHP otrzymuje przesłanie, weryfikuje pola formularza, następnie weryfikuje token Turnstile przez API Cloudflare
5. Tylko jeśli oba sprawdzenia przejdą, e-mail jest wysyłany

Weryfikacja po stronie serwera to kluczowy krok:

final class TurnstileValidator
{
    public function verify(string $token, string $remoteIp): bool
    {
        try {
            $response = $this->httpClient->request('POST', 'https://challenges.cloudflare.com/turnstile/v0/siteverify', [
                'body' => [
                    'secret'   => $this->secretKey,
                    'response' => $token,
                    'remoteip' => $remoteIp,
                ],
            ]);

            $data = $response->toArray();

            return true === ($data['success'] ?? false);
        } catch (\Throwable $e) {
            $this->logger->error('Weryfikacja Turnstile nie powiodła się: '.$e->getMessage());

            return false;
        }
    }
}

Walidator zawodzi bezpiecznie — każdy wyjątek zwraca false i blokuje przesłanie. Pusty lub brakujący token również zwraca false natychmiast.

Minimalna powierzchnia ataku PHP#

Cała powierzchnia PHP aplikacji w produkcji to dwa wzorce URL:

location ~ ^/(api|pl/api)/ {
    fastcgi_pass $php_upstream;
    fastcgi_read_timeout 30;
}

Wszystko inne — każdy wpis blogowy, każda strona kategorii, mapa strony, kanał RSS, strona wyszukiwania — jest obsługiwane przez nginx serwujący pliki statyczne. PHP-FPM nie jest nigdy wywoływane przy dostarczaniu treści. Powierzchnia ataku warstwy PHP to jeden endpoint POST.

Content Security Policy#

Konfiguracja nginx stosuje rygorystyczny CSP przy każdej odpowiedzi:

add_header Content-Security-Policy
    "default-src 'self';
     script-src  'self' challenges.cloudflare.com;
     style-src   'self' 'unsafe-inline';
     img-src     'self' data:;
     frame-src   challenges.cloudflare.com;
     connect-src 'self' challenges.cloudflare.com;"
    always;

Jedyną dozwoloną zewnętrzną domeną jest challenges.cloudflare.com, której Turnstile wymaga dla swojego skryptu, iframe i wywołania API. Brak Google Analytics, skryptów CDN, piksela Facebooka. script-src nie ma 'unsafe-inline' ani 'unsafe-eval' — cały JavaScript jest ładowany z plików z hashami przez Symfony AssetMapper.

'unsafe-inline' w style-src to celowy kompromis: widżet Turnstile wstrzykuje style inline, których nie można uniknąć bez nonce CSP, a AssetMapper aktualnie nie wstrzykuje nonces. Wszystko inne jest zablokowane.

Dodatkowe nagłówki bezpieczeństwa#

add_header X-Frame-Options        "SAMEORIGIN"                       always;
add_header X-Content-Type-Options "nosniff"                          always;
add_header Referrer-Policy        "strict-origin-when-cross-origin"  always;
add_header Permissions-Policy     "camera=(), microphone=(), geolocation=()" always;

Ukryte pliki są blokowane:

location ~ /\. { deny all; }

HSTS jest obsługiwane przez Cloudflare, więc nie ma nagłówka Strict-Transport-Security w konfiguracji nginx — byłby zbędny.

Wynik#

Formularz kontaktowy działa bez sesji, bez tokenów CSRF i bez JavaScriptu wymaganego do czegokolwiek poza samym wysłaniem formularza. Strona renderuje się w pełni jako statyczny HTML. Przesłania botów są blokowane przez weryfikację Turnstile po stronie serwera. Endpoint PHP jest nieosiągalny dla czegokolwiek poza żądaniami POST do /api/contact.

W porównaniu z WordPressem z wtyczką formularza kontaktowego, powierzchnia ataku zmalała z "PHP działającego przy każdym żądaniu, wp-admin wystawione, XML-RPC włączone, 22 wtyczki, każda mogąca mieć lukę" do "jeden endpoint POST z weryfikacją Cloudflare".

Następny wpis opisuje środowisko deweloperskie — DDEV, pipeline buildu i deployment do produkcji w dwóch kontenerach Docker.

Kod jest open-source na licencji Apache 2.0 — zobacz GitHub / notACMS. Zawiera 368 testów PHPUnit, CI/CD przez GitHub Actions i wzorzec lokalnych nadpisań który pozwala użytkownikom customizować szablony, CSS i tłumaczenia bez forkowania.

Architektura#

Cała treść żyje w plikach Markdown z YAML frontmatterem:

content/
├── blog/
│   └── tutorials/
│       └── my-post/
│           ├── en.md   ← wersja angielska
│           ├── pl.md   ← wersja polska
│           └── files/  ← obrazki, serwowane z /media/my-post/
└── pages/
    └── about/
        ├── en.md
        └── pl.md

ContentTreeBuilder skanuje system plików, parsuje każdy plik przez league/commonmark (GitHub Flavoured Markdown + YAML frontmatter) i buduje typowane ContentTree — indeks w pamięci wszystkich postów i stron dla danego locale. Tagi, kategorie, miesiące archiwum i mapy URL są obliczane z tego indeksu.

Statyczny build używa sub-requestów Symfony: HttpKernelInterface::handle() z SUB_REQUEST renderuje każdy URL przez pełny kernel bez dotykania sieci. Jeśli URL działa w development, będzie w buildzie statycznym. Brak osobnego silnika szablonów, brak konfiguracji buildu.

Kluczowe funkcje#

• Wielojęzyczność — sparowane en.md + pl.md w tym samym katalogu, automatyczne mapowanie tłumaczeń, tagi hreflang, przełącznik języka
• Wyszukiwarka — statyczny indeks oparty na WASM przez Pagefind, po stronie klienta, bez Elasticsearch ani Algolia
• Responsywne obrazki — automatyczne generowanie srcset przez ImageMagick, konfigurowalne szerokości wariantów
• Drafty i zaplanowane posty — dev-only przełączniki podglądu, zaplanowane posty publikowane automatycznie w czasie buildu
• Formularz kontaktowy — Cloudflare Turnstile CAPTCHA, ciasny CSP, pojedynczy endpoint POST
• Styleguide — strona tylko dla dev dokumentująca każdy komponent z prawdziwymi klasami CSS
• Wzorzec lokalnych nadpisań — katalog local/ scala się na bazę w czasie buildu, customizacja bez forkowania

Stos technologiczny#

• PHP 8.5, Symfony 7.x
• Szablony Twig, SCSS (dart-sass przez symfonycasts/sass-bundle)
• Symfony AssetMapper (bez webpacka, bez Vite, bez pipeline'u Node.js)
• nginx + PHP-FPM (dwa kontenery Docker na produkcji)
• Pagefind do wyszukiwania
• PHPUnit 13, PHPStan level 6, Rector, PHP CS Fixer

Dlaczego go zbudowałem?#

Hugo, Jekyll i Eleventy były oczywistymi kandydatami. Wybrałem budowę customowej aplikacji Symfony bo znam Symfony dobrze, a posiadanie pełnego stacka okazało się mieć realne zalety: te same szablony, kontrolery i pipeline treści obsługują zarówno development jak i produkcję. Nie ma "silnika szablonów build-time" oddzielonego od "silnika szablonów runtime." To po prostu Symfony.

Pełna historia dlaczego WordPress musiał odejść jest w Dlaczego odszedłem od WordPressa. Głębokie zanurzenie w architekturę jest w Symfony jako generator statycznych stron.

Open Source#

notACMS jest dostępny na GitHubie na licencji Apache 2.0. Przygotowanie do wydania — testy, audyt AI, poprawki bezpieczeństwa, wzorzec lokalnych nadpisań — jest udokumentowane w serii o open-source.

Po podjęciu decyzji o odejściu od WordPressa pytanie brzmiało: czym go zastąpić? Hugo, Jekyll i Eleventy były oczywistymi kandydatami. Zdecydowałem się zbudować własną aplikację Symfony — nie dlatego, że istniejące narzędzia są niewystarczające, ale dlatego, że Symfony znam dobrze, a posiadanie pełnego stosu okazało się mieć realne zalety.

Podstawowa idea#

Strona działa w dwóch trybach:

• Deweloperski — Symfony obsługuje żądania dynamicznie. Edytujesz plik Markdown, odświeżasz przeglądarkę, widzisz wynik. Standardowy workflow developerski Symfony z paskiem profilera.
• Build produkcyjny — jedno polecenie konsolowe renderuje każdy URL do pliku HTML na dysku. nginx serwuje te pliki bezpośrednio. PHP nie jest wywoływane przy dostarczaniu treści.

Te same szablony, kontrolery i pipeline treści obsługują oba tryby. Nie ma osobnego "silnika szablonów do budowania" oddzielnego od "silnika szablonów do działania". To po prostu Symfony.

Pipeline treści#

Cała treść mieszka w plikach Markdown z nagłówkiem YAML:

content/
├── blog/
│   └── tutorials/
│       └── moj-wpis/
│           ├── en.md   ← wersja angielska
│           ├── pl.md   ← wersja polska
│           └── files/  ← obrazy, serwowane pod /media/moj-wpis/
└── pages/
    └── about/
        ├── en.md
        └── pl.md

ContentTreeBuilder skanuje system plików, parsuje każdy plik przez league/commonmark (GitHub Flavoured Markdown + nagłówki YAML) i buduje typowany ContentTree — indeks w pamięci wszystkich wpisów i stron dla danego locale. Tagi, kategorie, miesiące archiwum i mapy URL są wyliczane z tego indeksu.

ContentItem to obiekt wartości final readonly. Brak bazy danych, ORM, migracji. Dodanie wpisu oznacza stworzenie katalogu z dwoma plikami Markdown i uruchomienie buildu.

Polecenie build — sub-żądania Symfony#

Build statyczny używa techniki specyficznej dla Symfony, która odróżnia to podejście od Hugo czy Jekylla: wywołuje HttpKernelInterface::handle() w celu tworzenia sub-żądań — wewnętrznych wywołań PHP przechodzących przez pełne jądro Symfony bez dotyku sieci.

$request = Request::create($url);
$request->attributes->set('_static_build', true);
$response = $this->kernel->handle($request, HttpKernelInterface::SUB_REQUEST, false);

if ($response->getStatusCode() < 400) {
    file_put_contents($outputPath, $response->getContent());
}

Dla każdego URL — wpisów blogowych, stron kategorii, stron tagów, miesięcy archiwum, stron statycznych, stron błędów, kanałów RSS, mapy strony — polecenie build tworzy żądanie, przepuszcza je przez Symfony i zapisuje HTML na dysk. URL /blog/ staje się public/static/blog/index.html. URL /sitemap.xml staje się public/static/sitemap.xml.

Brak osobnego silnika szablonów do nauki. Brak konfiguracji buildu. Jeśli URL działa w developmencie, będzie w statycznym buildzie.

nginx serwuje wszystko#

W produkcji nginx obsługuje całe dostarczanie treści:

location / {
    try_files /static$uri/index.html /static$uri/index.xml /static$uri $uri =404;
}

# PHP tylko dla formularza kontaktowego
location ~ ^/(api|pl/api)/ {
    fastcgi_pass $php_upstream;
}

Dla każdego przychodzącego URL nginx najpierw próbuje wstępnie wyrenderowanego pliku HTML. PHP-FPM jest wywoływane tylko dla /api/contact — jedynego dynamicznego endpointu. Każdy wpis blogowy, lista kategorii, strona tagów i strona statyczna to plik serwowany bezpośrednio z dysku. Raspberry Pi 5 obsługuje to banalnie.

Bez bazy danych#

Drzewo treści jest budowane z plików Markdown podczas budowania. W produkcji jest cache'owane bez ograniczeń czasowych w cache'u systemu plików Symfony (unieważniane i przebudowywane przy każdym deployu). W developmencie jest przebudowywane przy każdym żądaniu, żeby zmiany plików były natychmiast widoczne.

Brak MySQL, schematu, migracji, connection poolingu, wolnych zapytań. Dodawanie treści oznacza tworzenie plików i uruchamianie ddev build. Usuwanie treści oznacza usuwanie plików. Cała historia strony jest w gicie.

Wielojęzyczność bez bazy danych#

Zarówno polska, jak i angielska treść mieszka w tym samym katalogu:

content/blog/tutorials/moj-wpis/
    en.md  → slug: "blog/my-post"     → /blog/my-post/
    pl.md  → slug: "wpisy/moj-wpis"   → /pl/wpisy/moj-wpis/
    files/ → obrazy serwowane pod /media/moj-wpis/

Współlokalizacja to link translacji. Dwa pliki locale w tym samym katalogu są automatycznie traktowane jako tłumaczenia siebie nawzajem. TranslationMapBuilder buduje {directoryKey → {locale → url}} dla tagów hreflang i przełącznika języka. Bez pola translation_key, bez tabeli łączącej, bez synchronizacji do zarządzania.

Wyszukiwanie z Pagefind#

Wyszukiwanie to oparty na WASM statyczny indeks budowany przez Pagefind po wygenerowaniu plików HTML:

npx pagefind --site public/static --output-path public/pagefind

Pagefind czyta wstępnie wyrenderowany HTML, indeksuje regiony data-pagefind-body i generuje binarny indeks w public/pagefind/. Strona wyszukiwania ładuje ten indeks po stronie klienta przez dynamiczny import(). Brak Elasticsearch, Algolii, zapytań wyszukiwania po stronie serwera. Indeks to zbiór plików statycznych.

Prostota redesignu#

Zmiana wyglądu strony oznacza edycję szablonów Twig i SCSS. Brak biblioteki komponentów React do aktualizacji. Brak pipeline'u Node.js. Brak hierarchii motywów WordPress. Cały frontend to:

• assets/styles/app.scss — jeden punkt wejścia importujący pliki częściowe
• templates/ — szablony Twig
• symfonycasts/sass-bundle — kompiluje SCSS przez dart-sass, bez Node.js

Żeby zmienić schemat kolorów: edytuj _variables.scss. Żeby zmienić layout: edytuj szablon Twig. Uruchom ddev build i gotowe.

Kompromisy#

Głównym kompromisem w porównaniu z Hugo czy Jekyllem jest to, że to własny kod — ja go utrzymuję. Zaletą jest to, że jest dokładnie tym, czego potrzebuję, niczym więcej. Brak ekosystemu wtyczek do nawigowania, brak ścieżki aktualizacji do martwienia się, brak feature flag dla rzeczy, których nigdy nie użyję.

Jedyna naprawdę dynamiczna funkcja — formularz kontaktowy — jest omówiona w następnym wpisie.

To pierwszy wpis z serii dokumentującej migrację do własnego generatora stron statycznych opartego na Symfony. Kolejne wpisy omawiają architekturę, formularz kontaktowy, środowisko deweloperskie i budowanie strony z pomocą AI.

Taśmociąg aktualizacji#

WordPress regularnie wydaje aktualizacje bezpieczeństwa. Wtyczki wydają aktualizacje niezależnie. Motywy też. W spokojnym tygodniu miałem trzy pozycje w kolejce. W gorszy tydzień — piętnaście. Każda wymagała:

1. Kopii zapasowej bazy danych i plików
2. Zastosowania aktualizacji
3. Sprawdzenia, czy nic się nie posypało

Ten ostatni krok to największy problem. Wtyczki WordPressa wchodzą ze sobą w interakcje w sposób niemożliwy do przewidzenia. Aktualizacja wtyczki do cache'owania psuła wyniki wtyczki SEO. Aktualizacja wtyczki SEO zmieniała sposób generowania map strony. Każda aktualizacja to mały hazard.

Dla portfolio z wpisem co kilka miesięcy ten narzut na utrzymanie jest absurdalny.

Dziesiątki wtyczek do podstawowych funkcji#

Świeża instalacja WordPressa nie robi prawie nic. Żeby prowadzić przyzwoite portfolio blogowe, potrzebowałem wtyczek do:

• SEO — Yoast lub Rank Math, z własnym interfejsem, ustawieniami i cyklem aktualizacji
• Cache'owania — W3 Total Cache lub WP Super Cache, ze skomplikowaną konfiguracją
• Bezpieczeństwa — Wordfence lub podobna, skanowanie intruzji, blokowanie IP, codzienne raporty
• Formularza kontaktowego — Contact Form 7 lub Gravity Forms
• Kopii zapasowych — UpdraftPlus lub podobna, zwykle wysyłająca dane do zewnętrznego serwisu
• Wydajności — optymalizacja obrazów, lazy loading, minifikacja
• SMTP — bo WordPress domyślnie wysyła e-maile przez mail() w PHP, które trafiają do spamu

Każda wtyczka to kod, którego nie kontroluję, utrzymywany przez kogoś innego, potencjalnie porzucony jutro, działający przy każdym wczytaniu strony.

Kiedy zacząłem planować migrację, miałem 22 aktywne wtyczki.

Ataki botów i problemy z logowaniem#

Strona logowania do WordPressa jest dobrze znana botom. URL to zawsze /wp-admin/ lub /wp-login.php. Każdy bot w internecie to wie. Efekt: ciągłe próby włamania przez brute-force, przez całą dobę.

Wordfence ograniczał próby logowania, blokował podejrzane IP i wysyłał mi codzienne raporty o atakach. Działało — ale to kolejny element pochłaniający zasoby serwera na stronie, która w ogóle nie potrzebuje logowania użytkowników. Jedyną osobą logującą się byłem ja, raz w miesiącu.

XML-RPC to kolejny wektor ataku. WordPress domyślnie go włącza dla pingbacków i aplikacji mobilnej. Boty ciągle go sondują. Rozwiązaniem była reguła nginx blokująca ten endpoint — ale dowiedziałem się o tym dopiero po zobaczeniu ruchu w logach.

PHP i MySQL na Raspberry Pi#

holas.pl działa na własnym sprzęcie — najpierw Banana Pi, teraz Raspberry Pi 5. To sprawne płyty ARM, ale nie są maszynami serwerowymi. Uruchamianie PHP-FPM i MySQL jednocześnie dla bloga, który zmienia się raz w miesiącu, to czyste marnotrawstwo.

Typowe wczytanie strony WordPress na tym sprzęcie: PHP przetwarza żądanie, MySQL wykonuje kilka zapytań po treść wpisu, dane nawigacji, widżety paska bocznego i opcje strony, PHP renderuje szablony, każda aktywna wtyczka wykonuje swoje hooki. Wszystko to dla treści identycznej z poprzednim żądaniem i identycznej z następnym.

Ze stroną statyczną nginx serwuje wstępnie wyrenderowany plik HTML bezpośrednio z dysku. Procesor ARM ledwo się budzi. Strony ładują się szybciej niż WordPress zdążył przetworzyć żądanie.

Baza danych jako ryzyko#

Dziewiętnaście lat WordPressa to baza danych z tysiącami wierszy metadanych wpisów, opcji, rewizji i transientów. Wymaga:

• Regularnych kopii zapasowych (i testowania, że przywracanie faktycznie działa)
• Okazjonalnego czyszczenia — WordPress gromadzi śmieci: rewizje wpisów, wygasłe transienty, osierocone wiersze metadanych
• Monitorowania pod kątem uszkodzeń po nieoczystym wyłączeniu
• Ciągle działającego procesu MySQL, zużywającego pamięć

Portfolio blog to zbiór tekstów i obrazów. Przechowywanie go w relacyjnej bazie danych dodaje złożoności operacyjnej bez dodawania wartości.

Co zostało zachowane#

Treść. Wszystkie 26 wpisów zostało wyeksportowanych i przekonwertowanych do plików Markdown — tytuły, daty, kategorie, tagi, obrazy. Adresy URL zostały zachowane dokładnie: 25 indywidualnych przekierowań wpisów i 43 przekierowania ścieżek obrazów jest teraz wbudowanych w konfigurację nginx. Pozycje w wyszukiwarce przetrwały migrację nienaruszone.

Wszystko inne — baza danych, wtyczki, kolejka aktualizacji, strona logowania /wp-admin/ — zniknęło.

Następny wpis opisuje, co zastąpiło WordPressa: własna aplikacja Symfony generująca statyczne pliki HTML, serwowane przez nginx bez udziału PHP w dostarczaniu treści do odwiedzających.

Traefik to reverse proxy zaprojektowany dla środowisk kontenerowych. Obserwuje Docker socket, wykrywa uruchomione kontenery i automatycznie pobiera certyfikaty Let's Encrypt — bez certbota, bez crona, bez ręcznej konfiguracji per domena.

Konfiguracja składa się z dwóch części: jedna instancja Traefik działająca cały czas na serwerze oraz etykiety przy każdej usłudze, które mówią Traefik jak routować ruch i dla jakiej domeny wystawić certyfikat.

Część 1 — docker-compose.yml dla Traefik#

Uruchamiany raz na serwerze. Wszystkie pozostałe usługi przechodzą przez niego.

services:
    traefik:
        image: traefik:${TRAEFIK_VERSION}
        container_name: traefik
        command:
            - "--providers.docker=true"
            - "--providers.docker.exposedbydefault=false"
            - "--entrypoints.web.address=:80"
            - "--entrypoints.websecure.address=:443"
            # globalne przekierowanie HTTP → HTTPS
            - "--entrypoints.web.http.redirections.entrypoint.scheme=https"
            - "--entrypoints.web.http.redirections.entrypoint.to=websecure"
            # Let's Encrypt
            - "--certificatesResolvers.le.acme.email=${ACME_EMAIL}"
            - "--certificatesResolvers.le.acme.storage=acme.json"
            - "--certificatesResolvers.le.acme.tlsChallenge=true"
        restart: always
        ports:
            - 80:80
            - 443:443
        networks:
            - web
        volumes:
            - /etc/localtime:/etc/localtime:ro
            - /var/run/docker.sock:/var/run/docker.sock
            - ./acme.json:/acme.json
        labels:
            - traefik.http.middlewares.gzip.compress=true

networks:
    web:
        external: true

Kilka rzeczy wartych uwagi:

• exposedbydefault=false — Traefik ignoruje kontenery, chyba że jawnie się zgłoszą przez etykiety. Nic nie zostaje przypadkowo wystawione na zewnątrz.
• TLS challenge — Traefik obsługuje weryfikację domeny bezpośrednio na porcie 443. Nie trzeba tymczasowo otwierać portu 80.
• acme.json — certyfikaty są zapisywane na dysku i przeżywają restarty kontenera. Przed pierwszym uruchomieniem utwórz plik i ustaw odpowiednie uprawnienia:

touch acme.json && chmod 600 acme.json

Traefik odmówi uruchomienia przy zbyt szerokich uprawnieniach.

• Zewnętrzna sieć web — tworzysz ją raz:

docker network create web

Każda usługa potrzebująca routingu HTTP/S dołącza do tej sieci.

Część 2 — Certyfikaty testowe (staging)#

Przed przejściem na produkcję przetestuj z serwerem staging Let's Encrypt, żeby nie trafić na limity:

# dodaj do sekcji command w traefik:
- "--log.level=DEBUG"
- "--certificatesresolvers.le.acme.caserver=https://acme-staging-v02.api.letsencrypt.org/directory"

Certyfikaty stagingowe nie są zaufane przez przeglądarki, ale funkcjonalnie działają identycznie. Usuń te linie gdy wszystko działa.

Część 3 — Dodanie usługi#

Tu widać zwrot z inwestycji. Dowolny kontener dostaje HTTPS przez dodanie czterech etykiet:

services:
    myapp:
        image: myapp:latest
        networks:
            - web
        labels:
            - traefik.enable=true
            - traefik.http.routers.myapp.rule=Host(`myapp.example.com`)
            - traefik.http.routers.myapp.entrypoints=websecure
            - traefik.http.routers.myapp.tls.certresolver=le

networks:
    web:
        external: true

Traefik wykrywa kontener, pobiera certyfikat od Let's Encrypt i zaczyna routować ruch — bez konfiguracji nginx, bez uruchamiania certbota, bez crona. Odnowienia dzieją się automatycznie w tle.

Alternatywa bez Dockera#

Jeśli nie używasz Dockera, Certbot z wtyczką nginx to standardowe podejście: apt install certbot python3-certbot-nginx, certbot --nginx -d mojastrona.pl, a timer systemd zajmuje się odnowieniami. Sprawdza się dobrze na jednym serwerze z kilkoma stronami. Gdy usług jest więcej, podejście z Traefik zaczyna się opłacać.

Specyfikacja sprzętowa#

Nowy zestaw został skompletowany z myślą o maksymalnej responsywności i stabilności:

• Jednostka: Raspberry Pi 5 (8GB RAM).
• Obudowa: Argon NEO 5 M.2 NVMe – zapewnia skuteczne chłodzenie i bezpośrednią obsługę dysków SSD przez dedykowany interfejs.
• Pamięć masowa: Dysk Lexar 1TB M.2 PCIe NVMe NM620. Rezygnacja z kart micro SD na rzecz NVMe znacząco redukuje opóźnienia i zwiększa trwałość nośnika.

Energooszczędność#

Jednym z kluczowych argumentów za wyborem Raspberry Pi w roli serwera 24/7 jest niski pobór mocy. W obecnej konfiguracji parametry prezentują się następująco:

• Idle (bezczynność): Zapotrzebowanie na poziomie 3W (potwierdzone odczytem z zasilacza).
• Stress (obciążenie): Pobór mocy wzrasta do przedziału 9-12W.

Stosunek wydajności do zużytej energii czyni tę jednostkę niezwykle efektywnym rozwiązaniem pod kątem kosztów eksploatacji.

System i usługi systemowe#

Całość pracuje pod kontrolą Raspberry Pi OS. Na poziomie systemu operacyjnego (poza Dockerem) skonfigurowałem kluczowe usługi zarządzania i dostępu:

• Dostęp zdalny: VPN oparty na protokole Wireguard (PiVPN) zapewnia bezpieczny tunel do sieci domowej.
• Zarządzanie: Do obsługi graficznego interfejsu wykorzystuję VNC.
• Współdzielenie plików: Standardowa usługa Samba do szybkiego dostępu do danych w sieci lokalnej.

Środowisko Docker#

Kluczową zmianą w stosunku do poprzedniego serwera jest pełna konteneryzacja usług sieciowych. Za routing i automatyczne wystawianie certyfikatów SSL odpowiada Traefik.

W ramach Dockera utrzymuję obecnie:

1. holas.pl – moja strona internetowa.
2. Nextcloud – prywatna chmura do synchronizacji danych.
3. Immich – rozwiązanie do backupu i zarządzania biblioteką zdjęć.
4. Traefik – reverse proxy zarządzające ruchem przychodzącym.

Potencjał rozwojowy#

Mimo uruchomienia kilku wymagających usług, Raspberry Pi 5 w wersji 8GB wykazuje spory zapas mocy obliczeniowej oraz pamięci RAM. Obecne obciążenie pozwala na swobodne wdrażanie kolejnych kontenerów bez ryzyka spadku wydajności działających już systemów. Przejście na standard NVMe sprawiło, że operacje na bazach danych (szczególnie w Immich i Nextcloud) są wykonywane natychmiastowo.

Po roku użytkowania wewnętrznego wyszło v1.0.0 — z pełnym wsparciem dla Syliusa 2.x, czystą strukturą i wszystkim, czego używam na co dzień. Następnego dnia pojawiło się v1.0.1 z poprawkami dla różnych platform.

Dlaczego konfiguracja Syliusa bez narzędzi jest uciążliwa#

Sylius 2.x ma nietrywialną konfigurację lokalną. Wymaga PHP 8.4, Composera, bazy danych, serwera WWW z poprawnymi regułami rewrite, Node.js i Yarn do kompilacji assetów panelu admina (opartych na Webpack Encore) oraz binarki Symfony do zadań konsolowych. Sprawne uruchomienie tego wszystkiego na różnych maszynach — Windows, macOS, Linux — bez środowiska kontenerowego jest zawodne. Wersje się rozjeżdżają, zmienne środowiskowe różnią się, ścieżki kolidują.

DDEV rozwiązuje to, deklarując całe środowisko jako konfigurację. Boilerplate ma wbudowane właściwe wersje i łączy je razem, żeby nikt nie musiał tego rozgryzać ręcznie.

Co jest konfigurowane#

Plik .ddev/config.yaml ustawia:

• PHP 8.4 z apache-fpm (Sylius 2.x wymaga PHP 8.2+; 8.4 to obecna stabilna wersja)
• MariaDB 11.8 — najnowsza stabilna, z upload_dirs dostosowanym tak, żeby wykluczyć media/, node_modules/ i backups/ z synchronizacji Mutagen na macOS
• Composer 2
• Porty 8123 (HTTP) i 8443 (HTTPS), żeby unikać konfliktów z innymi lokalnymi projektami
• Xdebug wyłączony domyślnie — włączany przez ddev xdebug on gdy potrzebny

Co jest w środku#

ddev-sylius to szablon projektu oparty na DDEV dla Syliusa 2.x. Sklonuj, uruchom dwie komendy i masz działającą lokalną instancję Syliusa — bez ręcznej konfiguracji wersji PHP, bazy danych ani serwera WWW.

Niestandardowe komendy DDEV dołączone do boilerplate'u:

• ddev sylius-install — pełna instalacja Syliusa od zera
• ddev cc — czyszczenie cache
• ddev dist — instalacja zależności i budowanie assetów (Composer + Yarn)
• ddev yarn <param> — komendy Yarn wewnątrz kontenera
• ddev security-checker — skanowanie znanych podatności
• ddev code-check — weryfikacja standardów kodowania
• ddev backup / ddev database-import / ddev files-import — backup i przywracanie bazy danych i mediów
• ddev sylius-cleanup — resetowanie wszystkich danych (przydatne przy testowaniu przepływu instalacji)
• ddev build-site / ddev rebuild-site — pełna lub częściowa przebudowa projektu

Przetestowane na Windowsie 11 z WSL2 (Ubuntu 24.04), macOS Tahoe (Apple Silicon) i Linuksie z Dockerem.

Jak zacząć#

git clone https://github.com/holas1337/ddev-sylius my-projekt
cd my-projekt
ddev start
ddev sylius-install

Tyle. Po kilku minutach masz działający sklep Sylius z panelem administracyjnym, dostępny pod lokalnym URL-em wygenerowanym przez DDEV (domyślnie https://ddev-sylius-boilerplate.ddev.site:8443).

Codzienna praca#

Po pierwszej instalacji typowe komendy to:

ddev start             # start środowiska
ddev cc                # czyszczenie cache po zmianach konfiguracji
ddev dist              # przebudowa assetów po zmianach frontendu
ddev code-check        # sprawdzenie standardów przed commitem
ddev backup            # snapshot bazy przed ryzykowną migracją

Do debugowania ddev xdebug on włącza Xdebug, a ddev exec bin/console <komenda> daje bezpośredni dostęp do konsoli Symfony wewnątrz kontenera.

Co zmieniło się w v1.0.1#

Poprawka wydana następnego dnia naprawiła kilka rzeczy, które wyszły podczas testów na różnych platformach: dostosowania specyficzne dla macOS dla Mutagen i wyłączeń katalogów uploadu, aktualizacja MariaDB z 11.4 do 11.8 oraz aktualizacja phpMyAdmin do najnowszej wersji.

Repozytorium jest na GitHubie: holas1337/ddev-sylius. Issues i PR-y mile widziane.

uBlock Origin#

Niezbędna pierwsza warstwa ochrony. uBlock Origin (Firefox, Chrome) blokuje reklamy i śledzenie na poziomie sieciowym. Już z domyślnymi listami filtrów blokuje większość pikseli śledzących Facebooka i widżetów społecznościowych na stronach trzecich.

Uwaga dla użytkowników Chrome: Przejście Google na Manifest V3 ogranicza niektóre możliwości uBlock Origin w Chrome. Pełna wersja pozostaje dostępna w Firefoksie.

Privacy Badger#

Privacy Badger od Electronic Frontier Foundation (Firefox, Chrome) działa inaczej niż klasyczne blokery: zamiast statycznej listy blokowania, uczy się, które śledziki podążają za tobą między stronami i stopniowo je blokuje. Dobrze współpracuje z uBlock Origin.

Facebook Container (tylko Firefox)#

Facebook Container to rozszerzenie Mozilli, które izoluje sesję Facebooka w osobnej zakładce kontenera. Facebook nie widzi twojej aktywności na innych stronach, a widżety Facebooka na innych stronach nie mogą odczytać twoich ciasteczek sesji.

To najskuteczniejsze pojedyncze rozszerzenie wymierzone konkretnie w śledzenie Facebooka między stronami — stworzone i utrzymywane przez Mozillę.

Wbudowana ochrona przeglądarek#

Zarówno Firefox, jak i Brave mają domyślnie włączoną rozszerzoną ochronę przed śledzeniem, która blokuje wielu znanych śledzicieli — w tym Facebooka. Jeśli korzystasz z jednej z tych przeglądarek, masz już solidną bazę — rozszerzenia powyżej dodają do niej bardziej szczegółową kontrolę.

Jeśli używasz Chrome, rozważ przejście na Firefoksa dla lepszej domyślnej prywatności.

Przed Let's Encrypt uzyskanie zaufanego certyfikatu SSL wymagało płacenia komerycjnemu CA (Comodo, DigiCert, GoDaddy) od 200 do kilku tysięcy złotych rocznie, ręcznej weryfikacji tożsamości i samodzielnej obsługi odnowień. Let's Encrypt uruchomił się w 2015 roku, wyszedł z bety w kwietniu 2016 i zmienił to całkowicie: darmowe certyfikaty Domain Validation, automatyczne wydawanie przez protokół ACME, 90-dniowy czas ważności z wbudowaną obsługą odnowień. Dla małych serwerów i prywatnych stron działających dotychczas na HTTP była to pierwsza praktyczna droga do HTTPS.

Oficjalny klient Certbot nie był jeszcze dostępny w repozytoriach Debiana Jessie, więc skorzystałem z jednego z alternatywnych klientów — prostego skryptu bash: https://github.com/Neilpang/acme.sh

Używając tego skryptu można wszystko zrobić dosłownie w 5 minut.

Wymagania#

• Dostęp root do serwera
• Apache działający na Debianie Jessie
• Domena wskazująca na publiczne IP serwera
• Otwarty port 80 (używany przez challenge HTTP-01 do weryfikacji własności domeny)

Na wstępie ustalmy, że wszystko wykonujemy z roota oraz:

/root/.acme.sh/acme.sh     # miejsce składowania skryptów klienta
mojastrona.pl              # strona, dla której chcemy uzyskać certyfikat
/mnt/www/mojastrona.pl     # katalog na dysku naszej strony
/etc/apache2               # lokalizacja Apache wraz z plikami konfiguracji

Krok 1 — Pobierz klienta#

Przechodzimy do katalogu /root/.acme.sh/acme.sh (tworzymy jeśli nie istnieje) i wykonujemy:

git clone https://github.com/Neilpang/acme.sh

Jeśli nie mamy gita, pobieramy pliki ręcznie ze strony projektu i wypakowujemy.

Krok 2 — Symlink dla wygody#

ln -s /root/.acme.sh/ /etc/apache2/letsencrypt

Krok 3 — Pobierz certyfikat#

Upewniamy się, że strona jest dostępna z internetu, następnie:

./acme.sh issue /mnt/www/mojastrona.pl/ mojastrona.pl

Lub jeśli mamy aliasy (np. www.mojastrona.pl):

./acme.sh issue /mnt/www/mojastrona.pl/ mojastrona.pl www.mojastrona.pl

acme.sh umieszcza tymczasowy plik w webroocie, Let's Encrypt go pobiera, żeby zweryfikować że kontrolujesz domenę, i wydaje certyfikat. Pliki zapisane zostaną w:

/root/.acme.sh/mojastrona.pl/

Krok 4 — Konfiguracja Apache#

Wskazujemy Apache na nowe certyfikaty w pliku virtual hosta:

SSLCACertificateFile  /etc/apache2/letsencrypt/mojastrona.pl/ca.cer
SSLCertificateFile    /etc/apache2/letsencrypt/mojastrona.pl/mojastrona.pl.cer
SSLCertificateKeyFile /etc/apache2/letsencrypt/mojastrona.pl/mojastrona.pl.key

Następnie przeładowujemy Apache:

service apache2 reload

Od tego momentu strona powinna serwować certyfikat Let's Encrypt.

Krok 5 — Automatyczne odnawianie#

Certyfikaty mają ważność 90 dni. Aby odnawiać automatycznie, tworzymy wykonywalny skrypt acme_cron:

#!/bin/sh
/root/.acme.sh/acme.sh/acme.sh cron >> /var/log/le-renew.log
service apache2 reload

I przenosimy go do /etc/cron.daily.

Proces nie jest skomplikowany — po pierwszej konfiguracji odnawianie przebiega w pełni automatycznie.

Ta konfiguracja działała sprawnie, dopóki nie przeniosłem wszystkiego na Dockera. Nowoczesne podejście z Traefik obsługuje Let's Encrypt automatycznie — bez skryptów, bez crona, bez ręcznej konfiguracji. Więcej: Let's Encrypt z Dockerem i Traefik.

Jest prostsze wyjście: tymczasowe adresy e-mail — gotowe w kilka sekund, bez rejestracji, znikają po kilku godzinach.

Guerrilla Mail#

Guerrilla Mail to najprostszy wybór. Wchodzisz na stronę, kopiujesz wygenerowany adres, używasz go gdzie trzeba. Poczta pojawia się od razu — bez odświeżania. Skrzynka działa w ramach sesji przeglądarki: zamkniesz kartę i adres znika.

Możesz też wysyłać wiadomości z tymczasowego adresu — przydaje się przy niektórych formularzach potwierdzających.

Dropmail#

Dropmail oferuje więcej. To lepszy wybór, gdy adres ma przetrwać dłużej albo gdy zależy Ci na niezawodnym odbieraniu wiadomości.

Co wyróżnia Dropmail:

• Przekierowanie na prawdziwy adres — maile trafiają do Twojej normalnej skrzynki, nie musisz trzymać otwartej karty z Dropmail. Przekierowanie możesz anulować w każdej chwili.
• Klucz odzyskiwania — zapisz go i możesz wrócić do tego samego adresu później, nawet z innego urządzenia lub sesji przeglądarki
• Dwa typy domen — domeny stałe dla długotrwałych adresów, rotujące dla jednorazowego użytku
• Bot na Telegrama — odbieraj maile bezpośrednio w Telegramie bez otwierania przeglądarki
• Aplikacja na Androida — zarządzaj tymczasowymi adresami z telefonu

Żadna z powyższych funkcji nie wymaga rejestracji ani płatnego planu.

Apple Hide My Email#

Jeśli korzystasz z urządzeń Apple i masz subskrypcję iCloud+ (dostępną w każdym płatnym planie iCloud od 50 GB), masz już wbudowaną opcję: Hide My Email.

Generuje unikalny, losowy adres, który przekierowuje pocztę na Twoją prawdziwą skrzynkę — na stałe, dopóki go nie dezaktywujesz. Żadnej osobnej aplikacji, żadnej strony do odwiedzania. Funkcja jest wbudowana bezpośrednio w iOS, iPadOS i macOS:

• Autouzupełnianie w Safari — gdy wypełniasz pole e-mail na stronie, Safari proponuje automatyczne wygenerowanie ukrytego adresu
• Ustawienia → iCloud → Hide My Email — twórz adresy i zarządzaj nimi w jednym miejscu, sprawdzaj które są aktywne, dezaktywuj lub usuń dowolny z nich
• Zaloguj się przez Apple — gdy wybierasz opcję ukrycia adresu przy logowaniu przez Apple, Hide My Email generuje adres automatycznie

Kluczowa różnica w stosunku do Guerrilla Mail i Dropmail: te adresy to stałe aliasy powiązane z Twoim Apple ID, nie jednorazowe skrzynki. Ty nimi zarządzasz, możesz je wyłączyć, a poczta zawsze trafia do Twojej prawdziwej skrzynki. To najbardziej bezproblemowa opcja jeśli jesteś w ekosystemie Apple — zero dodatkowych narzędzi, stałe i zarządzalne aliasy.

Ograniczenie: wymaga płatnego planu iCloud+ i działa tylko na urządzeniach Apple.

Kiedy używać którego#

Używaj Guerrilla Mail gdy potrzebujesz tylko linku potwierdzającego i za dwie minuty zamkniesz kartę.

Używaj Dropmail gdy adres ma przeżyć zamknięcie przeglądarki albo gdy chcesz, żeby maile trafiały w miejsce, gdzie je faktycznie zobaczysz.

Używaj Apple Hide My Email gdy jesteś na iPhonie lub Macu, masz iCloud+, i chcesz generować adresy bez żadnego dodatkowego narzędzia — wbudowane w system, stałe i zarządzalne aliasy.

Co serwis miał robić#

Pośrednictwo ubezpieczeniowe to branża regulowana. Strona brokera to nie tylko broszura — musi komunikować status regulacyjny (numer licencji KNF, ubezpieczenie OC zawodowe), odróżniać firmę od agentów (broker reprezentuje klienta, nie ubezpieczyciela) i budować wystarczające zaufanie, żeby potencjalny klient korporacyjny zadzwonił.

Portfolio usług Alfa Consilium było szerokie: ubezpieczenia D&O, cargo, OC spedytora i OC przewoźnika, ubezpieczenia maszyn, brokerstwo leasingowe, faktoring, zarządzanie wierzytelnościami i zarządzanie ryzykiem z wizytami audytowymi na miejscu. Każdy obszar usług wymagał czytelnego, samodzielnego opisu — nie ściany tekstu, ale treści wystarczającej, żeby decydent zrozumiał zakres i skontaktował się z zespołem.

Projekt i wdrożenie#

Serwis został zaprojektowany w czystej estetyce korporacyjnej: ustrukturyzowany układ, czytelna nawigacja po usługach i dane kontaktowe dostępne z każdej podstrony. Klienci z sektora finansowego — firmy logistyczne, produkcyjne, floty — oczekują profesjonalnej prezentacji, nie startupowej landing page.

Wdrożenie na WordPressie z autorskim motywem PHP pisanym od podstaw — bez gotowego szablonu. Szablon obsługiwał trzy breakpointy responsywne: komputer, tablet i telefon. Responsywny design w 2016 roku wciąż nie był standardem dla małych polskich serwisów korporacyjnych; większość działała na stałej szerokości.

WordPress był właściwym wyborem dla klienta: zespół mógł aktualizować opisy usług i aktualności bez udziału dewelopera, a panel administracyjny nie wymagał żadnego szkolenia.

Co zostało dostarczone#

• Pełny projekt graficzny (desktop + tablet + mobile)
• Autorski motyw WordPress w PHP
• Podstrony usług dla wszystkich linii ubezpieczeniowych i finansowych
• Sekcja kontaktowa z informacjami regulacyjnymi (dane nadzoru KNF, OC zawodowe)
• Responsywny układ na wszystkich trzech breakpointach

Zrzut ekranu z działającego serwisu.

Firma działa nadal — pierwotna domena .pl przekierowuje teraz na alfaconsilium.eu.

W 2015 roku minikomputery jednopłytkowe zaczęły być praktyczną opcją dla energooszczędnego serwera domowego. Raspberry Pi 2 był oczywistym wyborem, ale Banana Pi miał coś, czego Pi nie oferował: port SATA. Dla serwera przechowującego pliki multimedialne i obsługującego backupy prawdziwy dysk twardy był niepodważalną zaletą nad kartą SD.

Sprzęt#

Banana Pi oparty jest na SoC Allwinner A20 — dwurdzeniowym ARM Cortex-A7 taktowanym 1 GHz. Kluczowe parametry, które przesądziły o wyborze:

• CPU: Allwinner A20, 2× 1 GHz (Cortex-A7)
• RAM: 1 GB DDR3
• Gigabit Ethernet (vs 100 Mbit na RPi 2)
• Port SATA — decydujący czynnik. Dysk SATA jest szybszy, bardziej niezawodny i wielokrotnie pojemniejszy od jakiejkolwiek karty SD

Konfiguracja: Banana Pi w obudowie, dysk 2,5" SATA do przechowywania danych, pendrive 4 GB na backupy.

Co działało na serwerze#

Na dystrybucji Bananian — dedykowanym Debianie dla Banana Pi (uwaga: projekt zakończył działalność w 2016 roku i został zastąpiony przez Armbian) — serwer obsługiwał:

• Serwer multimediów (minidlna — strumieniowanie muzyki i wideo na TV przez DLNA bez włączania pełnego PC)
• SSH (zdalne zarządzanie bez monitora, z dowolnego miejsca)
• VPN (OpenVPN — bezpieczne korzystanie z publicznych sieci Wi-Fi, zdalny dostęp do sieci domowej)
• VNC (TightVNC — sesja graficzna gdy potrzeba, np. dla jDownloadera)
• Serwer WWW (stos LAMP — ta strona na nim działała, plus kilka projektów prywatnych)
• Backup (skrypty bash na cronie, bez dodatkowego oprogramowania)
• Pobieranie plików (aria2 i curl z konsoli; jDownloader w trybie graficznym gdy potrzeba)

W praktyce#

Całość działała szybko, sprawnie i stabilnie przez całą dobę. Główną zaletą było zużycie energii: Banana Pi pobiera około 4–8 W pod typowym obciążeniem. Uruchamianie starego desktopa z Core 2 Duo (TDP 65 W, plus reszta systemu) żeby posłuchać muzyki — nie miało sensu. Godzina tamtej maszyny to pewnie cały dzień pracy Banana Pi.

Banana Pi w obudowie z podłączonym dyskiem SATA i starym pendrivem 4 GB na backupy.

Banana Pi od strony konsoli administratora.

Jeśli masz podstawowe umiejętności zarządzania Linuksem i szukasz energooszczędnego serwera pracującego non-stop — ekosystem Debiana daje wszystko, czego potrzebujesz.

Ten zestaw w końcu osiągnął swoje limity. W 2026 roku zastąpiłem go Raspberry Pi 5 z dyskiem NVMe i pełną konteneryzacją na Dockerze. Więcej: Raspberry Pi 5: Migracja na NVMe i konteneryzację usług.

Dlaczego przebudowa, a nie łatanie#

Stary design korzystał z dwóch oddzielnych szablonów: pełnego układu desktopowego i skóry mobilnej serwowanej przez detekcję user-agenta. To podejście działało w 2008 roku, ale do 2015 stało się kulą u nogi — każda zmiana treści lub stylu wymagała podwójnej pracy, a rosnąca różnorodność urządzeń sprawiała, że binarne rozróżnienie desktop/mobile było coraz mniej adekwatne. Tablety, phablet i ekrany o wysokiej gęstości pikseli wpadały w niezręczne przypadki brzegowe.

Decyzja była prosta: pełna przebudowa zamiast doklejania responsywności do starej bazy kodu. Start od zera oznaczał czystszy SCSS, właściwą semantyczną strukturę HTML i brak dziedzictwa hacków do utrzymania.

Implementacja techniczna#

Motyw zbudowałem od zera na WordPressie — bez gotowego szablonu, bez page buildera. Implementacja obejmowała:

• Szablony PHP zgodne z hierarchią szablonów WordPress (single.php, archive.php, page.php, functions.php)
• SCSS kompilowany do jednego arkusza styli — zmienne dla kolorów, odstępów i breakpointów
• Płynna siatka z trzema breakpointami: telefon, tablet i desktop
• Jedna baza kodu — jeden zestaw szablonów, jeden arkusz styli, wszystkie rozmiary ekranów obsługiwane przez media queries w CSS

Co jeszcze zmieniło się przy okazji#

Przebudowa zbiegła się z migracją serwera — strona przeniosła się na własnoręcznie skonfigurowanego Banana Pi z Debianem działającego 24/7. Ten etap opisałem osobno.

Co było później#

Responsywna przebudowa działała dobrze i wizualizacja służyła przez kilka kolejnych lat. Jednak praca z WordPressem coraz częściej oznaczała walkę z jego abstrakcjami zamiast budowania z nim — ekosystem pluginów, ograniczenia PHPowego szablonowania, kwestie deploymentu. W 2026 zastąpiłem go całkowicie — pełna historia w Dlaczego odszedłem od WordPressa.

27 lipca 2015 roku o 18:00 odbyło się pierwsze toruńskie spotkanie PHPers w Krainie Piva na Rynku Nowomiejskim 8. Współorganizowałem je razem z Szymonem Skowrońskim. Uruchomienie nowego oddziału oznaczało stworzenie regularnego miejsca spotkań dla programistów PHP w regionie — i na pierwszą edycję przybyły 57 osób, a kolejne 34 zaznaczyły swoje zainteresowanie.

Prelekcje#

Na spotkaniu odbyły się trzy prelekcje obejmujące różnorodne tematy z PHP:

• Leszek Prabucki — Podstawy programowania obiektywnego w PHP
• Łukasz Lubosz — Blackfire — inteligentny profiler
• Leszek Krupiński — Co PHP? zepsuje w Twoim kodzie

Sponsorzy#

Wydarzenie odbyło się dzięki wsparciu Cocoders, ecenter.pl oraz Krainy Piva, która nas ugościła.

Dlaczego społeczność ma znaczenie#

Organizowanie takich wydarzeń to coś, co cenię sobie obok codziennej pracy deweloperskiej. Budowanie lokalnej sieci kontaktów oznacza lepszą wymianę wiedzy, silniejsze powiązania między programistami w regionie i bardziej aktywną lokalną scenę technologiczną. 91 odpowiedzi na pierwszą w historii edycję PHPers w Toruniu pokazało, że zainteresowanie było realne.

Pełne szczegóły wydarzenia dostępne są na Facebooku.

Co musiał robić serwis#

Serwis miał komunikować pełen zakres oferty Biforu i zachęcić gości do odwiedzin. Nawigacja odzwierciedlała tę różnorodność: Aktualności, O nas, Kuchnia, Kultura, Sport, Napoje i Alko i Kontakt. Na każdej podstronie widoczne było wyraźne CTA do rezerwacji stolika z numerem telefonu, a wtyczka Facebook Like Box integrowała obecność w mediach społecznościowych z serwisem.

Wdrożenie#

Serwis zbudowałem na WordPressie z własnym motywem PHP, wdrożonym na podstawie dostarczonego projektu graficznego — bez gotowego szablonu. Wdrożenie obejmowało:

• Trzy breakpointy RWD — komputer, tablet i telefon — z layoutem dostosowującym się na każdym z nich
• Szablony PHP zgodne z hierarchią szablonów WordPress
• Treści zarządzane przez CMS — klient mógł samodzielnie aktualizować aktualności, wydarzenia, menu i godziny otwarcia
• Integrację z Facebookiem przez widget Like Box

Moją rolą było przełożenie statycznego projektu graficznego na w pełni działający motyw WordPress. Identyfikacja wizualna — ciemna kolorystyka, pogrubiona typografia, logo B!FOR — wynikała z briefu designerskiego; zadaniem była jego pikselowo-wierna implementacja w czystym, utrzymywalnym kodzie.

Serwis nie jest już dostępny.

Czym zajmuje się klient#

Fabryka Kształtów produkuje materiały reklamowe i promocyjne: litery reklamowe, kasetony, półki i stojaki z plexi, dekoracje ścienne, wyklejanie samochodów oraz niestandardowe formy i płaskorzeźby 3D. W zakresie usług firma dysponuje urządzeniem CNC/3D (pole robocze 2000×3000×200 mm) do cięcia aluminium, metali miękkich, dibondu, alucobondu, tworzyw sztucznych (plexi, PCV, HIPS), sklejki i MDF — oraz ploter tnąco-rysujący (szerokość do 1250 mm) do folii standardowej, flex, welurowej, samochodowej i magnetycznej.

Serwis#

Struktura była celowo minimalna — trzy podstrony odpowiadające na pytania, które zadaje potencjalny klient:

• Kim jesteśmy? — informacje o firmie
• Co robimy? — pełna lista usług i produkcji
• Jak nas znaleźć? — kontakt i adres

Wybór statycznej strony był celowy: wizytówka bez dynamicznych treści nie potrzebuje CMS-a. Czysty HTML/CSS/JS to szybszy czas ładowania, tańszy hosting i zerowy nakład na utrzymanie.

Dwa breakpointy — komputer i telefon — wystarczyły dla tego przypadku użycia bez nadmiernej inżynierii. W 2014 roku trzy wersje RWD nie były jeszcze domyślnym oczekiwaniem dla małej strony firmowej.

Wersja desktopowa.

Wersja mobilna.

Projekt został ukończony, ale nigdy nie trafił na produkcję.

Czym zajmuje się firma#

EKO TREND INWEST buduje i sprzedaje domy jednorodzinne na własnych działkach w okolicach Warszawy. Poza nowymi budowami firma zajmuje się również budową i remontami budynków mieszkalnych, użytkowych i przemysłowych, a także oferuje doradztwo kredytowe dla klientów finansujących inwestycje.

Strona główna pozycjonowała firmę na jakość i rzetelność: własna ekipa, sprawdzone firmy podwykonawcze, materiały najwyższej jakości, ceny zagwarantowane umowami. Przykładowe ceny realizacji domów jednorodzinnych w technologii tradycyjnej: od 350 zł/m² za stan surowy otwarty z dachem (2–3 miesiące), stan deweloperski (5–6 miesięcy), stan „pod klucz" (ok. 8 miesięcy).

Serwis#

Serwis miał osiem sekcji odpowiadających na pytania potencjalnego kupującego: Osiedle, Lokalizacja, Plan osiedla, Technologia wykonania, Galeria / Realizacje, Doradztwo kredytowe i Kontakt. Ciemna kolorystyka grafitowo-zielona pasowała do marki „EKO", a fotografie nieruchomości wypełniały treść serwisu.

Wybór QuickCMS dał klientowi lekki, edytowalny panel administracyjny bez rozbudowania WordPressa. Moją rolą było przygotowanie własnego motywu i pełne wdrożenie.

Serwis nie jest już dostępny — archiwalny zrzut dostępny w Wayback Machine.

Czym zajmuje się firma#

Wyróżnikiem HR Management była szerokość i głębokość zintegrowanej oferty: doradztwo ubezpieczeniowe, doradztwo prawne przez powiązaną kancelarię radców prawnych, pośrednictwo ubezpieczeniowe, likwidacja szkód (reprezentacja klientów przed towarzystwami ubezpieczeniowymi i w sporach sądowych) oraz consulting w zakresie oceny ryzyka. Jak podkreślał prezes dr Tomasz Kamiński — taka integracja prawników, brokerów ubezpieczeniowych i konsultantów pod jednym dachem była rzadkością na polskim rynku ubezpieczeniowym i prawnym.

Aktualności obejmowały tematykę ubezpieczeń D&O dla zarządów spółek, studia przypadków z ubezpieczeń budowlanych oraz ubezpieczeń zdarzeń medycznych. W 2013 roku firma weszła na rynek niemiecki.

Serwis#

Strona główna prezentowała siatkę sześciu kafelków usług — O nas, Doradztwo prawne, Consulting, Pośrednictwo ubezpieczeniowe, Likwidacja szkód, Dokumenty — wraz z aktualnościami z datami. Nawigacja była minimalna: Strona główna, Aktualności, O nas, Kontakt. Białe i szare tło z akcentami w kolorach pomarańczowym i niebieskim, zgodnie z identyfikacją wizualną firmy.

Dwuetapowe podejście sprawdziło się: wizytówka dała klientowi natychmiastową obecność w internecie, a w tym czasie powstawał właściwy serwis oparty na CMS. QuickCMS zapewnił klientowi pełną samodzielność w zarządzaniu aktualnościami i treścią.

Serwis dostępny pod adresem hr.com.pl.

Podejście placeholdera#

Zakres był celowo minimalny: jednostronicowy serwis HTML/CSS/JS z czteroslajdowym slideshow — szybki do zbudowania i szybki w działaniu. Żadnego CMS-a, żadnego backendu. Cel: szybkie zaistnienie w internecie przed startem właściwego serwisu.

Co pokazywały slajdy#

Cztery slajdy obejmowały: logo i dane rejestrowe firmy („Strona w przebudowie"), hasło („ROZWIJAMY SIĘ Z WAMI i dla Was"), dane kontaktowe do doradztwa prawnego i consultingu, oraz dane kontaktowe do pośrednictwa ubezpieczeniowego i dochodzenia roszczeń.

Archiwalny zrzut ekranowy wszystkich czterech slajdów.

Dwa miesiące później zastąpiona pełnym serwisem na QuickCMS: HR Management — pełny serwis.