WordPress na Dockerze: Docker Compose, Composer i Xdebug

Jeśli jesteś profesjonalnym programistą WordPress w 2026 roku, Docker jest Twoim najlepszym sprzymierzeńcem. Dawno minęły czasy ręcznego instalowania wersji PHP na Macu czy walki z błędami serwera specyficznymi dla Windowsa. Docker stał się wspólnym językiem środowisk deweloperskich, a jego dobra znajomość należy do warsztatu każdego, kto pracuje dziś w ekosystemie WordPressa.

W tym przewodniku omawiam Dockera w pracy z WordPressem: od podstaw i oficjalnego obrazu wordpress, przez Compose i wp-env, po debugowanie, CI/CD i migrację z MAMP lub LocalWP. Szczegóły techniczne pochodzą z oficjalnej dokumentacji Dockera, strony obrazu wordpress w Docker Hub, dokumentacji MariaDB i podręcznika dla programistów WordPressa, podlinkowanych w każdej sekcji.

#Dlaczego warto używać Dockera do WordPressa

Wymówka “u mnie działa” przestaje działać, gdy środowisko żyje w wersjonowanych plikach. Konteneryzacja zapewnia spójność między środowiskami, a ta zmiana przekształciła sposób, w jaki zespoły WordPressa współpracują i dostarczają oprogramowanie.

#Zgodność środowiska lokalnego z produkcją

Twój lokalny kontener może używać tej samej dystrybucji Linuksa, wersji PHP i konfiguracji MySQL co serwer produkcyjny. To ogranicza najbardziej frustrującą kategorię błędów: te, które pojawiają się tylko na produkcji. Gdy pracujesz w kontenerze z tym samym obrazem, którego używa serwer, kod działający na Twoim laptopie zachowa się tak samo na serwerze stagingowym i na produkcji.

Zgodność środowisk to nie tylko wersje oprogramowania. Obejmuje też konfigurację sieci, zmienne środowiskowe i uprawnienia plików. Z Dockerem każda osoba w zespole pracuje w identycznym środowisku, niezależnie od tego, czy jej system to macOS, Windows czy Linux.

#Kilka wersji PHP w izolowanych projektach

Projekt A potrzebuje PHP 8.4, a Projekt B PHP 7.4? Żaden problem. Każdy projekt żyje we własnej “bańce” i nigdy nie wchodzi w konflikt z innymi. Taki poziom izolacji był bardzo trudny w narzędziach takich jak MAMP czy XAMPP, gdzie zmiana wersji PHP dotykała wszystkich projektów naraz.

Izolacja Dockera chroni też system gospodarza. Rozszerzenia PHP, biblioteki systemowe i zależności projektu pozostają rozdzielone. Jeśli projekt wymaga eksperymentalnego rozszerzenia PHP albo nietypowej konfiguracji serwera, możesz ją wdrożyć bez ryzyka dla pozostałych projektów.

#Powtarzalne środowisko z plików wersjonowanych w Gicie

Każde środowisko Docker opisują pliki konfiguracyjne trzymane w Gicie. Nowa osoba w zespole klonuje repozytorium, wykonuje jedną komendę i ma działające środowisko, bez instrukcji instalacji krok po kroku, która szybko się dezaktualizuje. Dokumentacja środowiska żyje w kodzie projektu.

#WordPress w Docker Compose

Docker Compose to narzędzie koordynujące wiele kontenerów. Typowa konfiguracja WordPressa w 2026 roku składa się z kilku usług, które razem tworzą kompletne środowisko deweloperskie.

#Jakie usługi zawiera WordPress w Docker Compose

1. WordPress (PHP-FPM lub Apache): silnik wykonujący kod PHP WordPressa.
2. Nginx: serwer WWW przed PHP-FPM, jeśli wybierasz wariant fpm.
3. MariaDB/MySQL: baza danych, w której zapisana jest cała treść.
4. Redis: cache obiektowy, warty dodania, jeśli projekt używa go na produkcji.
5. Mailpit: do przechwytywania wychodzących e-maili podczas testów.

# Fragment compose.yaml z wariantem FPM
services:
  db:
    image: mariadb:11.4
    volumes:
      - db_data:/var/lib/mysql
  wordpress:
    image: wordpress:php8.4-fpm
    depends_on:
      - db
volumes:
  db_data:

Wariant fpm nie zawiera serwera WWW, więc potrzebuje kontenera Nginx, który przekaże mu żądania PHP. Jeśli nie chcesz konfigurować Nginxa, wariant z Apache (wordpress:php8.4-apache) serwuje WordPressa bezpośrednio na porcie 80 kontenera.

#Bind mounty czy nazwane wolumeny dla WordPressa

Wolumeny w Docker Compose są kluczowe dla pracy z WordPressem. Katalog motywów i wtyczek montujesz, by edytować kod na żywo, a dane bazy danych muszą przetrwać w nazwanych wolumenach, żeby nic nie zginęło między restartami kontenera.

Właściwa strategia łączy wydajność z wygodą. Dla plików, które często edytujesz (motywy, własne wtyczki), używaj bind mountów. Dla danych, które mają tylko przetrwać (baza danych, uploads), używaj nazwanych wolumenów Dockera. Dokumentacja oficjalnego obrazu podaje ścieżki: motywy trafiają do /var/www/html/wp-content/themes/, a wtyczki do /var/www/html/wp-content/plugins/.

#Dane dostępowe w plikach .env w Docker Compose

Zarządzanie sekretami ma znaczenie także lokalnie. Trzymaj dane dostępowe do bazy i klucze API w plikach .env i upewnij się, że są w .gitignore. Docker Compose czyta plik .env z katalogu projektu i podstawia zmienne takie jak ${DB_PASSWORD} w compose.yaml, co oddziela wrażliwą konfigurację od wersjonowanego kodu.

#Zmienne środowiskowe oficjalnego obrazu WordPressa

Obraz wordpress z Docker Hub generuje własny wp-config.php na podstawie zmiennych środowiskowych. Według oficjalnej strony obrazu rozpoznaje te zmienne:

Szczegół, który kosztuje najwięcej czasu: kontener WordPressa nie tworzy bazy wskazanej w WORDPRESS_DB_NAME. Tworzy ją kontener bazy danych, przez MARIADB_DATABASE w MariaDB albo MYSQL_DATABASE w MySQL. Jeśli te nazwy się różnią, WordPress pokaże błąd połączenia, nawet gdy dane dostępowe są poprawne.

WORDPRESS_CONFIG_EXTRA przydaje się do stałych, których obraz nie udostępnia, na przykład WP_ALLOW_MULTISITE albo WP_ENVIRONMENT_TYPE. Wszystko, co tam wpiszesz, wykonuje się przez eval(), więc trzymaj tę wartość krótką i wersjonowaną razem z resztą konfiguracji.

#Jak poczekać, aż MariaDB będzie gotowa przed startem WordPressa

Samo depends_on nie wystarczy. Dokumentacja Compose o kolejności uruchamiania wyjaśnia, że Compose czeka, aż kontener zależności będzie uruchomiony, a nie aż będzie gotowy przyjmować połączenia. MariaDB przy pierwszym starcie inicjalizuje się kilka sekund, a WordPress może wystartować wcześniej i nie połączyć się z bazą.

Rozwiązaniem jest healthcheck w bazie danych i condition: service_healthy w WordPressie. Oficjalny obraz MariaDB zawiera do tego skrypt healthcheck.sh, a dokumentacja MariaDB publikuje przykład z WordPressem. Po dostosowaniu do środowiska deweloperskiego wygląda tak:

services:
  db:
    image: mariadb:11.4
    environment:
      MARIADB_DATABASE: wordpress
      MARIADB_USER: wordpress
      MARIADB_PASSWORD: ${DB_PASSWORD}
      MARIADB_RANDOM_ROOT_PASSWORD: '1'
    volumes:
      - db_data:/var/lib/mysql
    healthcheck:
      test: ["CMD", "healthcheck.sh", "--connect", "--innodb_initialized"]
      start_period: 10s
      interval: 10s
      timeout: 5s
      retries: 3
  wordpress:
    image: wordpress:php8.4-apache
    ports:
      - "8080:80"
    environment:
      WORDPRESS_DB_HOST: db
      WORDPRESS_DB_NAME: wordpress
      WORDPRESS_DB_USER: wordpress
      WORDPRESS_DB_PASSWORD: ${DB_PASSWORD}
      WORDPRESS_DEBUG: '1'
    volumes:
      - wp_data:/var/www/html
      - ./moj-motyw:/var/www/html/wp-content/themes/moj-motyw
    depends_on:
      db:
        condition: service_healthy
volumes:
  db_data:
  wp_data:

Z tym plikiem docker compose up -d uruchamia bazę danych, czeka, aż healthcheck przejdzie, i dopiero wtedy startuje WordPressa pod adresem http://localhost:8080. Własny motyw jest zamontowany jako bind mount, a reszta WordPressa zostaje w wolumenie wp_data.

#Obrazy WordPressa apache, fpm, alpine i cli

Oficjalny obraz jest publikowany w kilku wariantach. Tagi łączą wersję WordPressa, wersję PHP i typ, na przykład php8.4-apache, php8.4-fpm, php8.4-fpm-alpine albo cli.

• apache: WordPress i Apache w jednym kontenerze. Najprostsza opcja do pracy lokalnej.
• fpm: samo PHP-FPM, przeznaczone do pracy za Nginxem lub innym proxy.
• fpm-alpine: to samo na Alpine Linux, z mniejszym obrazem.
• cli: WP-CLI bez serwera WWW, do uruchamiania komend wp na istniejącej instalacji.

Wariant cli ma pułapkę opisaną w Docker Hub: bazuje na Alpine, a jego użytkownik www-data ma UID 82, podczas gdy warianty oparte na Debianie używają UID 33. Uruchamiając wordpress:cli na instalacji z Debianem, zwykle trzeba dodać --user 33:33, a czasem -e HOME=/tmp, żeby WP-CLI mógł zapisywać pliki.

#Jak dodać rozszerzenia PHP do oficjalnego obrazu

Obraz nie zawiera dodatkowych rozszerzeń PHP, nawet jeśli wymagają ich popularne wtyczki. Docker Hub podaje jako przykład, że obraz sam z siebie nie wyśle e-maila. Aby dodać rozszerzenia, budujesz własny obraz z FROM wordpress:... i postępujesz według instrukcji obrazu php. Do zmiany dyrektyw takich jak upload_max_filesize wystarczy skopiować custom.ini do $PHP_INI_DIR/conf.d/:

FROM wordpress:php8.4-apache
COPY custom.ini $PHP_INI_DIR/conf.d/

Jeśli chcesz zaszyć motywy lub wtyczki w obrazie dla wielu instalacji, dokumentacja zaleca kopiowanie ich do /usr/src/wordpress/, skąd przy pierwszym starcie kontenera trafiają do /var/www/html/.

#wp-env, oficjalne środowisko Docker dla WordPressa

Jeśli tworzysz wtyczki lub motywy i nie musisz odtwarzać konkretnego serwera, wp-env oszczędza ręcznego pisania compose.yaml. To pakiet Node rozwijany w repozytorium Gutenberga, który pod spodem korzysta z Dockera. Instalujesz go przez npm -g i @wordpress/env i uruchamiasz komendą wp-env start z katalogu wtyczki.

Środowisko działa pod adresem http://localhost:8888 z użytkownikiem admin i hasłem password. Konfiguracja trafia do pliku .wp-env.json w katalogu głównym projektu:

{
  "$schema": "https://schemas.wp.org/trunk/wp-env.json",
  "core": null,
  "phpVersion": "8.3",
  "plugins": [ "." ],
  "config": {
    "WP_DEBUG_LOG": true
  }
}

core ustawione na null oznacza najnowszą stabilną wersję WordPressa, phpVersion ustala wersję PHP, a plugins wymienia wtyczki do zainstalowania i aktywacji. Do dyspozycji są też themes, mappings do montowania katalogów, port (domyślnie 8888), testsPort (8889) i mariadbVersion.

Composer, PHPUnit i WP-CLI są dostępne w kontenerze cli: wp-env run cli wp plugin list albo wp-env run cli --env-cwd=wp-content/plugins/moja-wtyczka composer install. Xdebug jest zainstalowany, ale wyłączony, a włącza go wp-env start --xdebug. Dokumentacja opisuje też eksperymentalny tryb wp-env start --runtime=playground, który uruchamia WordPressa w WebAssembly bez Dockera, z SQLite i bez komendy run.

Praktyczna różnica względem Compose: wp-env decyduje o architekturze za Ciebie. Przy wtyczce to szybsza droga. Do odtworzenia serwera produkcyjnego z Nginxem, Redisem i dokładną wersją MariaDB lepszym narzędziem pozostaje Compose.

#VS Code Dev Containers dla WordPressa

Wielu programistów nie instaluje już PHP na swoich laptopach. Używają VS Code Dev Containers, które zmieniają sposób pracy z edytorem.

#Jak działa Dev Container w VS Code

Otwierasz folder projektu, a VS Code wykrywa folder .devcontainer, uruchamia Dockera i łączy IDE bezpośrednio wewnątrz kontenera. Rozszerzenia VS Code, narzędzia wiersza poleceń i konfiguracja edytora działają w kontenerze.

#Rozszerzenia i lintery skonfigurowane w kontenerze

Skonfigurowane miejsce pracy dla każdego projektu, zaraz po otwarciu folderu. Nie ma znaczenia, czy ktoś dołączył do zespołu pięć minut temu, czy pięć lat temu: środowisko jest identyczne dla wszystkich. Rozszerzenia PHP, lintery, formatery kodu i narzędzia do debugowania są zdefiniowane w repozytorium.

#Dev Containers w rozproszonych zespołach

W agencjach WordPress z rozproszonymi zespołami Dev Containers usuwają częste źródło tarć: różnice między środowiskami lokalnymi. Każda osoba pracuje w tym samym środowisku, niezależnie od miejsca i sprzętu, bez sesji “skonfigurujmy Ci laptopa”.

#Wydajność Dockera na Macu i Windowsie

Docker był wolny na systemach innych niż Linux, bo pliki projektu przechodzą przez maszynę wirtualną. Docker Desktop daje dziś kilka sposobów, by zmniejszyć ten koszt.

#Jak włączyć VirtioFS w Docker Desktop

Na macOS wybierz VirtioFS jako mechanizm współdzielenia plików w ustawieniach Docker Desktop. Dokumentacja ustawień Docker Desktop podaje, że VirtioFS skrócił czas operacji na systemie plików nawet o 98%. Zastępuje wcześniejsze opcje, osxfs i gRPC FUSE.

#Synchronized file shares dla dużych repozytoriów

Dla bardzo dużych projektów Docker Desktop oferuje Synchronized file shares: utrzymuje zsynchronizowaną kopię plików gospodarza w systemie ext4 wewnątrz maszyny wirtualnej. Docker poleca tę funkcję dla repozytoriów liczących 100 000 plików lub więcej, a dostępna jest w subskrypcjach Pro, Team i Business. Instalacja WordPressa z dużym node_modules w motywie może zbliżyć się do tej liczby.

#Ile RAM-u zużywa Docker Desktop

Maszyna wirtualna Docker Desktop rezerwuje pamięć, dopóki jest włączona. Tryb Resource Saver zatrzymuje ją, gdy przez 5 minut (wartość do zmiany) nie działa żaden kontener, a Docker podaje oszczędność 2 GB lub więcej pamięci i CPU na komputerze gospodarza.

#Docker czy LocalWP, MAMP i DDEV

#Docker Compose a DDEV i Lando

DDEV i Lando upraszczają pracę z Dockerem dla programistów WordPressa. Dają gotowe konfiguracje i prostsze komendy, które skracają naukę. Gdy potrzebujesz pełnej kontroli nad każdym elementem infrastruktury, Compose z własnym plikiem pozostaje najbardziej elastyczną opcją.

#Kiedy wybrać DDEV, a kiedy Docker Compose

Wybór zależy od doświadczenia i projektu. Jeśli dopiero zaczynasz z konteneryzacją, DDEV ma łagodniejszą krzywą nauki. Jeśli prowadzisz kilka projektów o różnych wymaganiach infrastrukturalnych, Docker Compose z własnymi konfiguracjami daje więcej swobody.

#Bezpieczeństwo środowisk Docker dla WordPressa

Docker zapewnia izolację domyślnie, ale to konfiguracja decyduje, ile ochrony faktycznie dostajesz.

#Kontenery bez roota i aktualne obrazy

Unikaj uruchamiania procesów jako root w kontenerach, gdy nie jest to potrzebne. Aktualizuj obrazy bazowe, żeby dostawać poprawki bezpieczeństwa; sama dokumentacja obrazu wordpress przypomina o regularnym przebudowywaniu i ponownym wdrażaniu. Skanuj obrazy pod kątem znanych podatności narzędziami takimi jak Docker Scout czy Trivy.

#Osobne sieci Docker dla każdego projektu

Compose tworzy osobną sieć dla każdego projektu. Zachowaj ten podział i nie podłączaj bez powodu kontenerów z różnych projektów do jednej sieci, żeby włamanie do jednego nie sięgało pozostałych.

#Docker Secrets i pliki .env na hasła

Nigdy nie wpisuj danych dostępowych bezpośrednio do Dockerfile ani do compose.yaml. Obraz wordpress akceptuje przyrostek _FILE w swoich zmiennych: WORDPRESS_DB_PASSWORD_FILE=/run/secrets/db_password odczytuje hasło z pliku zamiast ze zmiennej. Compose montuje każdy sekret w /run/secrets/<nazwa> wewnątrz kontenera, zgodnie ze swoim przewodnikiem po sekretach, który dodaje jedno ograniczenie: sekrety działają tylko w kontenerach linuksowych.

#Jak skonfigurować CI/CD dla WordPressa z Dockerem

Największą zaletą Dockera jest to, że potoki CI/CD (GitHub Actions, GitLab CI) mogą używać tych samych obrazów, których używasz lokalnie. Ta spójność usuwa całą kategorię błędów wdrożeniowych.

#Kroki potoku CI/CD z Dockerem

1. Uruchom testy PHPUnit w kontenerze, by sprawdzić logikę backendu.
2. Uruchom testy end-to-end w Cypress lub Playwright przeciwko kontenerowi.
3. Wdróż stabilny obraz na klaster produkcyjny (Kubernetes/Swarm).

#Prywatny rejestr obrazów Docker dla WordPressa

Zespoły, które budują własne obrazy WordPressa, trzymają je w prywatnym rejestrze kontenerów. Takie obrazy zawierają potrzebne rozszerzenia PHP, narzędzia deweloperskie i konfigurację projektu, więc nowa osoba pobiera gotowy obraz zamiast go budować.

Docker Hub opisuje też statyczny tryb wdrożenia: budujesz obraz z WordPressem, motywem i wtyczkami w /usr/src/wordpress, uruchamiasz go w trybie --read-only z tmpfs dla /tmp i /run, a aktualizujesz, wdrażając nowy obraz zamiast korzystać z automatycznych aktualizacji.

#WordPress na Kubernetes lub Docker Swarm

Przy stronach WordPress o dużym ruchu orkiestracja w Kubernetes lub Docker Swarm pozwala skalować się według zapotrzebowania. Gdy ruch rośnie podczas kampanii albo wyprzedaży, startują nowe kontenery, które przejmują dodatkowe obciążenie.

#Jak debugować WordPressa w Dockerze

Debugowanie WordPressa w kontenerach wymaga kilku technik innych niż w tradycyjnej pracy lokalnej.

#Xdebug w kontenerach

Konfiguracja Xdebuga w kontenerze wymaga uwagi przy sieci: kontener musi dosięgnąć IDE nasłuchującego na komputerze gospodarza. Wiele konfiguracji Dev Containers ma już Xdebuga, wp-env włącza go flagą --xdebug, a we własnym obrazie trzeba zainstalować rozszerzenie i ustawić host połączenia oraz port.

#Jak czytać logi przez docker compose logs

Docker daje scentralizowany dostęp do logów wszystkich usług. Użyj docker compose logs, by zobaczyć połączone wyjście WordPressa, Nginxa, MariaDB i Redisa, albo docker compose logs -f wordpress, by śledzić jedną usługę. Przy włączonym WORDPRESS_DEBUG ostrzeżenia PHP pojawiają się w tym samym strumieniu. Na produkcji panele monitoringu dają narzędzia takie jak Grafana i Prometheus.

#Query Monitor i Blackfire w Dockerze

Narzędzia takie jak Query Monitor i Blackfire działają w środowiskach Docker z WordPressem. Profilowanie w kontenerze pokazuje wydajność w warunkach zbliżonych do produkcji.

#Migracja z MAMP lub LocalWP do Dockera

Jeśli używasz MAMP, XAMPP lub LocalWP, przejście na Dockera jest prostsze, niż się wydaje. Typowy proces obejmuje eksport baz danych, przygotowanie plików Compose odtwarzających obecną konfigurację i stopniowe wprowadzanie pozostałych praktyk.

#Jak przenieść projekt pilotażowy do Docker Compose

Zacznij od jednego projektu pilotażowego. Utwórz plik compose.yaml, który odtwarza obecne środowisko, w tym wersję PHP, silnik bazy danych i potrzebne rozszerzenia. Gdy pilotaż działa, przenieś pozostałe projekty.

#Jak zaimportować bazę danych i wp-content

Wyeksportuj bazy przez mysqldump i zaimportuj je do kontenera MariaDB. Skopiuj pliki WordPressa (zwłaszcza wp-content) do struktury wolumenów Dockera. Jeśli zmienia się adres, na przykład na http://localhost:8080, uruchom wp search-replace w WP-CLI i sprawdź, czy media i linki działają w nowym środowisku.

#Podsumowanie

Docker nie jest już narzędziem tylko dla DevOpsów; to fundament pracy programisty WordPress w 2026 roku. Dzięki konteneryzacji eliminujesz błędy środowiskowe, przyspieszasz wdrażanie nowych osób do zespołu i budujesz bezpieczniejsze aplikacje. Czas poświęcony na naukę Dockera zwraca się w produktywności i jakości kodu.

Zobacz też, jak przyspieszyć stronę WordPress i jaką rolę odgrywa w tym konteneryzacja.

Wciąż walczysz z konfiguracją lokalnych serwerów? Czas przekazać to zadanie Dockerowi.