Prometheus mit Docker installieren: Monitoring-Stack mit Grafana und Alertmanager

Prometheus ist seit seiner Entstehung 2012 bei SoundCloud zum De-facto-Standard für das Monitoring von Cloud-Native-Infrastrukturen geworden, und das nicht ohne Grund. Als zweites Projekt nach Kubernetes in die Cloud Native Computing Foundation (CNCF) aufgenommen, kombiniert es ein elegantes Pull-Modell, bei dem Metriken aktiv von Endpunkten abgeholt werden, mit einer leistungsstarken Abfragesprache namens PromQL und einer hochoptimierten lokalen Zeitreihendatenbank. Wer Microservices, Container, VMs oder physische Server überwachen will, kommt an Prometheus kaum vorbei. Diese Anleitung richtet sich an Administratoren, DevOps-Teams und ambitionierte Selfhoster, die den kompletten Monitoring-Stack aus Prometheus, Grafana, Alertmanager und Node Exporter per Docker Compose auf einem beliebigen Linux-Host aufsetzen wollen. Stand Oktober 2026 nutzt sie Prometheus v3.15.0, Grafana 13.2.3, Alertmanager v0.34.1 und Node Exporter v1.12.1.

Voraussetzungen

1. Linux-Host, VM oder NAS mit Docker Engine 20.10+ und dem Docker Compose Plugin v2 (docker compose-Befehl). Noch nicht installiert? Siehe Docker und Docker Compose auf Linux installieren.
2. Mindestens 2 GB RAM (empfohlen: 4 GB für größere Umgebungen mit vielen Targets)
3. Mindestens 20 GB freier Speicherplatz auf einem lokalen Dateisystem, kein NFS und kein AWS EFS (Vorgabe der TSDB)
4. Netzwerkzugang zu Port 9090 (Prometheus), 3000 (Grafana) und 9093 (Alertmanager) vom Browser aus
5. Optional: Reverse Proxy mit TLS (nginx, Traefik, Caddy) für den Produktivbetrieb, denn Prometheus selbst hat keine eingebaute Authentifizierung

Schritt 1: Eckdaten und Projektordner anlegen

Bevor Sie mit den Konfigurationsdateien beginnen, ein Blick auf die Eckdaten des Stacks:

Legen Sie die Ordnerstruktur an:

mkdir -p /opt/prometheus/{prometheus,alertmanager,grafana/provisioning/datasources}
cd /opt/prometheus

Verifizieren: ls /opt/prometheus sollte die Unterordner prometheus, alertmanager und grafana anzeigen.

Schritt 2: .env-Datei anlegen

Prometheus selbst benötigt keine Umgebungsvariablen; seine Konfiguration erfolgt ausschließlich über prometheus.yml und Command-Line-Flags. Grafana hingegen erwartet ein Admin-Passwort:

# /opt/prometheus/.env

# Grafana Admin-Zugang (Pflicht!)
GRAFANA_ADMIN_USER=admin
GRAFANA_ADMIN_PASSWORD=SicheresPasswortHierEintragen

# Optionale Port-Anpassungen
PROMETHEUS_PORT=9090
ALERTMANAGER_PORT=9093
GRAFANA_PORT=3000

# Retention (Standard 15 Tage, anpassbar z. B. auf 30d oder 90d)
PROMETHEUS_RETENTION=15d

Setzen Sie restriktive Berechtigungen, damit das Passwort nicht für alle Nutzer lesbar ist:

chmod 600 /opt/prometheus/.env

Verifizieren: ls -la /opt/prometheus/.env: Die Ausgabe muss -rw------- zeigen. Kein anderer Nutzer darf das Passwort lesen.

Schritt 3: prometheus.yml erstellen

Die Konfigurationsdatei definiert, welche Targets Prometheus scrapt und wie lange er auf Antwort wartet. Wichtig: Prometheus lädt diese Datei beim Start und kann sie ohne Neustart neu laden (mehr dazu in den FAQ).

# /opt/prometheus/prometheus/prometheus.yml

global:
  scrape_interval: 15s       # Alle 15 Sekunden Metriken abrufen
  evaluation_interval: 15s   # Alerting-Regeln alle 15 Sekunden auswerten

alerting:
  alertmanagers:
    - static_configs:
        - targets:
            - alertmanager:9093   # Docker-interner DNS-Name

rule_files:
  # Hier koennen spaeter Alert-Regeln eingebunden werden:
  # - /etc/prometheus/rules/*.yml

scrape_configs:
  # Prometheus scrapt sich selbst
  - job_name: "prometheus"
    static_configs:
      - targets: ["localhost:9090"]

  # Node Exporter: Host-Metriken
  - job_name: "node-exporter"
    static_configs:
      - targets: ["node-exporter:9100"]   # Service-Name als DNS

Verifizieren: Prüfen Sie die YAML-Syntax lokal:

docker run --rm --entrypoint promtool \
  -v /opt/prometheus/prometheus/prometheus.yml:/etc/prometheus/prometheus.yml \
  prom/prometheus:v3.15.0 \
  check config /etc/prometheus/prometheus.yml

Die Ausgabe endet mit SUCCESS: /etc/prometheus/prometheus.yml is valid prometheus config file syntax. Wichtig ist --entrypoint promtool: Ohne diese Angabe startet das Image den Prometheus-Server selbst und bricht mit unexpected promtool ab.

Schritt 4: alertmanager.yml erstellen

Für den ersten Start genügt eine Minimal-Konfiguration, die eingehende Alerts empfängt und im Null-Receiver verwirft. Im Produktiveinsatz tragen Sie hier E-Mail, Slack, Telegram oder Discord ein; wie das geht, zeigt Prometheus Alerts an Telegram und Discord senden: Alertmanager konfigurieren.

# /opt/prometheus/alertmanager/alertmanager.yml

route:
  receiver: "null"
  group_wait: 30s
  group_interval: 5m
  repeat_interval: 12h

receivers:
  - name: "null"

Verifizieren: cat /opt/prometheus/alertmanager/alertmanager.yml muss die Datei fehlerfrei ausgeben. Ein komplett leerer receivers-Block führt beim Start zu einem Fehler.

Schritt 5: Grafana-Datasource automatisch bereitstellen

Damit Grafana beim ersten Start Prometheus direkt als Datenquelle kennt, nutzen Sie das Provisioning-System. Entscheidend: Die URL muss http://prometheus:9090 lauten, also der Docker-interne DNS-Name des Services. http://localhost:9090 würde im Grafana-Container auf sich selbst zeigen und keine Daten liefern.

# /opt/prometheus/grafana/provisioning/datasources/prometheus.yml

apiVersion: 1

datasources:
  - name: Prometheus
    type: prometheus
    access: proxy
    url: http://prometheus:9090
    isDefault: true
    editable: true

Verifizieren: ls /opt/prometheus/grafana/provisioning/datasources/ zeigt die Datei prometheus.yml.

Schritt 6: compose.yaml erstellen und Stack starten

Jetzt kommt das Herzstück, die compose.yaml. Sie verwendet explizite Versionstags (v3.15.0, v1.12.1, v0.34.1, 13.2.3) statt latest, um unerwartete Breaking Changes bei Updates zu vermeiden. Prometheus v3.x ist die aktuelle stabile Generation, v2.x erhält keinen Long-Term-Support mehr. Die früher übliche Angabe --web.console.libraries und --web.console.templates fehlt bewusst: Seit Prometheus 3.0 enthält das Image keine Konsolen-Vorlagen mehr, die Flags hätten keine Wirkung.

# /opt/prometheus/compose.yaml

services:
  prometheus:
    image: prom/prometheus:v3.15.0
    container_name: prometheus
    restart: unless-stopped
    ports:
      - "${PROMETHEUS_PORT:-9090}:9090"
    volumes:
      - ./prometheus/prometheus.yml:/etc/prometheus/prometheus.yml:ro
      - prometheus_data:/prometheus
    command:
      - "--config.file=/etc/prometheus/prometheus.yml"
      - "--storage.tsdb.path=/prometheus"
      - "--storage.tsdb.retention.time=${PROMETHEUS_RETENTION:-15d}"
      - "--storage.tsdb.wal-compression"
      - "--web.enable-lifecycle"
    depends_on:
      - node-exporter

  node-exporter:
    image: prom/node-exporter:v1.12.1
    container_name: node-exporter
    restart: unless-stopped
    ports:
      - "9100:9100"
    volumes:
      - /proc:/host/proc:ro
      - /sys:/host/sys:ro
      - /:/rootfs:ro
    command:
      - "--path.procfs=/host/proc"
      - "--path.rootfs=/rootfs"
      - "--path.sysfs=/host/sys"
      - "--collector.filesystem.mount-points-exclude=^/(sys|proc|dev|host|etc)($$|/)"

  alertmanager:
    image: prom/alertmanager:v0.34.1
    container_name: alertmanager
    restart: unless-stopped
    ports:
      - "${ALERTMANAGER_PORT:-9093}:9093"
    volumes:
      - ./alertmanager/alertmanager.yml:/etc/alertmanager/alertmanager.yml:ro
    command:
      - "--config.file=/etc/alertmanager/alertmanager.yml"

  grafana:
    image: grafana/grafana:13.2.3
    container_name: grafana
    restart: unless-stopped
    ports:
      - "${GRAFANA_PORT:-3000}:3000"
    volumes:
      - grafana_data:/var/lib/grafana
      - ./grafana/provisioning:/etc/grafana/provisioning:ro
    environment:
      - GF_SECURITY_ADMIN_USER=${GRAFANA_ADMIN_USER:-admin}
      - GF_SECURITY_ADMIN_PASSWORD=${GRAFANA_ADMIN_PASSWORD:?Bitte GRAFANA_ADMIN_PASSWORD in .env setzen}
    depends_on:
      - prometheus

volumes:
  prometheus_data:
  grafana_data:

Starten Sie den Stack:

cd /opt/prometheus
docker compose up -d

Docker lädt die Images herunter und startet alle vier Container. Beim ersten Start kann das je nach Internetverbindung ein bis drei Minuten dauern.

Verifizieren: Prüfen Sie den Status aller Container:

docker compose ps

Erwartete Ausgabe (alle vier Container mit Status Up):

NAME             IMAGE                          STATUS          PORTS
alertmanager     prom/alertmanager:v0.34.1      Up              0.0.0.0:9093->9093/tcp
grafana          grafana/grafana:13.2.3         Up              0.0.0.0:3000->3000/tcp
node-exporter    prom/node-exporter:v1.12.1      Up              0.0.0.0:9100->9100/tcp
prometheus       prom/prometheus:v3.15.0        Up              0.0.0.0:9090->9090/tcp

Prüfen Sie zusätzlich die Health-Endpunkte:

curl -s http://localhost:9090/-/healthy   # Erwartet: Prometheus Server is Healthy.
curl -s http://localhost:9093/-/healthy   # Erwartet: OK
curl -I http://localhost:3000/            # Erwartet: HTTP/1.1 200 OK oder 302

Bei Problemen: docker compose logs prometheus bzw. docker compose logs grafana zeigt die genauen Fehlermeldungen.

Schritt 7: Prometheus Web-UI und Grafana einrichten

Öffnen Sie http://<server-ip>:9090 im Browser. In der Prometheus Web-UI sehen Sie unter Status → Target health die konfigurierten Scrape-Targets. Beide, prometheus und node-exporter, sollten den Status UP zeigen.

Testen Sie eine erste PromQL-Abfrage: Geben Sie im Abfragefeld unter Query up ein und klicken Sie auf „Execute“. Sie sehen Zeitreihen mit dem Wert 1 für jedes laufende Target, ein klares Zeichen, dass Prometheus Metriken sammelt.

Für Grafana rufen Sie http://<server-ip>:3000 auf. Melden Sie sich mit dem in der .env gesetzten Admin-Passwort an. Die Prometheus-Datenquelle ist dank Provisioning bereits eingebunden. Öffnen Sie Connections → Data sources und prüfen Sie, ob „Prometheus“ als Standard-Quelle aufgeführt ist.

Für einen sofortigen Mehrwert importieren Sie das bewährte Dashboard „Node Exporter Full“: Dashboards → New → Import, Dashboard-ID 1860 eingeben, Prometheus als Datenquelle auswählen und importieren. Sie sehen sofort CPU-Last, RAM-Nutzung, Disk-I/O und Netzwerkdurchsatz des Hosts. Wie Sie eigene Panels und Dashboards aufbauen, erklärt Grafana-Dashboards bauen: von der Datenquelle zum Panel.

Container-Metriken für den Docker-Host ergänzen Sie mit cAdvisor; wie das geht, zeigt cAdvisor mit Prometheus: Docker-Container-Metriken sammeln und in Grafana visualisieren.

Verifizieren: In Grafana unter Connections → Data sources → Prometheus meldet die Schaltfläche „Save & test“ eine erfolgreiche Verbindung. Unter Prometheus Status → Target health müssen beide Targets den Zustand UP zeigen. Steht node-exporter auf DOWN, prüfen Sie mit docker compose logs node-exporter auf Fehlermeldungen.

Schritt 8: Stack aktualisieren und Backup

Um den Stack auf neue Image-Versionen zu aktualisieren, passen Sie zunächst die Tags in der compose.yaml an und führen dann aus:

cd /opt/prometheus
docker compose pull
docker compose up -d

Docker Compose startet nur die Container neu, deren Image sich geändert hat. Die persistenten Daten in den benannten Volumes prometheus_data und grafana_data bleiben dabei erhalten.

Für ein Backup genügt es, den Ordner /opt/prometheus (Konfigurationsdateien und .env) zu sichern. Die TSDB-Daten in prometheus_data sind bei Verlust rekonstruierbar, da Prometheus die Targets erneut scrapt. Grafana-Dashboards und -Einstellungen in grafana_data sollten Sie jedoch regelmäßig exportieren oder das Volume ins Backup einschließen; eine solide Strategie dazu liefert 3-2-1-Backup-Strategie umsetzen.

Umstieg von Prometheus 3.12 und Grafana 10.4

Frühere Fassungen dieser Anleitung nutzten Prometheus v3.12.0, Node Exporter v1.7.0, Alertmanager v0.27.0 und Grafana 10.4.0. So ziehen Sie eine solche Installation nach:

1. Sichern: Stoppen Sie den Stack mit docker compose stop und sichern Sie den Projektordner sowie das Volume grafana_data, etwa mit docker run --rm -v prometheus_grafana_data:/data -v /var/backups:/backup alpine tar czf /backup/grafana-data.tgz -C /data .. Grafana stellt seine Datenbank beim ersten Start der neuen Version um, ein Zurück auf 10.4 gelingt nur mit dieser Sicherung.
2. Tags tauschen: Ersetzen Sie in der compose.yaml die vier Image-Tags durch die Werte aus Schritt 6 und entfernen Sie die beiden Zeilen --web.console.libraries und --web.console.templates, falls vorhanden.
3. Starten: docker compose pull und docker compose up -d. Prometheus und Alertmanager übernehmen TSDB und Konfiguration ohne Änderung; die Release-Notes zwischen den Versionen enthalten für diesen Aufbau keine nötigen Konfigurationsänderungen.
4. Grafana prüfen: Grafana 12 hat die Unterstützung für Angular-Plugins entfernt, Grafana 13 die Befehle grafana-cli und grafana-server (ersetzt durch grafana cli und grafana server). Dashboards mit alten Angular-Panels werden beim Öffnen auf die aktuellen Panels umgestellt; prüfen Sie importierte Dashboards danach auf leere Panels. Eigene Skripte gegen die Grafana-API, die Datenquellen über die numerische ID ansprechen, müssen auf die UID umgestellt werden.
5. Alertmanager-Metriken: Seit v0.34 unterscheidet das Label reason an alertmanager_notifications_failed_total zusätzlich authError und rateLimited. Eigene Alarme auf reason="clientError" passen Sie entsprechend an.

Im Test auf einem Debian-12-Host mit Docker CE wurde dieser Umstieg durchgespielt: Der alte Stack mit Grafana 10.4.0, provisionierter Datenquelle und einem angelegten Dashboard wurde mit den neuen Tags neu gestartet. Grafana 13.2.3 migrierte seine Datenbank in rund 15 Sekunden, Dashboard und Datenquelle blieben erhalten, der Verbindungstest der Datenquelle war erfolgreich, und beide Targets standen in Prometheus 3.15.0 auf up.

Verifizieren: Nach dem Update erneut docker compose ps ausführen: Alle Container müssen wieder mit Status Up laufen. Mit curl -s http://localhost:9090/api/v1/status/buildinfo | grep version lässt sich die laufende Prometheus-Version bestätigen.

Troubleshooting / Typische Fehler

1. „no such file or directory" beim Start / 0 Targets: Die prometheus.yml ist nicht korrekt gemountet. Prüfen Sie den Pfad in compose.yaml und stellen Sie sicher, dass die Datei unter ./prometheus/prometheus.yml relativ zum Projektordner existiert. docker compose logs prometheus zeigt die genaue Fehlermeldung.
2. „405 Method Not Allowed" bei POST /-/reload: Das Flag --web.enable-lifecycle fehlt im Abschnitt command der compose.yaml. Ergänzen Sie es und starten Sie Prometheus neu.
3. Grafana zeigt „No Data" trotz laufender Targets: Die häufigste Ursache ist eine falsche Datasource-URL. Öffnen Sie Connections → Data sources → Prometheus und stellen Sie sicher, dass die URL http://prometheus:9090 lautet, nicht http://localhost:9090. Außerdem: Stimmt der Zeitbereich im Dashboard-Panel mit den tatsächlich vorhandenen Daten überein?
4. Node Exporter bleibt auf DOWN: Auf manchen gehärteten Systemen fehlen die Berechtigungen für /proc- und /sys-Mounts. Prüfen Sie mit docker compose logs node-exporter. Falls --path.procfs-Fehler erscheinen, kann der Container im privilegierten Modus gestartet werden.
5. TSDB-Datenverlust nach Neustart: Prüfen Sie mit docker volume ls, ob die Volumes prometheus_prometheus_data und prometheus_grafana_data angelegt wurden. Bind-Mounts auf Verzeichnisse, die dem falschen Nutzer gehören (Prometheus läuft als UID 65534), können zu Rechteproblemen führen; benannte Volumes vermeiden das.
6. Port 9090 nicht erreichbar: Firewall prüfen. Auf UFW-Systemen: sudo ufw allow 9090/tcp. Ports 9090 und 9100 sollten generell nicht öffentlich exponiert werden, da Prometheus keine eingebaute Authentifizierung hat.
7. Alertmanager empfängt keine Alerts: Prüfen Sie, ob in prometheus.yml unter alerting.alertmanagers der korrekte Service-Name alertmanager:9093 eingetragen ist und ob rule_files auf existierende Dateien zeigen.

Häufige Fragen

Wie lade ich die Prometheus-Konfiguration neu, ohne den Container neu zu starten?

Senden Sie einen HTTP-POST an den Lifecycle-Endpunkt (erfordert das Flag --web.enable-lifecycle, das in dieser Anleitung bereits enthalten ist):

curl -X POST http://localhost:9090/-/reload

Alternativ geht auch ein SIGHUP-Signal an den Container: docker kill --signal=SIGHUP prometheus. Ein vollständiger Neustart ist damit nicht notwendig.

Wie füge ich einen neuen Scrape-Target hinzu?

Tragen Sie unter scrape_configs in der prometheus.yml einen neuen Job ein:

  - job_name: "mein-dienst"
    static_configs:
      - targets: ["mein-dienst-container:8080"]

Laden Sie anschließend die Konfiguration neu (siehe oben), ein Neustart ist nicht nötig. Prometheus fragt den angegebenen /metrics-Endpunkt dann alle 15 Sekunden ab.

Wie lange werden Metriken gespeichert und wie viel Speicherplatz wird benötigt?

Standard: 15 Tage, einstellbar über PROMETHEUS_RETENTION in der .env-Datei (z. B. 30d oder 90d). Als Faustregel gilt: ein bis zwei Bytes pro Sample. Bei 10.000 aktiven Zeitreihen und 15 Sekunden Scrape-Intervall entstehen grob 60 bis 120 MB pro Tag, also unter 1 GB pro Woche. Zusätzlich empfiehlt sich das Flag --storage.tsdb.retention.size als Obergrenze, um unkontrolliertes Disk-Wachstum zu verhindern.

Kann Prometheus auch Push-Metriken empfangen?

Prometheus ist primär für das Pull-Modell ausgelegt. Für kurzlebige Batch-Jobs und einmalige Prozesse gibt es den Pushgateway (prom/pushgateway, Port 9091) als Zwischenspeicher. Ab Prometheus v2.31+ unterstützt Prometheus zudem einen Remote Write Receiver per --web.enable-remote-write-receiver-Flag für direktes Push-Protokoll.

Wie betreibe ich Prometheus hinter einem Reverse Proxy?

Prometheus unterstützt URL-Präfixe per --web.external-url (z. B. http://monitoring.example.com/prometheus) und --web.route-prefix für den internen Pfad. Der Reverse Proxy muss den Pfad korrekt weiterleiten. Wie Sie Traefik als Docker-Reverse-Proxy mit automatischem HTTPS konfigurieren, zeigt Traefik als Docker-Reverse-Proxy mit automatischem HTTPS.

Warum keinen „latest"-Tag verwenden?

prom/prometheus:latest kann ohne Vorwarnung auf eine neue Hauptversion zeigen, also zum Beispiel von v2.x auf v3.x mit Breaking Changes in PromQL oder der TSDB. Explizite Tags wie v3.15.0 geben Ihnen Kontrolle darüber, wann Sie aktualisieren, und ermöglichen ein einfaches Rollback.

Fazit

Mit diesem Docker-Compose-Stack haben Sie ein vollständiges Monitoring-Fundament aufgebaut: Prometheus v3.15.0 sammelt Metriken nach dem Pull-Prinzip, Node Exporter liefert über 1.000 Host-Metriken, Grafana 13 macht die Daten in Dashboards sichtbar, und Alertmanager wartet bereits auf seine ersten Alert-Regeln. Die Kombination aus benannten Volumes, expliziten Image-Tags, WAL-Komprimierung und dem --web.enable-lifecycle-Flag sorgt für einen wartungsarmen, produktionstauglichen Betrieb. Der nächste sinnvolle Schritt ist die Konfiguration echter Alert-Regeln und das Anbinden weiterer Exporter für Datenbanken, Container oder Anwendungen; der Stack ist dafür von Anfang an vorbereitet.

Weiterführende Anleitungen und Quellen

1. Prometheus Alerts an Telegram und Discord senden: Alertmanager konfigurieren
2. cAdvisor mit Prometheus: Docker-Container-Metriken sammeln und in Grafana visualisieren
3. Grafana-Dashboards bauen: von der Datenquelle zum Panel
4. Beszel Server Monitoring mit Docker einrichten
5. Docker und Docker Compose auf Linux installieren (Ubuntu/Debian)
6. Traefik als Docker-Reverse-Proxy mit automatischem HTTPS
7. 3-2-1-Backup-Strategie umsetzen

Offizielle Quellen: Prometheus Installationsdokumentation, Prometheus GitHub Repository, prom/prometheus auf Docker Hub, Prometheus Storage-Dokumentation.