What are we building?

By the end, a complete monitoring stack runs behind your Traefik proxy, reachable at https://grafana.YOUR_DOMAIN with valid HTTPS. Four building blocks interlock:

• Prometheus 3.13 – the time-series database. It pulls (scrapes) metrics from the other services at intervals and stores them with a timestamp.
• node-exporter 1.12 – delivers the host metrics: CPU, memory, load, disks, network interfaces.
• cAdvisor 0.55 – delivers the container metrics: CPU and RAM per running container, so you see which service is eating.
• Grafana 13.1 – the interface: ready-made dashboards that turn the Prometheus data into graphs and displays.

The decisive difference from Uptime Kuma: instead of “green/red” you get trends – you recognize that the RAM has been slowly filling up for days, before the server swaps. Only Grafana is reachable from outside; Prometheus, node-exporter and cAdvisor get no public route.

Prerequisites

• Confidence with Docker Compose – services, volumes, networks. If that’s still new: understanding Docker Compose.
• A running Traefik reverse proxy with the shared proxy network and the Let’s Encrypt resolver le – set up as in reverse proxy with Traefik.
• A subdomain grafana.YOUR_DOMAIN whose DNS record (A/AAAA) points to your server IP – see connecting a domain to your server.

Step by step

Step 1: Understand the architecture

Before we create files, the picture behind it – otherwise you debug blind. Prometheus works on the pull principle: the services don’t send their values somewhere, but Prometheus queries them actively. Every “exporter” provides its metrics under /metrics, Prometheus fetches them every 15 seconds and stores them in its time-series database. Grafana in turn queries Prometheus and draws the graphs from it.

Why pull instead of push at all? Because this way Prometheus always knows whether a target is alive: if an exporter doesn’t respond, that’s itself information (up = 0). You need no agents that actively “phone home”, and you can simply enter every new target into the configuration. An exporter is nothing magical – it’s a tiny web server that delivers a text list of current measurements under /metrics.

From this follows the security rule of this setup: node-exporter, cAdvisor and Prometheus have no authentication. So they must never stand open on the internet. Prometheus and cAdvisor we bind only to the internal Docker network monitoring; node-exporter runs in the host network (why is explained in step 4), but stays unreachable from outside thanks to UFW and the netcup firewall. Only Grafana is additionally on the proxy network and gets a Traefik route – the only service with a login and a public address.

Step 2: Create the project folder and configure Prometheus

Create the folder structure:

mkdir -p ~/monitoring/prometheus ~/monitoring/grafana/provisioning/datasources
cd ~/monitoring

Create the Prometheus configuration. It defines whom Prometheus queries at what interval:

# prometheus/prometheus.yml
global:
  scrape_interval: 15s
  scrape_timeout: 10s

scrape_configs:
  - job_name: prometheus
    static_configs:
      - targets: ["localhost:9090"]

  - job_name: node
    static_configs:
      - targets: ["host.docker.internal:9100"]

  - job_name: cadvisor
    static_configs:
      - targets: ["cadvisor:8080"]

Important: cadvisor:8080 appears as a service name – Docker resolves it automatically in the shared monitoring network. The node-exporter, on the other hand, runs in the host network (step 4 explains why) and is therefore addressed via host.docker.internal:9100 – Prometheus gets this name mapped to the Docker host’s IP via extra_hosts shortly. scrape_interval: 15s is a good compromise – often enough for meaningful curves, seldom enough to hardly create load.

Step 3: Provision the Grafana data source automatically

Instead of clicking the Prometheus data source into Grafana by hand later, we set it up via provisioning – as a file. That’s reproducible: after a rebuild, everything is immediately back, without clicking.

# grafana/provisioning/datasources/datasource.yml
apiVersion: 1

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

access: proxy means that Grafana itself (server-side) queries Prometheus – the user’s browser never talks to Prometheus directly. That’s exactly why Prometheus can stay internal.

Step 4: The Compose stack

Now the heart. Create the compose.yaml. Replace grafana.YOUR_DOMAIN and the Grafana password:

services:
  prometheus:
    image: prom/prometheus:v3.13.1
    container_name: prometheus
    command:
      - "--config.file=/etc/prometheus/prometheus.yml"
      - "--storage.tsdb.path=/prometheus"
      - "--storage.tsdb.retention.time=30d"
    volumes:
      - ./prometheus/prometheus.yml:/etc/prometheus/prometheus.yml:ro
      - prom_data:/prometheus
    extra_hosts:
      - "host.docker.internal:host-gateway"
    networks: [monitoring]
    restart: unless-stopped

  node-exporter:
    image: prom/node-exporter:v1.12.1
    container_name: node-exporter
    command:
      - "--path.rootfs=/host"
    network_mode: host
    pid: host
    volumes:
      - "/:/host:ro,rslave"
    restart: unless-stopped

  cadvisor:
    image: gcr.io/cadvisor/cadvisor:v0.55.1
    container_name: cadvisor
    privileged: true
    devices:
      - /dev/kmsg
    volumes:
      - /:/rootfs:ro
      - /var/run:/var/run:ro
      - /sys:/sys:ro
      - /var/lib/docker/:/var/lib/docker:ro
      - /dev/disk/:/dev/disk:ro
    networks: [monitoring]
    restart: unless-stopped

  grafana:
    image: grafana/grafana:13.1.0
    container_name: grafana
    depends_on: [prometheus]
    environment:
      GF_SECURITY_ADMIN_USER: admin
      GF_SECURITY_ADMIN_PASSWORD: YOUR_GRAFANA_PASSWORD
      GF_SERVER_ROOT_URL: https://grafana.YOUR_DOMAIN
      GF_USERS_ALLOW_SIGN_UP: "false"
    volumes:
      - grafana_data:/var/lib/grafana
      - ./grafana/provisioning:/etc/grafana/provisioning:ro
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.grafana.rule=Host(`grafana.YOUR_DOMAIN`)"
      - "traefik.http.routers.grafana.entrypoints=websecure"
      - "traefik.http.routers.grafana.tls.certresolver=le"
      - "traefik.http.services.grafana.loadbalancer.server.port=3000"
    networks: [monitoring, proxy]
    restart: unless-stopped

volumes:
  prom_data:
  grafana_data:

networks:
  monitoring:
  proxy:
    external: true

What matters here:

• --storage.tsdb.retention.time=30d keeps metrics for 30 days. More = more meaning, but also more storage. 30 days is a good start.
• node-exporter needs the host root directory (/:/host:ro,rslave), pid: host and network_mode: host to read real host values instead of container values. --path.rootfs=/host tells it where the host view is (read-only, :ro). The host network isn’t a nice-to-have: /proc/net is bound to the network namespace – in a normal bridge network, node-exporter would see only its own container interface (effectively just the scrape traffic), not the real host interfaces. The price: node-exporter thus listens on port 9100 of the host – your firewall keeps the port closed from outside, and Prometheus reaches it via the extra_hosts entry (host-gateway).
• cAdvisor needs privileged: true, the device /dev/kmsg and read mounts on /sys and /var/lib/docker to detect all containers. That’s unavoidable for container monitoring – that’s why cAdvisor stays strictly internal.
• Only grafana carries Traefik labels and is on the proxy network. The internal port is 3000. GF_SERVER_ROOT_URL must be the public HTTPS address, otherwise logins and redirects break behind the proxy.
• GF_USERS_ALLOW_SIGN_UP: "false" prevents strangers from creating their own account. Set a strong admin password – Grafana is publicly accessible.

Step 5: Start and check the Prometheus targets

Start the complete stack:

docker compose up -d

The first time, Docker downloads four images – that takes a moment. Check that all containers are running:

docker compose ps

All four services (node-exporter, cadvisor, prometheus, grafana) should be running. Now the decisive test: Does Prometheus see its targets? Since Prometheus stays internal, we query it from a short-lived container that’s on the same network (Compose calls the network monitoring_monitoring – project folder plus network name):

docker run --rm --network monitoring_monitoring curlimages/curl:8.21.0 \
  -s http://prometheus:9090/api/v1/query?query=up

In the JSON response there’s a "value" with "1" for each target – that means “reachable”. In the test all three jobs (prometheus, node, cadvisor) returned a 1. A 0 means Prometheus can’t scrape the target – then the section “When things go wrong” helps.

Step 6: Open Grafana and import dashboards

Open https://grafana.YOUR_DOMAIN. Traefik fetches the certificate on the first access (a few seconds). Log in with admin and your password from the compose.yaml. Thanks to provisioning, the Prometheus data source is already connected – you find it under Connections → Data sources:

Now the dashboards. Instead of building panels ourselves, we import two proven ones from the Grafana community. Go to Dashboards → New → Import, enter the ID and click Load:

Import these two:

• 1860 – “Node Exporter Full”: the comprehensive host dashboard.
• 19792 – “cAdvisor Dashboard”: metrics per container.

On import, select the Prometheus data source each time. After that, “Node Exporter Full” shows your host in real time – CPU usage, used RAM, disk, network, uptime:

The cAdvisor dashboard breaks the same load down to individual containers – here you immediately see which service draws how much CPU and RAM:

Step 7: Read the most important metrics correctly

A dashboard full of curves is of little use if you don’t know what to watch for. These five values in the “Node Exporter Full” dashboard tell you almost everything about the health of your server:

• CPU Busy. Short spikes are normal. It gets critical when the usage stays permanently high – then the server is the bottleneck.
• Sys Load. The load should on average be below the number of your CPU cores (in the test: 4 cores → load permanently above 4 is a warning sign of overload).
• RAM Used. Important: Linux uses free memory as a file cache – so “used” isn’t the same as “tight”. Only when little stays free besides the cache and SWAP Used rises does the server get sluggish. It’s exactly this creeping rise you want to see early.
• Root FS Used. The classic among server outages is the full disk. The trend shows you the fill rate – so you recognize days in advance when it’s getting tight.
• Network Traffic. Unusual spikes even though nothing is running can indicate a backup, an update or – in the bad case – unwanted traffic.

In the cAdvisor dashboard the most exciting question is: Which container draws the load? If your server suddenly gets slow, you see here at a glance whether it’s due to a single app – and don’t have to guess. This turns “something is slow” into a targeted “the photo import in container X is eating the CPU right now”.

When things go wrong

Maintenance & backups

• What you must back up. Important is the grafana_data volume: it contains your users, settings and self-built dashboards. Back it up encrypted and off-site with Restic. The Prometheus metrics (prom_data) are pure measurements – a loss is bearable, a backup optional.
• Updates. The image tags are pinned (prometheus:v3.13.1, grafana:13.1.0 …). To update, raise the tags, then docker compose pull && docker compose up -d. Read the release notes first – Grafana in particular occasionally changes defaults between major versions. You get cAdvisor from gcr.io; there v0.55.1 is currently the latest available image version.
• Security. Grafana is publicly accessible – assign a strong admin password and leave GF_USERS_ALLOW_SIGN_UP at false. Prometheus and cAdvisor stay internal; don’t expose them “just quickly” for debugging, they have no authentication.
• The next step: alerts. A dashboard only helps if you look at it. Grafana can trigger alerts itself at thresholds (RAM > 90%, disk almost full) and report e.g. via push. This turns the pretty dashboard into an early-warning system – a good connection to your existing Uptime Kuma.
• Honest about the effort: the stack runs largely on its own after setup. Occasionally plan a look at the retention time and storage usage, and bump the versions roughly quarterly.

What are we building?

By the end, Uptime Kuma 2.4 runs at https://status.YOUR_DOMAIN, secured via Traefik with automatic HTTPS. You’ve set up the first monitor (which checks every minute whether a service responds), connected a notification and optionally a public status page. For the first time we bind a service that doesn’t listen on port 80 – an important detail for all the following apps.

Prerequisites

• A running Traefik reverse proxy including the proxy network and a working Let’s Encrypt resolver le
• A DNS record status.YOUR_DOMAIN that points to the server

Step by step

Step 1: The compose.yaml

Own folder, own file:

mkdir -p ~/uptime-kuma && cd ~/uptime-kuma

services:
  uptime-kuma:
    image: louislam/uptime-kuma:2
    volumes:
      - kuma-data:/app/data
    networks:
      - proxy
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.kuma.rule=Host(`status.YOUR_DOMAIN`)"
      - "traefik.http.routers.kuma.entrypoints=websecure"
      - "traefik.http.routers.kuma.tls.certresolver=le"
      - "traefik.http.services.kuma.loadbalancer.server.port=3001"
    restart: unless-stopped

volumes:
  kuma-data:

networks:
  proxy:
    external: true

You know this from the Traefik tutorial – except for one new, decisive line:

      - "traefik.http.services.kuma.loadbalancer.server.port=3001"

Uptime Kuma listens internally on port 3001, not on 80. This line tells Traefik which port to forward the requests to. Without it, Traefik guesses wrong and you get a Bad Gateway. Remember the label – every app that doesn’t run on port 80 needs it.

The rest is the familiar pattern: no ports: (only reachable via Traefik), proxy network, named volume for the data.

Step 2: Start and first login

docker compose up -d
docker compose logs -f uptime-kuma

When Kuma is ready, the log ends with this line – from here the service accepts requests (Ctrl+C only ends the following):

[SERVER] INFO: Welcome to Uptime Kuma
[SERVER] INFO: Uptime Kuma Version: 2.4.0
[SETUP-DATABASE] INFO: Listening on:
[SETUP-DATABASE] INFO: -  http://localhost:3001

On the first start, Kuma creates its database in the volume – that takes a few seconds. Then open https://status.YOUR_DOMAIN in the browser. Uptime Kuma 2.x first asks for the database – for a setup like ours, SQLite is the right, simplest choice (select it, click Next). Right after that you create the admin account (username + strong password).

Step 3: Create the first monitor

A monitor is a recurring check. Click Add New Monitor and create one for Traefik itself:

• Monitor type: HTTP(s)
• Friendly name: Traefik Dashboard
• URL: https://traefik.YOUR_DOMAIN
• Heartbeat interval: 60 seconds
• Authentication: the Traefik dashboard is protected by basic auth (step 7 of the Traefik tutorial) – so choose HTTP Basic Auth as the authentication method below and enter the user and password. Without credentials, Kuma only gets 401 and reports the monitor as Down.

Save – after a few seconds the monitor is Up (green) and shows the response time.

Besides the simple HTTP(s) check, it pays to choose the matching monitor type:

• HTTP(s) – Keyword: additionally checks whether a certain word appears in the response text. This detects “the server responds, but shows an error page”.
• TCP port: for services without a web interface (e.g. a database, an SSH port). Only checks whether the port is open.
• Ping: the simplest reachability test via ICMP.
• Docker container: checks the container status directly via the Docker socket – handy for internal services without their own domain.
• Push: here the monitored service calls Kuma regularly. Ideal for cron jobs and backups: if the script doesn’t report in time, Kuma raises the alarm (“dead man’s switch”).

Create the matching monitor for every important service.

For the HTTP(s) monitor, the option “certificate expiry notification” is also worth it: Kuma then warns in good time before a TLS certificate expires. For services behind Traefik, Let’s Encrypt renews automatically – but this very automation occasionally fails silently (a DNS record is changed, port 80 accidentally closed). The monitor is your safety net and reports in while there are still days to fix it, instead of visitors suddenly facing a certificate warning.

Step 4: Set up notifications (email and Telegram)

A monitor without an alarm is just a pretty chart. Under Settings → Notifications → Setup Notification you create a channel. Uptime Kuma supports over 90 – we set up the two most common completely: email for the classic message and Telegram for push straight to the phone.

Email (SMTP)

Choose “Email (SMTP)” as the notification service and enter your mail provider’s data:

• Hostname / port: e.g. smtp.YOUR_PROVIDER.com and 587
• Security: STARTTLS (port 587) or TLS/SSL (port 465)
• Username / password: your SMTP credentials
• From / to address: which address the warning comes from and which it’s sent to

Click Test – within a few seconds a test message lands in the mailbox. Only when it really arrives are the credentials and port correct. Don’t forget to save.

Telegram

Telegram is ideal for instant push alerts to the phone – without your own mail server. You need two pieces of information:

1. Bot token: message @BotFather in Telegram, send /newbot, assign a name – BotFather replies with the token.
2. Chat ID: send your new bot any message, then open https://api.telegram.org/bot<YOUR_TOKEN>/getUpdates in the browser and read the chat.id from the response.

Enter the token and chat ID into the Telegram notification (Uptime Kuma links both helpers directly in the dialog) and click Test – the message should appear in the chat immediately.

If you want push messages entirely under your own control (without a Telegram server), ntfy comes later – self-hosted, with its own recipe in the series.

Step 5: A public status page (optional)

Kuma can publish a status page where visitors see whether your services are running. Here’s how:

1. Status Pages → New Status Page, then assign a name (e.g. “Serverküche Status”) and a slug (the URL, e.g. serverkueche) and click Next.
2. In the editor, Add Group (e.g. “Services”), and below it, add the desired monitors via the selection field.
3. Save at the top right – done. The page is then publicly reachable at https://status.YOUR_DOMAIN/status/serverkueche.

Only include what really everyone may see – better leave internal services out.

Step 6: Avoid false alarms – fine-tune the alarm behavior

A monitor that raises the alarm at every brief network hiccup is quickly ignored – and then you miss the real outage. In the monitor form you set the behavior appropriately:

• Retries: the service only counts as “Down” after n failed checks. 2–3 filters out individual dropouts without obscuring real outages for long.
• Heartbeat interval on failure: Kuma may check more often in the error case (e.g. every 20 seconds) to detect recovery quickly.
• Resend notification: Kuma can remind you every x minutes as long as a service is down – useful so an outage at night doesn’t get lost in a single mail.

Step 7: Monitor cron jobs with a push monitor

Classic monitors check from outside whether a service responds. For things that run silently in the background – a nightly backup, a sync script, a cron job – the push monitor flips the principle: not Kuma asks, but your script reports in. If the report fails to come, Kuma raises the alarm – the classic “dead man’s switch”.

Create a monitor of type Push. Kuma then shows you a unique push URL:

https://status.YOUR_DOMAIN/api/push/YOUR_TOKEN?status=up&msg=OK&ping=

You call this URL at the end of your script – for example after a successfully completed backup:

# ... your backup command ...
curl -fsS "https://status.YOUR_DOMAIN/api/push/YOUR_TOKEN?status=up&msg=Backup+OK" > /dev/null

Set the check interval in Kuma a bit more generously than your cron cadence (if the backup runs hourly, give Kuma e.g. 90 minutes of tolerance). If no curl comes in that time, the monitor goes to Down and you’re notified – so you learn about a backup that did not run, not only when you urgently need it.

Step 8: Secure the admin login with 2FA

Your Kuma login protects access to all monitors, the stored notification credentials and the status-page configuration – and it’s publicly on the net. So enable two-factor authentication: under Settings → Security → Two-Factor Authentication. Kuma shows a QR code you scan with an authenticator app (e.g. Aegis or 2FAS); to activate, you enter the generated code once.

When things go wrong

Maintenance & backups

• Back up: the complete heart of Kuma is the kuma-data volume (a SQLite database). Back it up regularly – if it’s gone, all monitors and the history are gone. We build the off-site backup for it in the Restic tutorial.
• Updates: the tag :2 stays on the 2.x series and brings bug fixes with docker compose pull && docker compose up -d. Before a jump to a new major version (e.g. later :3), read the release notes and back up the volume first.
• Coming from 1.x? The switch to :2 migrates the SQLite database automatically on the first start – that can take a moment, and going back to :1 is not intended afterwards. So back up the kuma-data volume beforehand, then you’re on the safe side. New installations (like above) aren’t affected.
• Honest limitation: a monitor that runs on the same server as the monitored services can’t warn you when the whole server fails – then Kuma is offline too. For that case, add an external watcher. Two cheap ways: a second Uptime Kuma on a small server (or at home) that only monitors this instance via HTTP – or a free external ping service that pings your public status page. This way you also get a notice when the whole host is gone – the only case a local monitor inherently can’t cover.

With that you’ve internalized the app pattern and monitor everything you hang behind Traefik from now on. What every further app requires are encrypted off-site backups with Restic – so your data survives a server crash.