Najczęstsze błędy przy docker-compose z PostgreSQL i Node.js

Najczęstsze błędy przy docker-compose dla Node.js i PostgreSQL

Zdarza Ci się, że zamiast skupić się na kodowaniu, spędzasz godziny na debugowaniu środowiska deweloperskiego? Ustawienie aplikacji z bazą danych i backendem w kontenerach Docker to świetny sposób na powtarzalne środowisko. Jednak konfiguracja docker-compose dla aplikacji Node.js z PostgreSQL potrafi frustrować, gdy na starcie widzisz tylko komunikaty o błędach.

Na początku pracy z Dockerem, a wcześniej z lokalnym stawianiem środowiska, łatwo utknąć na problemach z wersjami Node.js czy zależnościami PostgreSQL. Z Dockerem miało być prościej – i faktycznie jest, pod warunkiem, że wiesz, gdzie czyhają pułapki. W tym artykule przejdziemy przez najczęstsze błędy przy docker-compose dla aplikacji z bazą PostgreSQL i backendem Node na laptopie programisty.

Celem jest to, abyś mógł wrócić do pisania kodu, zamiast walczyć z infrastrukturą. Zobaczysz konkretne przykłady konfiguracji docker-compose.yml, fragmenty Dockerfile i typowe problemy z połączeniem między backendem i bazą danych. Wszystkie porady są praktyczne i możliwe do wdrożenia od razu.

Zastanowimy się, dlaczego aplikacja Node.js nie łączy się z bazą PostgreSQL, mimo że konfiguracja wygląda na poprawną. Poznasz nie tylko przyczyny, ale i powtarzalne rozwiązania, które możesz skopiować do swoich projektów. Dzięki temu unikniesz wielu godzin bezproduktywnego debugowania i skupisz się na rozwoju funkcjonalności.

---

---

Problem 1: Komunikacja między serwisami w docker-compose

Jednym z fundamentalnych źródeł problemów jest sama komunikacja między kontenerami w docker-compose. Każdy serwis działa w izolowanej sieci, a nieprawidłowe adresowanie hostów czy portów powoduje klasyczne błędy typu connection refused. Zrozumienie sieci Dockera to pierwszy krok do stabilnego środowiska.

Gdy backend Node.js nie widzi bazy, programista często próbuje rozwiązać problem po stronie kodu. Tymczasem wina leży zazwyczaj w niepoprawnych hostach, złym mapowaniu portów lub braku świadomości, jak Docker tworzy sieć. W tej sekcji skupiamy się na najczęstszych scenariuszach.

localhost vs nazwa serwisu – host bazy danych

W świecie Docker Compose localhost w kontenerze oznacza sam kontener, a nie Twój laptop ani inny serwis. To źródło bardzo wielu błędów, zwłaszcza przy pierwszym podejściu do dockerowego środowiska deweloperskiego dla Node.js i PostgreSQL.

Jeśli w aplikacji Node.js próbujesz łączyć się z bazą pod adresem localhost:5432, to tak naprawdę odwołujesz się do portu 5432 w tym samym kontenerze backendu. Kontener PostgreSQL jest pod zupełnie innym adresem – jego nazwą jest nazwa serwisu z docker-compose.yml, np. db.

Przykładowa konfiguracja:

version: '3.8'
services:
  db:
    image: postgres:14
    environment:
      POSTGRES_DB: mydatabase
      POSTGRES_USER: myuser
      POSTGRES_PASSWORD: mypassword
    ports:
      - "5432:5432"
    volumes:
      - pgdata:/var/lib/postgresql/data

  backend:
    build: .
    ports:
      - "3000:3000"
    environment:
      DATABASE_URL: postgres://myuser:mypassword@db:5432/mydatabase
      NODE_ENV: development
    depends_on:
      - db
    volumes:
      - .:/app
      - /app/node_modules
volumes:
  pgdata:

W kodzie Node.js powinieneś używać np. process.env.DATABASE_URL i upewnić się, że hostem jest db, a nie localhost. Zmiana jednego słowa często rozwiązuje cały problem komunikacji między backendem i PostgreSQL.

Niewłaściwe mapowanie portów na hoście

Drugim częstym problemem jest port mapping – sposób, w jaki porty z kontenerów wystawiasz na hosta, czyli swój laptop. Błędna konfiguracja ports może sprawić, że serwis działa w kontenerze, ale jest całkowicie niewidoczny z zewnątrz.

Format mapowania to HOST_PORT:CONTAINER_PORT. Przykłady:

• PostgreSQL: 5432:5432 – baza dostępna lokalnie pod localhost:5432
• Node.js: 3000:3000 – aplikacja dostępna pod http://localhost:3000

Problemy zaczynają się, gdy na hoście port jest już zajęty. Wtedy docker-compose up może zakończyć się błędem „port is already allocated” lub kontener będzie się restartował. Warto sprawdzić, czy porty nie są używane:

• macOS/Linux: lsof -i :3000
• Windows: netstat -ano | findstr :3000

Jeśli port jest zajęty, zmień mapowanie, np. na 3001:3000 dla backendu lub 5555:5432 dla PostgreSQL. Wewnątrz sieci Docker porty pozostają bez zmian – modyfikujesz tylko stronę hosta.

Problem 2: Konfiguracja PostgreSQL w Dockerze

Sama baza danych PostgreSQL wymaga właściwej konfiguracji, aby działać stabilnie w środowisku Docker Compose. Brak odpowiednich zmiennych środowiskowych, problemy z woluminami danych czy błędny connection string z aplikacji Node.js to klasyczne przypadki, które potrafią zablokować start projektu.

PostgreSQL w kontenerze jest inicjalizowany przy pierwszym uruchomieniu na podstawie przekazanych zmiennych i woluminów. Jeśli ten etap pójdzie źle, późniejsze próby połączeń kończą się błędami, mimo pozornie poprawnej konfiguracji backendu.

Kluczowe zmienne środowiskowe PostgreSQL

Kontener postgres wymaga kilku podstawowych zmiennych środowiskowych. Bez nich baza może nie utworzyć się poprawnie lub w ogóle nie wystartować. Błędy uwierzytelnienia pochodzą często właśnie z niezgodności pomiędzy tymi zmiennymi a danymi używanymi w Node.js.

Minimalny zestaw:

services:
  db:
    image: postgres:14
    environment:
      POSTGRES_DB: moja_aplikacja_db
      POSTGRES_USER: user_apki
      POSTGRES_PASSWORD: supertajnehaslo!

Warto zwrócić uwagę, że nazwy zmiennych muszą być dokładne (POSTGRES_DB, nie np. POSTGRES_DATABASE). Literówka tutaj potrafi sprawić, że kontener stworzy domyślne ustawienia, a Ty będziesz bezskutecznie próbować logować się innymi danymi z poziomu aplikacji Node.js.

Woluminy danych PostgreSQL – utrata danych i błędy startu

Dane w kontenerze są domyślnie efemeryczne, więc bez woluminów znikną po usunięciu kontenera. W przypadku PostgreSQL najczęściej używa się nazwanych woluminów, dzięki czemu baza przetrwa restarty i odtworzenia serwisów w docker-compose.

Przykład konfiguracji:

services:
  db:
    image: postgres:14
    environment:
      POSTGRES_DB: moja_aplikacja_db
      POSTGRES_USER: user_apki
      POSTGRES_PASSWORD: supertajnehaslo!
    volumes:
      - pgdata:/var/lib/postgresql/data
volumes:
  pgdata:

Jeśli wolumin zostanie uszkodzony lub jest w niepoprawnym stanie, baza może przestać startować. W logach zobaczysz wtedy błędy inicjalizacji lub uszkodzenia danych. Czasem jedynym skutecznym krokiem jest usunięcie woluminu (docker volume rm pgdata) i ponowne utworzenie bazy – oczywiście po wcześniejszym wykonaniu backupu.

Błędny connection string w aplikacji Node.js

Nawet gdy kontener db jest poprawnie skonfigurowany, problem może leżeć w samej aplikacji Node.js. Connection string bywa miejscem, gdzie pojawiają się literówki w haśle, błędna nazwa hosta albo zły port.

Przykładowa zmienna w .env lub docker-compose.yml:

DATABASE_URL=postgresql://user_apki:supertajnehaslo!@db:5432/moja_aplikacja_db

Zwróć uwagę na:

• poprawny protokół (postgresql:// lub postgres://)
• zgodną nazwę użytkownika i hasło
• host ustawiony na db
• port 5432
• nazwę bazy z POSTGRES_DB

Warto logować sam connection string (bez hasła) lub chociaż host, port i nazwę bazy, aby szybciej wyłapać rozbieżności między backendem a kontenerem PostgreSQL.

---

---

Problem 3: Backend Node.js w kontenerze Docker

Aplikacja Node.js, nawet poprawnie działająca lokalnie bez Dockera, może mieć trudności w kontenerze. Problemy z przekazywaniem zmiennych środowiskowych, instalacją zależności czy ścieżkami roboczymi powodują, że kontener startuje, ale backend nie działa tak, jak powinien.

Konteneryzacja backendu wymaga kilku dobrych praktyk, które znacznie ułatwiają pracę deweloperską. Dzięki nim zyskasz stabilne i przewidywalne środowisko, niezależne od systemu operacyjnego na laptopie.

Zmienne środowiskowe połączenia z bazą

Jeśli aplikacja Node.js korzysta z process.env.DATABASE_URL, to w kontenerze musisz tę zmienną jawnie przekazać. Środowisko Dockera nie „widzi” Twoich lokalnych ustawień, dopóki ich nie zdefiniujesz w docker-compose.yml lub pliku .env używanym przez Compose.

Przykład konfiguracji w docker-compose.yml:

services:
  backend:
    build: .
    ports:
      - "3000:3000"
    environment:
      DATABASE_URL: postgres://user_apki:supertajnehaslo!@db:5432/moja_aplikacja_db
      NODE_ENV: development
      PORT: 3000
    depends_on:
      - db
    volumes:
      - .:/app
      - /app/node_modules

Pamiętaj, że wartości z environment nadpisują zmienne z .env projektu Docker Compose, jeśli mają tę samą nazwę. Dobrze jest utrzymywać jedno źródło prawdy dla ustawień produkcyjnych i deweloperskich, a różnice jasno opisywać.

Instalacja zależności i Dockerfile dla Node.js

Bardzo częstym błędem jest brak npm install w Dockerfile lub niepoprawna kolejność kopii plików. To prowadzi do błędów typu Error: Cannot find module 'express', mimo że lokalnie wszystko działa.

Przykładowy Dockerfile z multi-stage build:

FROM node:18-alpine AS build_deps
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm install

FROM node:18-alpine
WORKDIR /app
COPY --from=build_deps /app/node_modules ./node_modules
COPY . .
EXPOSE 3000
CMD ["npm", "start"]

Taki podział pozwala na wykorzystanie cache warstw Dockera oraz zmniejsza rozmiar finalnego obrazu. Najpierw kopiujesz tylko pliki package*.json, instalujesz zależności, a potem dopiero resztę kodu. Dzięki temu przy zmianach w kodzie nie trzeba za każdym razem instalować wszystkich paczek.

WORKDIR i montowanie woluminów

Kolejny typowy problem to niezgodność między WORKDIR w Dockerfile a ścieżką montowania w docker-compose.yml. Jeśli w jednym miejscu używasz /usr/src/app, a w drugim /app, kontener może startować bez dostępu do kodu aplikacji.

Bezpieczny, spójny wariant:

• Dockerfile: WORKDIR /app
• docker-compose: - .:/app w volumes

Przykład w docker-compose.yml:

services:
  backend:
    build: .
    volumes:
      - .:/app
      - /app/node_modules

Dzięki temu kod z Twojego laptopa jest widoczny w katalogu roboczym kontenera, a jednocześnie node_modules nie jest nadpisywane lokalną wersją. Umożliwia to wygodne użycie hot-reloadingu i szybkie iteracje przy pracy deweloperskiej.

Montowanie woluminów i hot-reload

Jeśli chcesz mieć hot-reload w środowisku Docker, kluczowe jest poprawne montowanie woluminów. Błędna konfiguracja może sprawić, że zmiany w kodzie nie będą widoczne lub kontener zacznie korzystać z niewłaściwych modułów.

Dobrą praktyką jest:

1. Montowanie całego katalogu projektu: - .:/app.
2. Dodanie pustego woluminu na node_modules, aby ukryć potencjalne lokalne moduły:

yaml volumes: - .:/app - /app/node_modules

W ten sposób korzystasz z zależności zainstalowanych w kontenerze, zgodnych z jego systemem i architekturą. Jednocześnie każdy zapis pliku na hoście jest od razu widoczny w kontenerze, co świetnie współgra z narzędziami takimi jak nodemon.

CMD / ENTRYPOINT w Dockerfile

Jeśli kontener Node.js startuje, ale aplikacja nie rusza, przyczyną jest często błędne polecenie w CMD lub ENTRYPOINT. Zdarza się, że wskazywany skrypt nie istnieje albo brakuje odpowiedniego wpisu w package.json.

Przykładowe poprawne polecenie:

CMD ["npm", "start"]

Lub dla środowiska deweloperskiego z hot-reloadem:

CMD ["npm", "run", "dev"]

Ważne, by CMD było w formacie exec (lista argumentów), a nie pojedynczy string. Ułatwia to przekazywanie sygnałów do procesu Node.js i poprawne zatrzymywanie kontenera przez Dockera.

Problem 4: Typowe pułapki w pliku docker-compose.yml

Plik docker-compose.yml pełni rolę serca całego środowiska kontenerowego. Drobne błędy w strukturze YAML, złe nazwy serwisów, brak depends_on lub niepoprawny kontekst budowania obrazu potrafią kompletnie zablokować uruchomienie projektu.

YAML jest wrażliwy na wcięcia i składnię. Każda pomyłka w tym obszarze przekłada się na błędy parsowania lub nieoczekiwane zachowania podczas startu serwisów. Dlatego warto znać kilka częstych źródeł problemów.

Błędy składni YAML i kontekst budowania

Najprostszym, a jednocześnie częstym błędem są nieprawidłowe wcięcia, mieszanie tabulatorów ze spacjami albo brak dwukropka po nazwie klucza. Docker Compose zwykle informuje o tym od razu komunikatem o błędzie parsowania.

Najlepsze praktyki:

• używaj tylko spacji (brak tabulatorów)
• zachowuj spójne wcięcia (np. 2 spacje)
• korzystaj z wbudowanej walidacji YAML w IDE

Kontekst budowania obrazu jest równie ważny. Przykłady:

services:
  backend:
    build: .

oznacza, że Dockerfile jest w tym samym katalogu co docker-compose.yml. Jeśli pliki backendu są w osobnym katalogu, możesz użyć:

services:
  backend:
    build:
      context: ./backend
      dockerfile: Dockerfile

Błędnie ustawiony context powoduje, że Docker nie znajduje Dockerfile’a lub nie widzi plików projektu podczas budowania.

depends_on i gotowość bazy danych

depends_on określa kolejność startu serwisów, ale nie gwarantuje, że zależny serwis jest już gotowy do obsługi połączeń. To szczególnie istotne przy PostgreSQL, który potrzebuje chwili na inicjalizację przed przyjmowaniem połączeń z Node.js.

Aby poprawić niezawodność, warto połączyć depends_on z healthcheck. Przykład:

services:
  db:
    image: postgres:14
    environment:
      POSTGRES_DB: mydatabase
      POSTGRES_USER: myuser
      POSTGRES_PASSWORD: mypassword
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U myuser -d mydatabase"]
      interval: 5s
      timeout: 5s
      retries: 5

  backend:
    build: .
    depends_on:
      db:
        condition: service_healthy

Dzięki temu backend Node.js wystartuje dopiero, gdy pg_isready potwierdzi gotowość bazy. Minimalizuje to losowe błędy połączeń podczas restartów całego środowiska.

Sieci w Docker Compose

Domyślnie Docker Compose tworzy jedną sieć dla wszystkich serwisów z danego pliku. To wystarcza w większości prostych setupów: backend, baza danych, ewentualnie frontend. Problemy pojawiają się, gdy ręcznie definiujesz sieci i przypadkowo izolujesz kontenery.

Jeśli nie masz mocnego powodu, aby konfigurować własne sieci, korzystaj z sieci domyślnej Dockera. Uprości to konfigurację i zmniejszy ryzyko błędów komunikacji między Node.js a PostgreSQL. Gdy jednak definiujesz sieci ręcznie, upewnij się, że wszystkie serwisy, które muszą się widzieć, należą do tej samej sieci.

Problem 5: Laptop programisty i środowisko Dockera

Nie wszystkie problemy wynikają z konfiguracji docker-compose czy Dockerfile. Często winny jest sam system operacyjny, ograniczenia zasobów lub stan Docker Desktop. Wtedy nawet idealnie przygotowany plik konfiguracyjny nie wystarczy, aby środowisko działało stabilnie.

Docker na laptopie wymaga pamięci RAM, CPU i stabilnie działającego Docker Engine. Gdy któryś z tych elementów zawodzi, objawy przypominają problemy z aplikacją, choć tak naprawdę chodzi o infrastrukturę.

Docker Desktop, zasoby systemowe i kolizje portów

Czasem docker-compose up nie działa, bo… Docker w ogóle nie jest uruchomiony. Warto zacząć od sprawdzenia, czy:

• Docker Desktop jest aktywny (ikona w pasku systemowym)
• na Linuxie działa usługa dockerd (sudo systemctl status docker)

Przy zbyt małej ilości RAM lub CPU przydzielonej dla Dockera kontenery mogą działać bardzo wolno lub się zawieszać. W ustawieniach Docker Desktop możesz zwiększyć limity pamięci i liczby rdzeni, co często rozwiązuje problemy przy kilku intensywnie działających serwisach.

Kolizje portów na hoście to kolejny klasyk. Jeśli np. masz lokalnie zainstalowanego PostgreSQL na porcie 5432, próba wystawienia kontenera na ten sam port zakończy się błędem. W takim wypadku:

• zmień mapowanie na np. 15432:5432
• zakończ proces używający portu, jeśli nie jest potrzebny

Wersje Docker Engine i Docker Compose

Starsze wersje Dockera lub Compose mogą nie obsługiwać nowszych opcji, takich jak bardziej rozbudowane depends_on z warunkiem service_healthy. Niekiedy mogą występować też błędy, które dawno naprawiono w późniejszych wydaniach.

Dobrą praktyką jest:

• regularna aktualizacja Docker Desktop
• sprawdzanie wersji: docker --version, docker-compose --version
• dopasowanie wersji pliku docker-compose.yml (np. version: '3.8') do możliwości używanej wersji Compose

Na etapie konfiguracji warto również upewnić się, że lokalne narzędzia (np. rozszerzenia do IDE) współpracują z aktualną wersją Dockera, co wpływa na wygodę pracy i wykrywanie błędów.

Jak skutecznie debugować i zapobiegać problemom

Znajomość typowych błędów to jedno, a skuteczne debugowanie i zapobieganie im – drugie. Dobrze skonfigurowane narzędzia oraz uporządkowane podejście oszczędzają mnóstwo czasu przy pracy nad aplikacją Node.js i PostgreSQL w kontenerach Docker.

W tej sekcji znajdziesz zestaw praktycznych technik, które warto stosować przy każdym problemie z docker-compose. To swoisty arsenał narzędzi, do którego możesz sięgać zawsze, gdy coś przestanie działać.

Kluczowe komendy i narzędzia debugowania

Najważniejsze komendy, z których warto korzystać na co dzień:

1. docker-compose logs <nazwa_serwisu> – podstawowe źródło informacji o błędach.
2. docker-compose ps – stan wszystkich kontenerów (Up/Exit/Restarting).
3. docker exec -it <nazwa_kontenera> /bin/sh lub /bin/bash – wejście do środka kontenera i ręczne sprawdzenie środowiska.
4. Testy połączeń z poziomu kontenera backendu, np.:
5. ping db
6. nc -vz db 5432 (jeśli nc jest dostępny)

Dzięki tym narzędziom możesz sprawdzić obecność zmiennych środowiskowych (env), dostępność portów i realne działanie aplikacji wewnątrz kontenera. To dużo bardziej wiarygodne niż samo patrzenie na konfigurację.

Plik .env i .dockerignore

Kolejnym elementem zwiększającym czytelność i bezpieczeństwo są pliki .env oraz .dockerignore. Pierwszy pozwala zarządzać zmiennymi środowiskowymi w jednym miejscu, drugi – ogranicza niepotrzebne pliki kopiowane do obrazu.

Przykład .env:

POSTGRES_DB=moja_aplikacja_db
POSTGRES_USER=user_apki
POSTGRES_PASSWORD=supertajnehaslo!
NODE_APP_PORT=3000

Fragment docker-compose.yml:

services:
  db:
    environment:
      POSTGRES_DB: ${POSTGRES_DB}
      POSTGRES_USER: ${POSTGRES_USER}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
  backend:
    ports:
      - "${NODE_APP_PORT}:${NODE_APP_PORT}"

Plik .dockerignore warto wykorzystać do wykluczenia node_modules, katalogu .git, logów oraz innych niepotrzebnych zasobów. Mniejszy kontekst budowania obrazu to szybsze buildy i mniej problemów z przenoszeniem środowiska.

Podsumowanie i praktyczne wnioski

Rozwiązywanie problemów z Docker Compose to umiejętność, która rozwija się z każdym projektem. Wiele typowych błędów wynika z drobiazgów: literówek, złych wcięć w YAML-u czy użycia localhost zamiast nazwy serwisu bazy danych. Świadomość tych pułapek pozwala dużo szybciej wrócić do pisania kodu.

Warto pamiętać o kilku kluczowych zasadach:

• Myśl kontenerowo – każdy kontener ma swoją sieć i zasoby, nie jest tylko „folderem” na laptopie.
• Buduj środowisko małymi krokami – najpierw baza, potem backend, następnie reszta serwisów.
• Korzystaj z logów i narzędzi debugujących – docker-compose logs, ps, exec to podstawy codziennej pracy.
• Dbaj o dokładność – w nazwach serwisów, zmiennych środowiskowych, mapowaniu portów i strukturze YAML.

Problemy z konfiguracją to naturalna część nauki każdego programisty. Z każdym kolejnym rozwiązanym błędem Twoje środowiska deweloperskie stają się stabilniejsze, a Ty szybciej osiągasz efekty. Dzięki odpowiedniemu wykorzystaniu docker-compose, PostgreSQL i Node.js mogą współpracować na Twoim laptopie bez walki z infrastrukturą – a Ty możesz skupić się na rozwijaniu aplikacji.