Optionale Dienste mit Docker-Compose-Profilen nur bei Bedarf starten¶
Veröffentlicht am 5. September 2026 · Geschätzte Lesezeit: 9 Minuten
Mit Docker-Compose-Profilen bleiben Kerndienste dauerhaft verfügbar, während Verwaltungsoberflächen, Test- oder Diagnosecontainer nur bei Bedarf laufen. Dazu erhält jeder optionale Dienst einen Profilnamen; Dienste ohne profiles bleiben standardmäßig aktiv.[1][2] Plane etwa 30 bis 45 Minuten für Sicherung, Anpassung und Funktionsprüfung ein.
Voraussetzungen
- Ein Linux-Server oder NAS mit Docker Engine und dem Docker-Compose-Plugin
- Ein bereits funktionierendes Compose-Projekt mit einer
compose.yaml - Terminalzugriff auf den Projektordner
- Ein aktuelles Backup der Compose-Datei und aller wichtigen Anwendungsdaten
1. Projektzustand und Compose-Version prüfen¶
Wechsle in den Ordner deines vorhandenen Compose-Projekts.[3] Ersetze <projektordner> durch dessen vollständigen Pfad:
Zeige die installierte Compose-Version an:[3]
Prüfe danach die unveränderte Konfiguration:[7]
docker compose config löst Compose-Dateien und Variablen auf und prüft das resultierende Anwendungsmodell; --quiet unterdrückt die normale Ausgabe.[7] Behebe vorhandene Fehler, bevor du ein Profil ergänzt.[7]
Zeige abschließend die aktuell zum Projekt gehörenden Container:[3]
Notiere die Dienstnamen und veröffentlichten Ports.[3] Ein Compose-Dienstname ist der Schlüssel direkt unter services: und wird später anstelle von <dienstname> eingesetzt.[1]
2. Konfiguration und Daten sichern¶
Erstelle eine datierte Kopie der Compose-Datei.[5]
Heißt deine Datei docker-compose.yml, ersetze compose.yaml in allen Befehlen durch diesen Namen.[3] Sichere eine vorhandene .env-Datei ebenfalls, ohne ihren Inhalt auszugeben:[5]
Die Dateikopien sichern nur die Konfiguration. Datenbanken, Bind-Mounts und benannte Volumes müssen zusätzlich mit dem dokumentierten Backup-Verfahren der jeweiligen Anwendung gesichert werden.[3]
Keine Volumes löschen
Verwende weder für die Umstellung noch für den Rückweg docker compose down -v. Der Parameter -v kann benannte Volumes und damit dauerhafte Anwendungsdaten entfernen.[3]
3. Kern- und optionale Dienste festlegen¶
Lass dir alle in der Datei definierten Profilnamen anzeigen:
Eine leere Ausgabe bedeutet, dass noch kein Profil definiert ist.[7] config --profiles ist die dafür vorgesehene Compose-Option.[7]
Teile die Dienste anschließend gedanklich in zwei Gruppen:[1][4]
- Kerndienste: Anwendung, Datenbank oder andere Komponenten, die beim normalen
docker compose up -dimmer benötigt werden.[1] - Optionale Dienste: Admin-Oberflächen, Debugger, Testwerkzeuge oder einmalig benötigte Hilfscontainer.[1][4]
Docker empfiehlt, Kerndiensten kein Profil zuzuweisen.[1]
Dienste ohne profiles sind immer aktiviert; ein Dienst mit Profil wird beim normalen Start ausgelassen.[1]
Ein Profil ist jedoch keine Zugriffskontrolle, sondern nur eine Startauswahl.[1][2]
4. Optionalen Dienst einem Profil zuordnen¶
Öffne die vorhandene Compose-Datei:[1]
Ergänze profiles direkt beim optionalen Dienst.[1][2] Das folgende Muster zeigt eine ständig aktive Anwendung und Datenbank sowie eine optionale Admin-Oberfläche.[1]
services:
app:
image: <vorhandenes-app-image-mit-festem-tag>
restart: unless-stopped
database:
image: <vorhandenes-datenbank-image-mit-festem-tag>
restart: unless-stopped
adminer:
image: <bereits-geprüftes-admin-image-mit-festem-tag>
profiles:
- tools
depends_on:
- database
ports:
- "127.0.0.1:${ADMINER_PORT:-8081}:8080"
Übernimm dieses Muster nicht als vollständigen neuen Stack, sondern ergänze nur den profiles-Abschnitt bei einem bereits eingerichteten optionalen Dienst.[1] Die Platzhalter bedeuten:
<vorhandenes-app-image-mit-festem-tag>ist das bereits verwendete Anwendungsimage samt geprüftem Versions-Tag oder Digest.<vorhandenes-datenbank-image-mit-festem-tag>ist das unveränderte Datenbankimage deines Stacks.<bereits-geprüftes-admin-image-mit-festem-tag>ist das zur Datenbank passende Verwaltungsimage mit festem, zuvor geprüftem Tag.toolsist der frei gewählte Profilname. Verwende ihn in Datei und Befehlen exakt gleich.[1]ADMINER_PORTist der Host-Port aus der.env-Datei; ohne Eintrag wird hier ersatzweise8081verwendet.[6]127.0.0.1bindet den Beispielport nur an den Server selbst. Für einen Zugriff aus dem Heimnetz ist stattdessen eine ausdrücklich gewählte interne Server-IP nötig.8080rechts vom Doppelpunkt ist nur ein Beispiel für den internen Port des Admin-Dienstes und muss zu dessen Dokumentation passen.[3]
Ersetze <vorhandenes-app-image-mit-festem-tag> durch das bereits geprüfte Anwendungsimage. Ersetze <vorhandenes-datenbank-image-mit-festem-tag> durch das unveränderte Datenbankimage. Ersetze <bereits-geprüftes-admin-image-mit-festem-tag> durch das passende Verwaltungsimage.
Profilnamen dürfen laut Docker aus Buchstaben, Ziffern, Punkten, Unterstrichen und Bindestrichen bestehen und müssen mit einem Buchstaben oder einer Ziffer beginnen.[1] Das Profil steht innerhalb des betreffenden Dienstes, nicht auf oberster Ebene.[1][2]
5. Port-Platzhalter geschützt setzen¶
Öffne eine vorhandene .env-Datei oder lege sie im Projektordner an:[5][6]
Ergänze den im Beispiel verwendeten Host-Port:[6]
8081 ist ein Beispiel und darf auf dem Host noch nicht durch einen anderen Dienst belegt sein.[3] Die .env-Datei darf keine echten Zugangsdaten in ein öffentliches Git-Repository bringen. Prüfe bei versionierten Projektordnern, ob sie ignoriert wird:
Eine Ausgabe mit .env bestätigt die Ignore-Regel. Eine leere Ausgabe bedeutet, dass du vor einem Commit die vorhandene .gitignore prüfen und gegebenenfalls .env ergänzen musst. Compose-Profile schützen weder Passwörter noch Tokens.[1][2]
6. Profil und Abhängigkeiten validieren¶
Prüfe die geänderte Datei:[7]
Der Befehl muss mit Exit-Code 0 enden.[7] Zeige danach alle definierten Profile:
In diesem Beispiel muss tools erscheinen.[7] Die Compose-Spezifikation warnt vor Abhängigkeiten, die durch nicht gemeinsam aktivierte Profile aus dem Anwendungsmodell ausgeschlossen werden: Solche Querverweise können die Konfiguration ungültig machen.[2]
Halte deshalb Kerndienste wie database normalerweise profilfrei.[1][2]
Falls eine optionale Komponente von einem weiteren optionalen Dienst abhängt, ordne beiden einen passenden gemeinsamen Profilnamen zu oder aktiviere alle benötigten Profile ausdrücklich.[1][2]
7. Nur die Kerndienste starten und prüfen¶
Übernimm die Konfiguration ohne aktiviertes Profil:[1]
Dienste ohne Profil starten normal; der Dienst adminer aus dem Beispiel bleibt deaktiviert.[1] Kontrolliere den Projektzustand:[3]
Prüfe zusätzlich die Anwendung über ihren normalen Browser- oder Client-Zugang. Die Prüfung ist für diesen Schritt bestanden, wenn die Kerndienste funktionieren und kein neuer Container des optionalen Dienstes gestartet wurde.[1]
Falls adminer bereits vor der Änderung lief, stoppe ihn gezielt:[1]
Entferne anschließend nur seinen gestoppten Container:[3]
adminer ist hier der Beispiel-Dienstname. Ersetze ihn durch deinen echten optionalen Dienst. Diese Befehle löschen keine benannten Volumes, dennoch musst du vor dem Entfernen den dokumentierten Datenspeicher des konkreten Werkzeugs prüfen.[3]
8. Optionales Profil gezielt aktivieren¶
Starte Kerndienste und das Profil tools im Hintergrund:[1][3]
--profile ist eine globale Compose-Option und steht deshalb vor up.[3] Kontrolliere danach alle Container:[3]
Rufe die Verwaltungsoberfläche nur über den vorgesehenen Weg auf. Bei der lokalen Beispielbindung kann ein SSH-Tunnel den Browserzugriff ermöglichen. Ersetze <server-ip> durch die interne IP oder den DNS-Namen deines Servers:
Ersetze <benutzer> durch deinen vorhandenen SSH-Benutzer und <server-ip> durch die erreichbare Serveradresse; 8081 ist der gewählte Host-Port. Öffne während des laufenden Tunnels lokal http://127.0.0.1:8081. Nutze nur einen bereits sicher eingerichteten SSH-Zugang.
Admin-Oberfläche nicht ins Internet stellen
Ein optionaler Admin-Dienst vergrößert während seiner Laufzeit die Angriffsfläche. Veröffentliche ihn nicht ungeschützt über Router, Reverse Proxy oder öffentliche Server-IP. Ein Profil ersetzt weder Anmeldung noch Firewall, HTTPS und Updates.[1][2]
9. Alternative Aktivierung und mehrere Profile verstehen¶
Ein Profil lässt sich für einen einzelnen Befehl auch über eine Umgebungsvariable aktivieren:[1][6]
COMPOSE_PROFILES aktiviert die genannten Profile zusätzlich zu allen Diensten ohne Profil.[6] Mehrere Namen werden durch Kommas getrennt.[6]
Mit der Befehlszeilenoption aktivierst du mehrere Profile durch Wiederholung:[1][3]
Alternativ verwendest du eine kommaseparierte Variable:[6]
Docker unterstützt außerdem --profile "*", um alle Profile zu aktivieren.[1] Verwende diese Variante auf einem produktiven Heimserver nur nach Prüfung, weil sie auch vergessene Test- oder Admin-Dienste starten kann.[1]
Wenn du einen profilierten Dienst ausdrücklich als Ziel angibst, kann Compose ihn auch ohne manuelles --profile starten.[1] Dabei werden dessen depends_on-Abhängigkeiten berücksichtigt, andere Dienste mit demselben Profil aber nicht automatisch gestartet.[1] Nutze für einen vorhersehbaren Gruppenstart deshalb den Profilnamen.[1]
10. Optionalen Dienst wieder sicher abschalten¶
Stoppe zuerst nur den optionalen Dienst:[1]
Entferne seinen gestoppten Container, wenn er nicht bis zum nächsten Einsatz bestehen bleiben soll:[3]
Prüfe danach den verbleibenden Stack:[3]
Die Kerndienste müssen weiterlaufen und die normale Anwendung muss erreichbar bleiben. Verwende nicht unbedacht docker compose --profile tools down: Der offizielle Ablauf entfernt dabei auch die aktivierten profilfreien Kerndienste des Projekts.[1]
11. Risiken, typische Fehler und Rückweg¶
Beachte vor dem dauerhaften Einsatz diese Grenzen:[1][2]
- Ein Profil spart nur dann Arbeitsspeicher und offene Zugänge, wenn der optionale Container tatsächlich gestoppt beziehungsweise entfernt ist.[1]
- Bereits vorhandene Container verschwinden nicht allein dadurch, dass du später
profilesin die YAML-Datei einträgst.[1] - Ein Profil schützt keine Geheimnisse und beschränkt keine Benutzerrechte.[1][2]
- Ein
latest-Tag kann sich unbemerkt ändern. Behalte vorhandene, geprüfte feste Tags oder Digests bei. - Eine lokale Portbindung ist nur vom Server selbst erreichbar; für Fernzugriff brauchst du einen kontrollierten Weg wie einen SSH-Tunnel.[3]
Typische Fehler lassen sich so eingrenzen:[1][2][7]
profileswird ignoriert: Prüfe die Einrückung. Der Block muss direkt im optionalen Dienst stehen.[1][2]toolserscheint nicht: Führedocker compose config --profilesim richtigen Projektordner aus und kontrolliere die Schreibweise.[7]- Der optionale Dienst startet bei normalem
up: Er lief möglicherweise schon vorher. Stoppe und entferne gezielt nur diesen Container.[1] - Eine Abhängigkeit fehlt: Halte notwendige Kerndienste profilfrei oder gib abhängigen optionalen Diensten kompatible Profile.[2]
- Der Port ist belegt: Wähle einen freien internen Host-Port in
.envund passe SSH-Tunnel sowie Browseradresse an. - Die Admin-Seite ist nicht erreichbar: Prüfe zuerst
docker compose ps --allund danach die letzten Protokollzeilen des echten Dienstnamens:
Ersetze <dienstname> durch den Eintrag unter services:. Veröffentliche keine Logs, die Tokens, Benutzernamen oder andere sensible Werte enthalten.
Für den vollständigen Rückweg suche zuerst die angelegte Sicherung:
Ersetze <sicherungsdatei> durch den gewünschten vollständigen Dateinamen und stelle die alte Compose-Datei wieder her:
Prüfe die wiederhergestellte Konfiguration:
Übernimm sie anschließend:
Kontrolliere danach docker compose ps --all, die Protokolle und den normalen Nutzerzugang.[3] Bei Datenproblemen reicht die YAML-Sicherung nicht aus; verwende dann das anwendungsspezifische Datenbackup.
Die praktische Anleitung von Event-Driven.io zeigt Profile als Möglichkeit, optionale Anwendungen und Werkzeuggruppen in einer gemeinsamen Compose-Datei zu verwalten.[4] Das öffentlich auffindbare Video „Stop Struggling with Docker Compose – Use These 10 Tricks Instead!“ führt Profile ab Minute 11:04 an einem Compose-Beispiel vor.[5] Für Syntax und Verhalten sind die aktuellen offiziellen Docker-Quellen maßgeblich.
Sources¶
[1] https://docs.docker.com/compose/how-tos/profiles — Docker Docs: Using profiles with Compose [2] https://docs.docker.com/reference/compose-file/profiles — Docker Docs: Compose profiles reference [3] https://docs.docker.com/reference/cli/docker/compose — Docker Docs: docker compose CLI [4] https://event-driven.io/en/docker_compose_profiles — Event-Driven.io: Docker Compose Profiles [5] https://www.youtube.com/watch?v=wSODnwNYglU — YouTube: Stop Struggling with Docker Compose – Use These 10 Tricks Instead! [6] https://docs.docker.com/compose/how-tos/environment-variables/envvars — Docker Docs: COMPOSE_PROFILES [7] https://docs.docker.com/reference/cli/docker/compose/config — Docker Docs: docker compose config
Fertig¶
Dein Compose-Projekt trennt jetzt dauerhafte Kerndienste von optionalen Werkzeugen. Die Funktionsprüfung ist erfolgreich, wenn docker compose config --quiet Exit-Code 0 liefert, docker compose config --profiles den erwarteten Profilnamen zeigt, docker compose up -d nur die Kerndienste betreibt, docker compose --profile tools up -d den optionalen Dienst zusätzlich startet und nach dessen gezieltem Stoppen die normale Anwendung weiter erreichbar bleibt.[1][7]