Docker Compose: více služeb dohromady

Docker Compose: více služeb dohromady

V první části série jsme se naučili spustit jeden kontejner příkazem docker run. Reálná aplikace zřídka žije sama: přidává se k ní databáze, cache, a často i fronta zpráv. Tři služby jsou už tři samostatné příkazy docker run, v každém až desítka přepínačů, plus síť, kterou je třeba vytvořit ručně předem: docker network create app-net. Na pořadí spuštění přitom záleží, ale nic ho nezaručuje.

Problém je zvlášť patrný po restartu serveru. Kontejnery s restart: unless-stopped naběhnou samy, ale Docker neví, která služba má startovat první. Pokud aplikace naběhne dřív než databáze, první požadavek spadne s ECONNREFUSED — a je třeba aplikaci ručně restartovat, až je databáze připravená.

Docker Compose to řeší změnou samotného způsobu uvažování. Místo sekvence příkazů popisujete požadovaný stav v souboru docker-compose.yml: jaké služby mají existovat, jak jsou propojené, co na čem závisí. Pořadí spuštění, sítě a volumes bere na sebe Compose.

Jednu technickou věc je dobré vyřešit hned na začátku. Moderní příkaz je docker compose (dvě slova, plugin v Go, vestavěný do Docker Engine od verze 20.10+). Starý docker-compose (s pomlčkou, samostatný nástroj v Pythonu, větev v1) byl oficiálně vyřazen z podpory v květnu 2023. Ověřit, jaká verze je nainstalovaná:

docker compose version

Očekávaný výstup je něco jako Docker Compose version v2.x.x. Pokud příkaz nenajde, plugin se instaluje samostatně: apt install docker-compose-plugin.

2. Struktura docker-compose.yml

2.1 K řádku version:

Většina starších tutoriálů začíná soubor řádkem version: "3.8". V Compose v2 je tento řádek ignorován s varováním o zastaralosti — lze ho klidně odstranit, soubor bude kratší a bez zbytečného šumu v logách.

2.2 services: — klíč, jméno a DNS zároveň

Název každé služby pod klíčem services: plní dvojí roli: ve výchozím stavu z něj vzniká jméno kontejneru (<projekt>-<služba>-1) a zároveň je to DNS jméno, pod kterým je služba vidět ostatním kontejnerům ve stejné síti. Pokud nastavíte container_name: my-app explicitně, jméno bude předvídatelné, ale pak službu nelze škálovat příkazem docker compose up --scale app=3 — Compose nemůže vytvořit víc kontejnerů se stejným pevným jménem.

2.3 image: nebo build:

image: postgres:16-alpine stáhne hotový image z registru. build: . sestaví image z Dockerfile v aktuálním adresáři. Pokud Dockerfile neleží v kořeni projektu, uvede se explicitně:

build:
  context: ./app
  dockerfile: Dockerfile.prod

2.4 environment: — dva formáty zápisu

Proměnné prostředí lze psát jako mapu (DATABASE_URL: postgres://...) nebo jako seznam (- DATABASE_URL=postgres://...). Formát mapy se čte lépe při velkém počtu proměnných. Výraz ${VAR} se v obou formátech dosazuje z hodnoty v souboru .env nebo ze shell prostředí v okamžiku spuštění Compose.

2.5 ports: — jen to, co skutečně potřebuje být venku

Formát "3000:3000" znamená port hostu : port kontejneru. Bez sekce ports: zůstává služba nedostupná zvenčí, ale dostupná ostatním službám ve stejné síti Compose. Pro databázi v produkci ports: zpravidla není potřeba a je nežádoucí — otevírat port SŘBD do internetu bez naprosté nutnosti se nevyplatí.

2.6 volumes: u služby

Krátká forma je pgdata:/var/lib/postgresql/data. Dlouhá forma umožňuje explicitně uvést typ — type: volume pro named volume nebo type: bind pro bind mount. Named volume použitý ve službě musí mít odpovídající blok na horní úrovni souboru: volumes: pgdata: — právě tady Compose přebírá řízení jeho životního cyklu.

2.7 networks: — vlastní výchozí síť

Bez explicitní deklarace Compose vytvoří síť s názvem <projekt>_default a připojí do ní všechny služby. Vlastní síť se nastaví takto: u služby networks: [app-net], a dole v souboru networks: app-net: (prázdný blok znamená bridge síť s výchozím nastavením).

2.8 restart: — čtyři varianty

Pro produkci se jako výchozí vyplatí zvolit unless-stopped: služba přežije restart hostu, ale nebude se snažit naběhnout znovu, pokud jste ji zastavili vědomě.

2.9 command: a entrypoint:

Obě direktivy přepisují to, co je nastaveno v Dockerfile přes CMD nebo ENTRYPOINT. Typické použití je samostatný dev režim: command: npm run dev místo produkčního spouštěcího příkazu, bez nutnosti udržovat dva různé Dockerfile.

3. Reálný stack: Node.js + PostgreSQL + Redis

Dáme to všechno dohromady do jednoho funkčního příkladu — aplikace na Node.js, databáze PostgreSQL a cache Redis:

services:
  app:
    build: .
    ports: ["3000:3000"]
    env_file: .env
    environment:
      DATABASE_URL: postgres://user:${DB_PASSWORD}@db:5432/mydb
      REDIS_URL: redis://cache:6379
    depends_on:
      db:
        condition: service_healthy
      cache:
        condition: service_started
    networks: [app-net]
    restart: unless-stopped

  db:
    image: postgres:16-alpine
    environment:
      POSTGRES_USER: user
      POSTGRES_PASSWORD: ${DB_PASSWORD}
      POSTGRES_DB: mydb
    volumes: [pgdata:/var/lib/postgresql/data]
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U user -d mydb"]
      interval: 5s
      timeout: 5s
      retries: 10
    networks: [app-net]
    restart: unless-stopped

  cache:
    image: redis:7-alpine
    command: redis-server --maxmemory 128mb --maxmemory-policy allkeys-lru
    networks: [app-net]
    restart: unless-stopped

volumes:
  pgdata:

networks:
  app-net:

3.1 Proměnné POSTGRES_*

Oficiální image postgres čte POSTGRES_USER, POSTGRES_PASSWORD a POSTGRES_DB jen jednou — při první inicializaci clusteru na prázdném volume. Při dalších spuštěních, kdy volume už existuje, se tyto proměnné ignorují. Heslo pozdější změnou proměnné nezměníte — bude třeba provést ALTER USER uvnitř už běžící databáze.

3.2 depends_on s podmínkou service_healthy

Sekce depends_on: db: condition: service_healthy znamená, že app nezačne startovat, dokud healthcheck databáze nevrátí úspěch. Prostý zápis depends_on: [db], bez podmínky, čeká jen na start samotného procesu kontejneru — a PostgreSQL v tu chvíli ještě může inicializovat cluster a nepřijímat spojení. Přesně to způsobuje ECONNREFUSED při prvním požadavku po startu stacku.

3.3 Proč retries: 10, ne 5

Při interval: 5s a retries: 10 je Compose ochoten čekat na healthy stav databáze až 50 sekund celkem. To není s rezervou: první inicializace clusteru PostgreSQL sama o sobě může trvat 10-20 sekund, a při retries: 5 (25 sekund) může Compose označit databázi jako unhealthy ještě předtím, než skutečně naběhla.

3.4 redis:7-alpine a limit paměti

Tag redis:latest znamená, že obsah image se může kdykoli změnit; redis:7-alpine fixuje hlavní verzi a váží zhruba 40 MB. Přepínač --maxmemory 128mb v command: je v produkci kriticky důležitý: bez explicitního limitu se Redis ve výchozím stavu snaží využít veškerou dostupnou paměť hostu, a při aktivním cachování to může vést k OOM zabití sousedních kontejnerů.

3.5 Jak služby najdou jedna druhou podle jména

Řádek @db:5432 v DATABASE_URL funguje díky vestavěnému DNS Compose: jméno služby db se přeloží na interní IP adresu odpovídajícího kontejneru. To funguje jen pro služby ve stejné sekci networks: a nefunguje z hostu — z terminálu serveru jméno db nic neznamená.

4. .env — proměnné a secrets

4.1 Automatické načtení

Soubor .env ve stejném adresáři jako docker-compose.yml Compose načte automaticky, bez dalšího nastavení:

DB_PASSWORD=supersecret123
NODE_ENV=production

4.2 Dva různé mechanismy — nezaměňovat

Tady se snadno spletou dva podobné, ale odlišné způsoby, jak se hodnoty dostanou do kontejneru:

• ${DB_PASSWORD} přímo v compose souboru — dosazení proběhne během parsování YAML samotným Compose; hodnota se dostane do konfigurace, ale ne automaticky do proměnných prostředí kontejneru.
• env_file: .env v sekci služby — soubor se celý předá dovnitř kontejneru jako proměnné prostředí, dostupné aplikaci přes, například, process.env.DB_PASSWORD.

4.3 Ověření dosazení

docker compose config

Tento příkaz vypíše finální compose soubor už po dosazení všech ${VAR} — pohodlný způsob, jak se ujistit, že hodnoty z .env se skutečně načetly, ještě před spuštěním stacku.

4.4 Priorita zdrojů hodnot

Od nejvyšší priority po nejnižší: proměnná shell prostředí → hodnota ze souboru .env → výchozí hodnota přímo ve výrazu, pokud je zadaná jako ${VAR:-default}.

4.5 .gitignore

Soubor .env se musí přidat do .gitignore. Rozumný vzor je *.env a .env*, což zároveň vyloučí .env.local a .env.production, které se často přidávají později.

4.6 .dockerignore taky

.env musí být i v .dockerignore — jinak COPY . . v Dockerfile zkopíruje secrets přímo dovnitř image. Snadno se to ověří:

docker run --rm my-app cat /app/.env

Pokud příkaz vypíše obsah souboru, secret je už „zapečený" v image, a problém nevyřeší smazání souboru v dalším commitu: předchozí vrstva image ho stále obsahuje.

4.7 Přístupová práva k souboru

chmod 600 .env omezí čtení souboru jen na vlastníka — pro jeden VPS to stačí. Pro scénáře náročnější než jeden server (Swarm, víc týmů s různou úrovní důvěry) se vyplatí podívat se po Docker Secrets nebo HashiCorp Vault.

5. Sítě: jak služby najdou jedna druhou

5.1 Izolace podle projektů

Každý Compose projekt — obvykle samostatný adresář — dostane vlastní izolovanou síť. Služba app z jednoho projektu nevidí db jiného projektu, i když oba běží na stejném hostu.

5.2 Jméno projektu

Ve výchozím stavu se jméno projektu bere z názvu adresáře. Lze ho nastavit explicitně přepínačem docker compose -p myproject up nebo řádkem name: myproject na horní úrovni compose souboru — to ovlivňuje jména kontejnerů a sítí, a tedy i to, zda se dva stacky navzájem „uvidí".

5.3 Minimum otevřených portů

Pravidlo je jednoduché: ports: se píše jen u služeb, které skutečně potřebují přístup zvenčí. V příkladu výše je to app (3000:3000); db a cache takový blok nemají. Zbytečný řádek "5432:5432" v sekci databáze otevře PostgreSQL celému internetu — to je jedna z nejčastějších příčin kompromitace databáze na VPS.

5.4 Komunikace mezi různými stacky

Pokud spolu mají komunikovat dva nezávislé Compose projekty — například samostatný monitorovací stack, který potřebuje vidět metriky aplikace — použije se připojení k už existující síti:

networks:
  monitoring-net:
    external: true

6. Klíčové příkazy

7. Závěr

Teď je celý stack — aplikace, databáze, cache — popsaný v jednom souboru. git clone plus docker compose up -d vytvoří identické prostředí na jakémkoli serveru s Dockerem za minutu až dvě, bez jediného ručního kroku a bez otázky „v jakém pořadí to spustit".

Zůstává pár věcí, které docker-compose.yml sám o sobě neřeší. HTTPS a SSL certifikáty — stack potřebuje před sebou reverse proxy jako Nginx nebo Traefik. Víc domén na jedné IP adrese se také řeší na úrovni proxy, ne Compose. Limity zdrojů (mem_limit: 512m, cpus: "0.5") zatím chybí — a bez nich může jedna služba, která se vymkne kontrole, vzít veškerou paměť serveru ostatním. A logy jsou zatím dostupné jen přes docker compose logs, bez rotace a bez uchování po smazání kontejneru.

Přesně tyto mezery jsou tématem dalšího článku: před stack se postaví Nginx nebo Traefik, objeví se certifikát Let's Encrypt a automatické spuštění se přesune z ručního docker compose up -d na systemd jednotku, která stack po restartu serveru naběhne sama, bez účasti člověka.

Časté dotazy