Docker Compose Profiles erklärt

Acht Services liefen in einer einzigen compose.yml auf meiner Homelab-Maschine: ein Reverse Proxy, drei echte Anwendungen, Uptime Kuma, ein Log-Shipper, ein Backup-Container und ein Watchtower-Updater. Jedes docker compose up -d — selbst ein schneller Neustart einer einzigen defekten App — weckte auch den Backup-Job und den Updater, obwohl keiner der beiden mit diesem Neustart etwas zu tun hatte.

Was ein profiles:-Schlüssel tatsächlich bewirkt

Laut der Profiles-Referenz der Compose Specification startet ein Service, der mit einem oder mehreren Profilnamen markiert ist, nur dann, wenn eines dieser Profile aktiv ist — entweder über --profile <name> auf der Kommandozeile oder über eine kommagetrennte COMPOSE_PROFILES-Umgebungsvariable. Ein Service ganz ohne profiles:-Schlüssel gilt als dauerhaft aktiv: Er startet unabhängig davon, welche Profile Sie aktivieren — oder ob Sie überhaupt ein Profil aktivieren.

services:
  proxy:
    image: caddy:2
    # kein profiles:-Schlüssel — startet immer

  uptime-kuma:
    image: louislam/uptime-kuma:1
    profiles: ["monitoring"]

  backup:
    image: offen/docker-volume-backup:2
    profiles: ["backup"]

docker compose up -d startet hier nur proxy. docker compose --profile monitoring up -d startet proxy und uptime-kuma. Mehrere --profile-Flags lassen sich kombinieren: docker compose --profile monitoring --profile backup up -d aktiviert beide Gruppen gleichzeitig.

Der Stack vor den Profiles

Jeder Service in der Compose-Datei startete bei jedem up — egal, ob der Neustart überhaupt etwas mit ihm zu tun hatte:

Service	Rolle	Muss bei jedem Boot laufen?
caddy	Reverse Proxy	ja
app-a, app-b, app-c	die eigentlichen Anwendungen	ja
uptime-kuma	Uptime-Monitoring	nein — erst nötig, sobald der Stack läuft
loki + promtail	Log-Shipping	nein — nützlich, aber nicht boot-kritisch
offen/docker-volume-backup	nächtliches Volume-Backup	nein — läuft nach Cron-Zeitplan, nicht bei jedem Neustart
containrrr/watchtower	Auto-Update-Prüfung	nein — eine periodische Prüfung, keine Boot-Abhängigkeit

Vier der acht Services hatten keinen Grund, neu zu starten, nur weil app-b abgestürzt war und einen schnellen docker compose restart app-b brauchte. Sie starteten trotzdem neu, weil Compose ohne Profile keine Vorstellung davon hat, "welche Services für genau dieses up eigentlich relevant sind".

Aufteilung in core / monitoring / backup

services:
  caddy:
    image: caddy:2
    # dauerhaft aktiv: kein profiles-Schlüssel

  app-a:
    image: my-app-a:latest
    # dauerhaft aktiv: kein profiles-Schlüssel

  uptime-kuma:
    image: louislam/uptime-kuma:1
    profiles: ["monitoring"]

  loki:
    image: grafana/loki:3
    profiles: ["monitoring"]

  promtail:
    image: grafana/promtail:3
    profiles: ["monitoring"]

  backup:
    image: offen/docker-volume-backup:2
    profiles: ["backup"]

  watchtower:
    image: containrrr/watchtower
    profiles: ["backup"]

Alltägliche Neustarts laufen jetzt über docker compose up -d und starten nur caddy und die App-Container. Ein bewusstes docker compose --profile monitoring --profile backup up -d bringt den vollständigen Stack hoch, inklusive Monitoring und Backup/Update-Tooling — genau dann, wenn das tatsächlich beabsichtigt ist.

Vorher/Nachher: RAM und Startzeit

Ich habe beides auf derselben Maschine gemessen, mit zwei Kaltstarts des Stacks — einmal mit einfachem up, einmal mit --profile monitoring --profile backup — und docker stats ausgelesen, sobald jeder Container Up meldete:

Szenario	Gestartete Container	RAM-Verbrauch	Zeit bis alle Up
Vollständiger Stack (up, keine Profile angewendet)	8	1,9 GB	38s
Nur core (up, Profile ungenutzt)	4	0,9 GB	14s

Diese 24 Sekunden klingen erst mal nicht nach viel — bis es der Unterschied zwischen "eine App neu starten, fertig" und "eine App neu starten und auf vier unbeteiligte Container warten" ist.

Dev, Prod und COMPOSE_PROFILES

Derselbe Mechanismus deckt den häufiger dokumentierten Anwendungsfall ab: eine compose.yml für lokale Entwicklung und Produktion, statt separat gepflegter compose.dev.yml und compose.prod.yml. Markieren Sie reine Dev-Komfortfunktionen — einen Mail-Catcher, eine Admin-UI, einen ausführlichen Debug-Sidecar — mit profiles: ["dev"] und setzen Sie lokal einen Standardwert, damit Sie das Flag nicht jedes Mal erneut eintippen müssen:

export COMPOSE_PROFILES=dev   # oder in .env / der Umgebungskonfiguration Ihrer CI setzen

Mit COMPOSE_PROFILES=dev lokal gesetzt und in der .env der Produktivumgebung nicht gesetzt (oder leer), erzeugt dieselbe compose.yml zwei unterschiedliche Stacks, ohne eine einzige Service-Definition zu duplizieren — der Mechanismus ist dieselbe COMPOSE_PROFILES-Variable, die in der Referenz zu vordefinierten Umgebungsvariablen von Compose dokumentiert ist.

Häufige Fehler

• Ein Service, dem versehentlich der profiles:-Schlüssel fehlt. Er wird still dauerhaft aktiv und untergräbt die Aufteilung für genau diesen einen Service, ohne jede Fehlermeldung — wie in der Warnung oben beschrieben.
• Tippfehler bei einem Profilnamen auf der Kommandozeile. docker compose --profile monitorng up wirft keinen Fehler; es startet schlicht nichts Zusätzliches, weil kein Service zu einem nicht existierenden Profil passt.
• depends_on reicht über Profilgrenzen hinweg. Wenn app-a (dauerhaft aktiv) depends_on: [uptime-kuma] (profilgebunden) hat, versucht ein einfaches up, app-a zu starten, ohne jemals die genannte Abhängigkeit zu starten — siehe unseren Leitfaden zu Docker-Compose-Netzwerken, falls diese Abhängigkeit auch der Weg ist, über den Services sich gegenseitig erreichen. Halten Sie depends_on innerhalb derselben Profilgruppe, aus der es deklariert wird.
• Annahme, down respektiere Profile genauso wie up. docker compose down ohne passendes --profile-Flag entfernt nur Container aus dem in diesem Aufruf aktuell aktiven Profil-Set — siehe unseren Vergleich von Compose down, stop und kill, was jeder Teardown-Befehl tatsächlich entfernt.

FAQ

Wie starte ich einen Docker-Compose-Service nur in einem bestimmten Profil?

Fügen Sie dem Service in der `compose.yml` eine `profiles:`-Liste hinzu (z. B. `profiles: ["monitoring"]`), und starten Sie ihn dann mit `docker compose --profile monitoring up`. Ein Service ohne `profiles:`-Schlüssel startet immer, unabhängig davon, welche Profile aktiv sind.

Was passiert mit einem Service ohne zugewiesenes Profil?

Er gilt als dauerhaft aktiv — er startet bei jedem `docker compose up`, egal ob Sie ein `--profile`-Flag übergeben und unabhängig davon, welche Profilnamen Sie aktivieren.

Kann ich mehrere Docker-Compose-Profile gleichzeitig aktivieren?

Ja. Übergeben Sie `--profile` mehrfach (`docker compose --profile monitoring --profile backup up`), oder setzen Sie `COMPOSE_PROFILES=monitoring,backup` als kommagetrennte Umgebungsvariable.

Worin unterscheidet sich COMPOSE_PROFILES vom --profile-Flag?

`COMPOSE_PROFILES` setzt eine Standard-Profilliste, meist über eine `.env`-Datei, damit Sie `--profile` nicht bei jedem Befehl eintippen müssen. Ein explizites `--profile`-Flag auf der Kommandozeile hat weiterhin Vorrang davor.

Entfernt docker compose down auch Services außerhalb des aktiven Profils?

Nein. `docker compose down` wirkt nur auf das in diesem Aufruf aktive Profil-Set. Services, die unter einem Profil gestartet wurden, das beim `down`-Befehl nicht übergeben wird, laufen weiter.

Fazit

Profiles verwandeln "in dieser Compose-Datei startet immer alles zusammen" in "bei diesem konkreten up startet nur, was wirklich gebraucht wird" — ohne dafür in mehrere Compose-Dateien aufzuteilen. Die eigentliche Fehlerquelle liegt nicht in der Syntax, die pro Service nur einen Schlüssel braucht, sondern im vergessenen Service, der dauerhaft aktiv bleibt und die Aufteilung still aushebelt. Wenn Sie den Rest eines Multi-Service-Stacks darum herum aufbauen, deckt unser Leitfaden zu Docker Compose für Self-Hosting die Teile ab, die dieser Artikel voraussetzt.