Docker Compose v2 auf Netcup installieren & gehärtete Multi-Container-Stacks architekturell aufbauen

Bevor Sie Docker Compose v2 auf einem Netcup VPS oder Root Server installieren, sollten Sie Ihr System zwingend auf Überreste des abgekündigten v1-Python-Skripts (/usr/local/bin/docker-compose) oder des veralteten Debian/Ubuntu-Universe-Pakets (docker-compose) überprüfen. Wenn beide Binärdateien gleichzeitig unter /usr/bin und /usr/local/bin existieren, führt dies in CI/CD-Pipelines und Cron-Wartungsskripten regelmäßig zu schwer auffindbaren Schema-Parsing-Fehlern.

Docker Compose v2 ist vollständig in Go kompiliert und integriert sich direkt in die Docker-CLI-Plugin-Architektur unter /usr/libexec/docker/cli-plugins/docker-compose. Da es ohne einen zwischengeschalteten Python-Interpreter nativ mit den containerd- und dockerd-API-Sockets kommuniziert, laufen Stack-Konvergenzen, parallele Image-Downloads (Parallel Pulls) und Log-Streams mit deutlich geringerem CPU- und RAM-Overhead ab.

Darüber hinaus arbeitet Compose v2 Hand in Hand mit docker-buildx-plugin (BuildKit). Jeder Aufruf von docker compose build nutzt automatisch paralleles Layer-Caching, sichere Build-Time-Secret-Mounts und optimierte Multi-Stage-Pipelines.

# 1. Veraltete v1-Pakete oder manuell per curl heruntergeladene Binaries entfernen
sudo apt remove -y docker-compose || true
sudo rm -f /usr/local/bin/docker-compose

# 2. APT-Paketindex aktualisieren und Compose-v2- sowie Buildx-Plugins installieren
sudo apt update
sudo apt install -y docker-compose-plugin docker-buildx-plugin

# 3. Speicherort des Plugin-Binaries und Laufzeitversion überprüfen
ls -la /usr/libexec/docker/cli-plugins/
docker compose version
docker buildx version

-rwxr-xr-x 1 root root 64231808 Oct 20 14:12 docker-compose
Docker Compose version v2.29.7
github.com/docker/buildx v0.17.1

Unstrukturierte Container-Deployments, die über /home/ubuntu oder /root verstreut sind, werden im Betrieb schnell unwartbar und führen dazu, dass automatisierte Restic-Backups wichtige Konfigurationsdateien übersehen. Auf produktiven Netcup-Servern sollten sämtliche Docker-Compose-Workloads unter /opt/stacks/<stack-name> mit strikten POSIX-Dateiberechtigungen standardisiert werden.

Darüber hinaus ist die Übergabe hochsensibler Zugangsdaten (wie PostgreSQL-Superuser-Passwörter, JWT-Signaturschlüssel oder S3-API-Tokens) über Inline-environment:-Variablen ein gravierendes Sicherheitsrisiko: Jeder Prozess oder Benutzer mit Zugriff auf docker inspect kann sämtliche Umgebungsvariablen im Klartext aus dem Container-Metadaten-JSON auslesen. Zudem werden Umgebungsvariablen an Kindprozesse vererbt, erscheinen in /proc/<pid>/environ und landen bei unbehandelten Ausnahmen häufig ungefiltert in Crash-Dumps oder APM-Telemetrie-Logs.

Trennen Sie stattdessen unkritische Laufzeitparameter (wie Zeitzonen, Ports und Image-Tags) in die .env-Datei ab und binden Sie sensible Zugangsdaten über das Top-Level-Element secrets: ein. Zur Laufzeit hängt Docker Compose jede Secret-Datei als schreibgeschütztes In-Memory-Dateisystem (tmpfs) unter /run/secrets/<secret_name> in den Zielcontainer ein. Wenn der Container gestoppt wird, wird der tmpfs-Mount sofort aus dem RAM entfernt, während die Quell-Passwortdateien auf dem Host durch chmod 0400 (root:root) vor unbefugtem Zugriff geschützt bleiben.

# Standardisierte Verzeichnisstruktur für den Stack anlegen
sudo mkdir -p /opt/stacks/core-app/{secrets,config,data}
sudo chown -R root:docker /opt/stacks/core-app
sudo chmod 0750 /opt/stacks/core-app
sudo chmod 0700 /opt/stacks/core-app/secrets

# Kryptografisch zufällige 32-Byte-Passwörter für Postgres und JWT-Signatur generieren
openssl rand -base64 32 | tr -d '\n' | sudo tee /opt/stacks/core-app/secrets/postgres_password.txt > /dev/null
openssl rand -base64 32 | tr -d '\n' | sudo tee /opt/stacks/core-app/secrets/app_jwt_secret.txt > /dev/null
sudo chmod 0400 /opt/stacks/core-app/secrets/*.txt

# Unkritische Laufzeitkonfiguration in .env speichern (für Compose-Variableninterpolation)
sudo tee /opt/stacks/core-app/.env > /dev/null <<'EOF'
COMPOSE_PROJECT_NAME=core_app
TZ=Europe/Berlin
POSTGRES_VERSION=16.4-alpine3.20
REDIS_VERSION=7.4-alpine
APP_IMAGE=ghcr.io/example-org/core-api:1.14.2
APP_PORT=127.0.0.1:8080
EOF
sudo chmod 0600 /opt/stacks/core-app/.env
sudo ls -la /opt/stacks/core-app/secrets/ /opt/stacks/core-app/.env

-rw------- 1 root docker   158 Nov  4 14:22 /opt/stacks/core-app/.env

/opt/stacks/core-app/secrets/:
total 16
drwx------ 2 root docker 4096 Nov  4 14:22 .
drwxr-x--- 5 root docker 4096 Nov  4 14:22 ..
-r-------- 1 root root     44 Nov  4 14:22 app_jwt_secret.txt
-r-------- 1 root root     44 Nov  4 14:22 postgres_password.txt

Wenn Sie mehrere Dienste in einer einzigen compose.yaml ohne eigene networks:-Definition deklarieren, platziert Docker Compose jeden Container in einer gemeinsamen Standard-Bridge (<projekt>_default). Jeder Container in dieser Bridge kann jeden Port jedes anderen Containers erreichen, und alle Container besitzen standardmäßig ausgehenden NAT-Zugang ins öffentliche Internet.

Unter der Haube setzt die Linux-Netzwerk-Engine von Docker die Bridge-Isolierung über zwei dedizierte Netfilter-Ketten durch: DOCKER-ISOLATION-STAGE-1 und DOCKER-ISOLATION-STAGE-2. Pakete, die ein benutzerdefiniertes Bridge-Interface (br-<id>) verlassen und für ein anderes Bridge-Interface bestimmt sind, werden auf Kernel-Ebene sofort verworfen (DROP). Gleichzeitig betreibt Docker in jedem benutzerdefinierten Bridge-Netzwerk einen eingebetteten DNS-Resolver unter 127.0.0.11, der ausschließlich diejenigen Servicenamen auflöst, die explizit in derselben Bridge registriert sind.

Um Ihren Netcup-Stack wirksam gegen Lateral Movement und SSRF-Angriffe (Server-Side Request Forgery) zu härten, unterteilen Sie Ihre Architektur in zwei voneinander isolierte Linux-Bridge-Netzwerke:

• ▪ frontend_net (Externe/Edge-Bridge): Wird ausschließlich zwischen Ihrem Reverse Proxy (Caddy/Traefik/Nginx) und dem Anwendungsserver (app) geteilt. Erlaubt ausgehende Internetverbindungen, falls die Webanwendung externe Webhooks oder Zahlungs-APIs aufrufen muss.
• ▪ backend_internal (internal: true Air-Gapped-Bridge): Verbindet app mit postgres und redis. Die Option internal: true weist den iptables/nftables-Treiber von Docker an, jegliches ausgehende Default-Gateway-NAT-Routing aus diesem Subnetz komplett zu blockieren. Selbst wenn ein Angreifer eine SQL-Command-Execution in PostgreSQL oder eine Lua-Ausführung in Redis erreicht, kann der Datenbank-Container keine ausgehenden Verbindungen aufbauen, um Schadcode nachzuladen oder Daten direkt auszuleiten.
• ▪ Explizites Subnetz-Pinning (ipam): Durch die Vergabe fester CIDR-Blöcke (wie 172.28.10.0/24 und 172.28.20.0/24) verhindern Sie, dass Docker zufällige Subnetze zuweist, die später mit WireGuard-VPN-Tunneln (10.x.x.x) oder internen Firmenrouten kollidieren.

# Nach dem Start des Stacks (Schritt 5) die erzeugten Linux-Bridges und iptables-Isolationsregeln prüfen:
docker network ls
sudo iptables -S DOCKER-ISOLATION-STAGE-1
sudo iptables -S DOCKER-USER

NETWORK ID     NAME                          DRIVER    SCOPE
8f3a1c92b104   core_app_backend_internal     bridge    local
c41e9021a77b   core_app_frontend_net         bridge    local
-P DOCKER-ISOLATION-STAGE-1 ACCEPT
-A DOCKER-ISOLATION-STAGE-1 -i br-8f3a1c92b104 ! -o br-8f3a1c92b104 -j DOCKER-ISOLATION-STAGE-2
-A DOCKER-ISOLATION-STAGE-1 -i br-c41e9021a77b ! -o br-c41e9021a77b -j DOCKER-ISOLATION-STAGE-2

Auf einem Netcup VPS 1000 G12.5 (4 vCores, 8 GB RAM) oder einem Root Server RS 1000 G12.5 (4 dedizierte AMD EPYC-Kerne, 8 GB ECC-RAM) gehören ungedrosselte Container zu den häufigsten Ursachen für ungeplante Server-Ausfälle. Wenn eine plötzliche Lastspitze oder ein Speicherleck dazu führt, dass Ihr Anwendungscontainer 7,8 GB RAM belegt, beendet der Out-Of-Memory-(OOM)-Killer des Linux-Kernels Prozesse anhand ihres oom_score – und trifft dabei häufig postgres oder dockerd mitten in einer laufenden Transaktion.

Ubuntu 24.04 und Debian 12 nutzen die einheitliche cgroupv2-Hierarchie unter /sys/fs/cgroup. Wenn Sie deploy.resources.limits und reservations in Ihrer compose.yaml definieren, übersetzt Docker Compose v2 diese Vorgaben direkt in die Kernel-Parameter memory.max, memory.high und cpu.max. Dadurch wird jeder Speicheranstieg strikt innerhalb des verursachenden Containers abgefangen, während das Host-Betriebssystem und sshd jederzeit reaktionsfähig bleiben.

Ebenso wichtig ist die Dimensionierung des POSIX-Shared-Memory-Segments (/dev/shm) für Datenbank-Container. Docker begrenzt /dev/shm standardmäßig auf lediglich 64 MB. Sobald PostgreSQL 16 auf einem Multi-Core-Server parallele Hash-Joins oder große Bitmap-Index-Scans ausführt, überschreiten die gemeinsamen Arbeitsspeicher-Segmente diese Grenze sofort und brechen Abfragen mit ERROR: could not resize shared memory segment: No space left on device ab. Das Setzen von shm_size: 256mb zusammen mit random_page_cost=1.1 und effective_io_concurrency=200 stimmt den Datenbank-Container optimal auf das lokale NVMe-Speicher-Subsystem von Netcup ab.

name: ${COMPOSE_PROJECT_NAME:-core_app}

x-logging-defaults: &default-logging
  driver: "json-file"
  options:
    max-size: "25m"
    max-file: "4"
    compress: "true"

services:
  db:
    image: postgres:${POSTGRES_VERSION:-16.4-alpine3.20}
    container_name: core_app_db
    restart: unless-stopped
    user: "70:70"
    shm_size: 256mb
    environment:
      TZ: ${TZ:-UTC}
      POSTGRES_DB: core_prod
      POSTGRES_USER: core_user
      POSTGRES_PASSWORD_FILE: /run/secrets/postgres_password
    secrets:
      - postgres_password
    command:
      - "postgres"
      - "-c"
      - "shared_buffers=768MB"
      - "-c"
      - "effective_cache_size=2048MB"
      - "-c"
      - "work_mem=16MB"
      - "-c"
      - "maintenance_work_mem=192MB"
      - "-c"
      - "random_page_cost=1.1"
      - "-c"
      - "effective_io_concurrency=200"
      - "-c"
      - "log_min_duration_statement=250"
    volumes:
      - pgdata:/var/lib/postgresql/data
    networks:
      - backend_internal
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U core_user -d core_prod -h 127.0.0.1"]
      interval: 10s
      timeout: 5s
      retries: 5
      start_period: 20s
    deploy:
      resources:
        limits:
          cpus: "1.50"
          memory: 3072M
        reservations:
          cpus: "0.50"
          memory: 1024M
    security_opt:
      - no-new-privileges:true
    logging: *default-logging

  redis:
    image: redis:${REDIS_VERSION:-7.4-alpine}
    container_name: core_app_redis
    restart: unless-stopped
    command:
      - "redis-server"
      - "--appendonly"
      - "yes"
      - "--appendfsync"
      - "everysec"
      - "--maxmemory"
      - "512mb"
      - "--maxmemory-policy"
      - "allkeys-lru"
      - "--save"
      - "900 1"
      - "--save"
      - "300 10"
    volumes:
      - redisdata:/data
    networks:
      - backend_internal
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 10s
      timeout: 3s
      retries: 5
      start_period: 10s
    deploy:
      resources:
        limits:
          cpus: "0.50"
          memory: 768M
        reservations:
          cpus: "0.15"
          memory: 256M
    security_opt:
      - no-new-privileges:true
    cap_drop:
      - ALL
    logging: *default-logging

  app:
    image: ${APP_IMAGE:-nginx:1.27-alpine}
    container_name: core_app_web
    restart: unless-stopped
    depends_on:
      db:
        condition: service_healthy
      redis:
        condition: service_healthy
    ports:
      - "${APP_PORT:-127.0.0.1:8080}:80"
    environment:
      TZ: ${TZ:-UTC}
      DB_HOST: db
      DB_PORT: 5432
      DB_NAME: core_prod
      DB_USER: core_user
      DB_PASSWORD_FILE: /run/secrets/postgres_password
      JWT_SECRET_FILE: /run/secrets/app_jwt_secret
      REDIS_URL: redis://redis:6379/0
    secrets:
      - postgres_password
      - app_jwt_secret
    networks:
      - frontend_net
      - backend_internal
    healthcheck:
      test: ["CMD-SHELL", "wget -qO- http://127.0.0.1:80/ > /dev/null || exit 1"]
      interval: 15s
      timeout: 5s
      retries: 3
      start_period: 15s
    deploy:
      resources:
        limits:
          cpus: "1.50"
          memory: 2048M
        reservations:
          cpus: "0.25"
          memory: 512M
    security_opt:
      - no-new-privileges:true
    logging: *default-logging

secrets:
  postgres_password:
    file: ./secrets/postgres_password.txt
  app_jwt_secret:
    file: ./secrets/app_jwt_secret.txt

volumes:
  pgdata:
    driver: local
  redisdata:
    driver: local

networks:
  frontend_net:
    driver: bridge
    ipam:
      config:
        - subnet: 172.28.10.0/24
  backend_internal:
    driver: bridge
    internal: true
    ipam:
      config:
        - subnet: 172.28.20.0/24

Führen Sie vor dem Start jeder geänderten compose.yaml stets docker compose config aus, um das vollständig interpolierte YAML zu prüfen – inklusive aller .env-Variablen, YAML-Anker (*default-logging) und relativen Secret-Dateipfade. Bei Tipp- oder Einrückungsfehlern bricht docker compose config sofort mit einer klaren Fehlermeldung ab, ohne laufende Container zu beeinträchtigen.

Während restart: unless-stopped den dockerd-Daemon anweist, einzelne Container nach einem Host-Reboot neu zu starten, bietet die Kapselung des gesamten Stacks in einer parametrisierten systemd-Service-Unit (/etc/systemd/system/compose-stack@.service) eine saubere Integration in systemctl status, journalctl-Boot-Abhängigkeiten (After=docker.service network-online.target) sowie kontrollierte docker compose stop-Hooks beim Herunterfahren.

cd /opt/stacks/core-app

# 1. YAML-Syntax und Variableninterpolation vorab prüfen
sudo docker compose config --quiet && echo "Compose syntax OK"

# 2. Images parallel herunterladen und Stack im Hintergrund starten (wartet auf Healthchecks)
sudo docker compose up -d --wait

# 3. Laufende Container, Health-Status und aktive cgroupv2-Ressourcenlimits prüfen
sudo docker compose ps
sudo docker stats --no-stream

Compose syntax OK
NAME             IMAGE                       STATUS                   PORTS
core_app_db      postgres:16.4-alpine3.20    Up 28 seconds (healthy)  5432/tcp
core_app_redis   redis:7.4-alpine            Up 28 seconds (healthy)  6379/tcp
core_app_web     nginx:1.27-alpine           Up 16 seconds (healthy)  127.0.0.1:8080->80/tcp

CONTAINER ID   NAME             CPU %     MEM USAGE / LIMIT   MEM %     NET I/O
a1b2c3d4e5f6   core_app_db      0.18%     64.2MiB / 3GiB      2.09%     4.1kB / 3.2kB
b2c3d4e5f6a1   core_app_redis   0.22%     9.8MiB / 768MiB     1.28%     2.8kB / 1.9kB
c3d4e5f6a1b2   core_app_web     0.05%     14.1MiB / 2GiB      0.69%     1.5kB / 1.1kB

[Unit]
Description=Docker Compose v2 Stack (%i)
Requires=docker.service
After=docker.service network-online.target
Wants=network-online.target

[Service]
Type=oneshot
RemainAfterExit=yes
WorkingDirectory=/opt/stacks/%i
ExecStartPre=/usr/bin/docker compose config --quiet
ExecStart=/usr/bin/docker compose up -d --remove-orphans --wait
ExecReload=/usr/bin/docker compose up -d --remove-orphans --wait
ExecStop=/usr/bin/docker compose stop --timeout 30
TimeoutStartSec=300
TimeoutStopSec=60

[Install]
WantedBy=multi-user.target