docker compose

Het hart van Docker Compose is het Compose file: een YAML-bestand waarin services, netwerken, volumes en configuraties staan. Dit bestand heet meestal `compose.yaml` of `docker-compose.yml`. Services worden beschreven met kenmerken zoals de Docker image, build-instructies, poorttoewijzingen, omgevingsvariabelen, afhankelijkheden en volume-koppelingen. Deze declaratieve aanpak maakt infrastructuur reproduceerbaar en versieerbaar — infrastructuur als code.

De Compose CLI: v2 en v5

De Compose CLI is de opdrachtregelinterface voor Docker Compose. De huidige ondersteunde versies zijn Compose v2 en v5. Deze worden meegeleverd met Docker Desktop en zijn beschikbaar voor Linux.

Sinds Compose v2 is de aanroep veranderd van `docker-compose` (met koppelteken) naar `docker compose` (zonder koppelteken). Het is nu een subcommando van `docker`. Deze wijziging integreert Compose soepeler met Docker Engine en zorgt voor een consistente gebruikerservaring.

Sinds Compose v2 negeert het hulpmiddel het topniveauveld `version` in het Compose-bestand. Vroeger moest je `version: '3.8'` opgeven om het formaat aan te duiden. Nu baseert Compose zich op de Compose Specification — een gemeenschappelijke standaard, onderhouden door de open source-gemeenschap en Docker. Deze spec maakt het Compose-bestandsformaat uniform, onafhankelijk van de gebruikerstoepassing of omgeving. Zolang je je aan de specificatie houdt, hoef je je geen zorgen te maken over compatibiliteit tussen Compose-versies.

Geschiedenis en versies

Docker Compose gaat terug tot 2014, toen Compose v1 uitkwam. Deze eerste versie vereenvoudigde het ontwikkelen van complexe multi-container toepassingen. v1 werd breed geadopteerd, maar had beperkingen: gebrekkige integratie met Docker Engine en beperkte functionaliteit bij het beheren van stacks in swarm-modus.

In 2020 kondigde Docker Compose v2 aan — een volledige herschrijving in Go. Deze versie biedt betere prestaties, betere foutafhandeling en strakkere integratie met het Docker-platform.

Ondersteuning voor Compose v1 eindigde na juni 2023. Vanaf dat moment werd v1 verwijderd uit toekomstige versies van Docker Desktop. De transitie naar v2 was noodzakelijk om technische schulden te verminderen en de ontwikkeling van nieuwe functies te versnellen binnen een modernere codebase.

Compose v2 voegde functionaliteit toe die ontwikkelaars meer controle geeft. `ssh`-agent forwarding voor het veilig bouwen van images kwam in Compose v2.4.0 GA. Hiermee kun je private Git-repositories klonen tijdens het build-proces zonder SSH-sleutels in de container te kopiëren.

Platformspecificatie in de build-sectie kwam in Compose v2.11.0. Dit specificeert expliciet op welk CPU-architectuur een image moet worden gebouwd — `linux/amd64` of `linux/arm64` — relevant bij ontwikkeling op Apple Silicon (M1/M2) Macs of multi-architectuur deployment.

De ontwikkeling blijft actief. Volgens de officiële GitHub-repository zijn er tot op heden 284 releases geweest. De meest recente versie, v5.5.0, verscheen op 17 augustus 2026. Docker Compose blijft een kernonderdeel van het Docker-ecosysteem.

Op 31 augustus 2021 werd de Compose CLI-code officieel overgezet naar de `docker/compose/v2`-repository. Deze migratie markeerde het einde van de oude codebase en het begin van een nieuwe ontwikkelingslijn. De code is open source onder de MIT-licentie.

Werken met Docker Compose

Stap 1: Maak een projectmap en een Compose-bestand

Maak een map voor je project en een bestand `compose.yaml`:

mkdir myapp && cd myapp && touch compose.yaml

Stap 2: Definieer de services

Open `compose.yaml` in je editor en definieer de services. Een voorbeeld met PostgreSQL, Redis en Nginx:

services:
  db:
    image: postgres:16
    environment:
      POSTGRES_USER: user
      POSTGRES_PASSWORD: password
    volumes:
      - db-data:/var/lib/postgresql/data
  redis:
    image: redis:7
  web:
    image: nginx:1.27
    ports:
      - "8080:80"
    depends_on:
      - db
      - redis</p><p>volumes:
  db-data:

Stap 3: Start de stack

Start alle services met één commando:

docker compose up -d

`-d` draait de containers op de achtergrond (detached mode).

Stap 4: Bekijk de status

Controleer of alle services draaien:

docker compose ps

Stap 5: Bekijk logs

Bekijk de logs van een specifieke service:

docker compose logs web

Stap 6: Stop de stack

Stop alle services:

docker compose down

Stap 7: Bouw images met platform-specificatie

Bouw een image voor een specifiek platform:

docker compose build --platform linux/arm64

Stap 8: Gebruik `docker stack deploy` voor swarm-modus

Deploy een stack op basis van een Compose-bestand in swarm-modus:

docker stack deploy --compose-file compose.yaml mystack

Verificatie

Controleer of de stack correct draait:

docker compose ps

De output toont elke service met status `Up` of `running`. Controleer ook of de services bereikbaar zijn op de verwachte poorten:

curl http://localhost:8080

Voor een stateless stack met PostgreSQL, Redis en Nginx bevestigt een HTTP-response van Nginx dat de stack werkt.

Veelgestelde problemen

1. `docker compose` werkt niet

Oorzaak: Compose v1 wordt gebruikt of Compose is niet geïnstalleerd. Oplossing: Gebruik `docker-compose` (met koppelteken) voor v1, of installeer Compose v2. Controleer de versie:

docker compose version

2. Fout: `version` wordt genegeerd

Oorzaak: Compose v2 negeert het `version`-veld. Oplossing: Verwijder het `version`-veld uit `compose.yaml`. Volg de Compose Specification.

3. SSH-agent forwarding werkt niet

Oorzaak: De SSH-agent is niet gestart of de key is niet geladen. Oplossing: Start de agent en laad de key:

eval "$(ssh-agent -s)" && ssh-add ~/.ssh/id_ed25519

Gerelateerde tools

`docker stack config` toont de uiteindelijke inhoud van een Compose-bestand na het mergen en interpoleren van variabelen. Handig voor debugging en validatie van complexe configuraties.

Whaler is een Linux-programma voor Docker-containerbeheer. Het start en stopt standalone containers en Docker Compose-toepassingen, bekijkt logs en biedt een eenvoudige interface voor basisacties. Ontwikkeld door Selivestrov Dmitriy, gelicenseerd onder GPL-3.0+, installeerbaar via Flatpak.

Verouderde versies

Oudere versies van het Compose-bestandsformaat — v1 en v2.x — worden niet langer actief onderhouden. De documentatie daarvoor is verplaatst naar de V1-branch van de Compose-repository op GitHub. De Compose Specification is sinds Compose 1.27.0+ de standaard.

Docker Compose verenigt complexe multi-service applicaties in een YAML-bestand, stelt ontwikkelaars in staat snel te itereren en zorgt voor consistentie tussen ontwikkel-, test- en productieomgevingen. Met een actieve ontwikkelingscyclus, sterke integratie met Docker en een duidelijke migratie weg van verouderde versies blijft Docker Compose een betrouwbare keuze voor containerized workloads. De vraag is niet of je Compose gebruikt, maar wanneer je de overstap naar v5 maakt.