Self-hosting Uptime Kuma on a VPS: what it watches, and the dashboard's own NAT problemUptime Kuma selbst hosten auf einem VPS: was es überwacht, und das eigene NAT-Problem des Dashboards

What it actually watchesWas es tatsächlich überwacht

Uptime Kuma ships with a long list of monitor types; five cover almost every real use:Uptime Kuma bringt eine lange Liste an Monitor-Typen mit; fünf davon decken fast jeden echten Anwendungsfall ab:

• HTTP(s) — requests a URL on a schedule, checks the status code, and can also match a keyword or a JSON path in the response body, so "returns 200" and "returns 200 with an empty cart" are different alerts.HTTP(s) — ruft in einem festen Intervall eine URL auf, prüft den Statuscode und kann zusätzlich ein Schlüsselwort oder einen JSON-Pfad im Antwort-Body abgleichen, sodass „liefert 200“ und „liefert 200 mit leerem Warenkorb“ unterschiedliche Alarme sind.
• TCP Port — opens a raw socket and confirms something answers. This is how you watch a database, an SSH daemon, or any service with no HTTP interface at all.TCP Port — öffnet einen rohen Socket und bestätigt, dass etwas antwortet. So überwachst du eine Datenbank, einen SSH-Daemon oder jeden anderen Dienst ganz ohne HTTP-Schnittstelle.
• Ping — plain ICMP. Cheapest possible check, and the first thing to fail when a whole host is gone rather than just one service on it.Ping — reines ICMP. Der billigstmögliche Check, und das Erste, was ausfällt, wenn der ganze Host weg ist und nicht nur ein einzelner Dienst darauf.
• DNS Record — resolves a record on an interval and can alert when the answer changes, which catches an expired domain or a registrar mistake before a customer does.DNS Record — löst einen Eintrag in einem Intervall auf und kann alarmieren, wenn sich die Antwort ändert, was eine abgelaufene Domain oder einen Registrar-Fehler auffängt, bevor ein Kunde es tut.
• Push — the direction reverses. Instead of Uptime Kuma reaching out, your job or service calls a unique heartbeat URL on its own schedule, and Kuma alerts if that call stops arriving. It is the only sane way to monitor a cron job, a worker behind a firewall, or anything that has no public endpoint to poll.Push — die Richtung kehrt sich um. Statt dass Uptime Kuma nach außen greift, ruft dein Job oder Dienst nach eigenem Zeitplan eine eindeutige Heartbeat-URL auf, und Kuma schlägt Alarm, wenn dieser Aufruf ausbleibt. Es ist der einzig vernünftige Weg, einen Cron-Job, einen Worker hinter einer Firewall oder irgendetwas ohne öffentlichen Endpunkt zum Abfragen zu überwachen.

Group monitors, tag them, and set the check interval and retry count per monitor — a flaky endpoint that fails once a day does not need to page you on the first miss.Gruppiere Monitore, versieh sie mit Tags und stelle Prüfintervall und Wiederholungszahl pro Monitor ein — ein wackeliger Endpunkt, der einmal am Tag ausfällt, muss dich nicht schon beim ersten Fehlschlag alarmieren.

Where the checks run from mattersWoher die Prüfungen laufen, ist wichtig

One thing worth saying plainly: a monitor is only ever telling you what things look like from wherever it is running. Point Uptime Kuma at a VPS in Dallas or Charlotte and the ping and HTTP timings it reports are US East/Central numbers. That is a perfectly good signal for "is the service up or down", and a mediocre one for "how fast does this feel to a visitor in Frankfurt" — for that you would want a check running near the visitor, not near you. Use Kuma for availability and treat any latency number it shows as from this one vantage point, not a global truth.Eine Sache, die man klar sagen sollte: Ein Monitor sagt dir immer nur, wie die Dinge von dort aussehen, wo er läuft. Setzt du Uptime Kuma auf einen VPS in Dallas oder Charlotte, sind die gemeldeten Ping- und HTTP-Zeiten Werte aus US East/Central. Das ist ein völlig brauchbares Signal für „ist der Dienst oben oder unten“, und ein mittelmäßiges für „wie schnell fühlt sich das für einen Besucher in Frankfurt an“ — dafür bräuchtest du eine Prüfung, die nah am Besucher läuft, nicht nah an dir. Nutze Kuma für Verfügbarkeit und behandle jede angezeigte Latenzzahl als von genau diesem einen Standpunkt aus, nicht als globale Wahrheit.

SizingDimensionierung

Uptime Kuma is Node.js plus SQLite, and it is genuinely light: monitoring a few dozen endpoints on short intervals idles well under 100 MB of RAM. The database only grows with check history, and by default it keeps that history indefinitely, so the honest ceiling on disk is however many monitors times however many months you let it accumulate — small numbers either way unless you are watching hundreds of things at ten-second intervals. It idles far under 1 GiB total, and the smallest tier with a bit of room for the OS and Docker itself is enough for a personal or small-team setup.Uptime Kuma ist Node.js plus SQLite und wirklich leichtgewichtig: Die Überwachung von ein paar Dutzend Endpunkten in kurzen Intervallen läuft im Leerlauf deutlich unter 100 MB RAM. Die Datenbank wächst nur mit der Prüfhistorie, und standardmäßig behält sie diese Historie unbegrenzt, sodass die ehrliche Obergrenze beim Speicherplatz sich aus der Anzahl der Monitore mal der Anzahl der Monate ergibt, die du sie ansammeln lässt — in beiden Fällen kleine Zahlen, außer du beobachtest Hunderte Dinge im Zehn-Sekunden-Takt. Insgesamt liegt es im Leerlauf weit unter 1 GiB, und die kleinste Stufe mit etwas Spielraum für das Betriebssystem und Docker selbst reicht für ein privates Setup oder ein kleines Team.

The compose fileDie Compose-Datei

services:
  uptime-kuma:
    image: louislam/uptime-kuma:1.23.16   # pin a real tag — check Docker Hub's tag list for the current release before you deploy
    restart: unless-stopped
    volumes:
      - uptime-kuma:/app/data
    ports:
      - "127.0.0.1:3001:3001"

volumes:
  uptime-kuma:

Bind the published port to 127.0.0.1, the same as any other web app on the box: the only thing that should reach port 3001 directly is the reverse proxy running on the same host, not the open internet. Bring it up with docker compose up -d, then open http://127.0.0.1:3001 over an SSH tunnel once to create the admin account before you put a domain in front of it.Binde den veröffentlichten Port an 127.0.0.1, genau wie bei jeder anderen Webanwendung auf der Maschine: Das Einzige, was Port 3001 direkt erreichen soll, ist der Reverse-Proxy auf demselben Host, nicht das offene Internet. Starte es mit docker compose up -d, öffne dann einmal http://127.0.0.1:3001 über einen SSH-Tunnel, um das Admin-Konto anzulegen, bevor du eine Domain davorsetzt.

HTTPS and the reverse proxy — the thing that bites laterHTTPS und der Reverse-Proxy — das Ding, das dich später beißt

Caddy is the least fuss:Caddy macht am wenigsten Aufwand:

status.example.com {
    reverse_proxy 127.0.0.1:3001
}

That line is genuinely the whole config, and it is enough on its own because Caddy detects a WebSocket upgrade and proxies it transparently. That detail matters here specifically: the Uptime Kuma dashboard is not a page that reloads, it is a Socket.IO connection that pushes monitor state live. If you put nginx in front instead, the dashboard will load — logo, monitor list, everything looks fine — and then every status just sits frozen, because nginx does not forward a WebSocket upgrade unless you tell it to:Diese Zeile ist wirklich die gesamte Konfiguration, und sie reicht für sich allein, weil Caddy ein WebSocket-Upgrade erkennt und es transparent durchreicht. Dieses Detail ist hier besonders wichtig: Das Uptime-Kuma-Dashboard ist keine Seite, die neu lädt, sondern eine Socket.IO-Verbindung, die den Monitor-Status live pusht. Setzt du stattdessen nginx davor, lädt das Dashboard — Logo, Monitorliste, alles sieht in Ordnung aus — und danach bleibt jeder Status einfach eingefroren, weil nginx ein WebSocket-Upgrade nicht weiterleitet, wenn man es ihm nicht sagt:

location / {
    proxy_pass http://127.0.0.1:3001;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $host;
}

Miss those three headers and you get a working-looking dashboard that never actually updates, which is a genuinely confusing bug to chase the first time you hit it.Fehlen diese drei Header, bekommst du ein scheinbar funktionierendes Dashboard, das sich nie wirklich aktualisiert — ein Bug, der beim ersten Mal wirklich verwirrend zu jagen ist.

Read this before you buy: the NAT IPv4 catchLies das, bevor du kaufst: die NAT-IPv4-Falle

Here is the part that has nothing to do with monitoring and everything to do with the network the VPS sits on. Split the traffic into two directions:Hier kommt der Teil, der nichts mit Monitoring zu tun hat und alles mit dem Netzwerk, in dem der VPS steckt. Teile den Traffic in zwei Richtungen:

• Outbound — the monitors themselves. Every HTTP, TCP, ping and DNS check Uptime Kuma runs is Kuma reaching out to somewhere else. NAT IPv4 does not affect any of this. A VPS with a shared address and a handful of forwarded ports can watch a thousand endpoints without issue, because it never needs to be reached.Ausgehend — die Monitore selbst. Jeder HTTP-, TCP-, Ping- und DNS-Check, den Uptime Kuma ausführt, ist Kuma, das nach draußen zu etwas anderem greift. NAT IPv4 betrifft davon nichts. Ein VPS mit einer geteilten Adresse und einer Handvoll weitergeleiteter Ports kann tausend Endpunkte problemlos überwachen, weil er selbst nie erreichbar sein muss.
• Inbound — the dashboard, the status page, and push monitors. Loading https://status.example.com from your laptop, and a cron job calling its heartbeat URL, both need something to answer on 443 from the outside. If your plan gives you NAT IPv4 — a shared address with a small number of forwarded ports rather than 80 and 443 of your own — a plain HTTPS domain on the standard port will not resolve to your box.Eingehend — das Dashboard, die Statusseite und Push-Monitore. https://status.example.com von deinem Laptop zu laden und ein Cron-Job, der seine Heartbeat-URL aufruft, brauchen beide etwas, das von außen auf 443 antwortet. Gibt dir dein Plan NAT IPv4 — eine geteilte Adresse mit einer kleinen Zahl weitergeleiteter Ports statt eigenen 80 und 443 —, löst eine schlichte HTTPS-Domain auf dem Standardport nicht zu deiner Maschine auf.

Three honest ways to handle it:Drei ehrliche Wege, damit umzugehen:

• Get a dedicated IPv4. Then 80 and 443 are yours and both compose files above work unchanged. On our plans that is available on request by e-mail, not as a self-service add-on.Eine dedizierte IPv4 holen. Dann gehören 80 und 443 dir, und beide Compose-Dateien oben funktionieren unverändert. Bei unseren Plänen ist das auf Anfrage per E-Mail verfügbar, nicht als Self-Service-Zusatz.
• Use the forwarded port you have. https://status.example.com:41022 works, but not with the Caddy config above unchanged: automatic HTTPS needs port 80 or 443 reachable to complete the ACME challenge, and a forwarded high port gives it neither. Either get 443 forwarded specifically alongside it, or switch Caddy to a DNS-01 challenge (tls { dns <provider> <api-token> }, with the matching DNS plugin) so certificate issuance stops depending on any inbound port at all. Skip that and Caddy never gets a certificate, and the URL itself stays an ugly one nobody types from memory besides.Den weitergeleiteten Port nutzen, den du hast. https://status.example.com:41022 funktioniert, aber nicht mit der Caddy-Konfiguration oben unverändert: Automatisches HTTPS braucht Port 80 oder 443 erreichbar, um die ACME-Challenge abzuschließen, und ein weitergeleiteter hoher Port liefert keinen von beiden. Entweder lässt du dir zusätzlich gezielt 443 weiterleiten, oder du stellst Caddy auf eine DNS-01-Challenge um (tls { dns <provider> <api-token> }, mit dem passenden DNS-Plugin), sodass die Zertifikatsausstellung überhaupt nicht mehr von einem eingehenden Port abhängt. Lässt du das weg, bekommt Caddy nie ein Zertifikat, und die URL selbst bleibt eine hässliche, die sich außerdem niemand merkt.
• Skip public exposure. If the dashboard is only for you, put it behind a WireGuard tunnel or leave it on the SSH-tunnel workflow from setup and never open it to the internet at all — push monitors then only work for jobs running on machines that can also reach the tunnel.Auf öffentliche Erreichbarkeit verzichten. Ist das Dashboard nur für dich, leg es hinter einen WireGuard-Tunnel oder belasse es beim SSH-Tunnel-Workflow aus dem Setup und öffne es nie zum Internet hin — Push-Monitore funktionieren dann nur noch für Jobs, die auf Maschinen laufen, die den Tunnel ebenfalls erreichen.

Worth reading first if you have not sorted this out yet: NAT IPv4 vs a dedicated IP and NAT IPv4, ports and forwarding.Lesenswert vorab, falls du das noch nicht geklärt hast: NAT IPv4 im Vergleich zu einer dedizierten IP und NAT IPv4, Ports und Weiterleitung.

A clean machine firstZuerst eine saubere Maschine

Deploy the VPS, create a non-root user with your SSH key on it, disable password login, and default the firewall to deny before Docker touches the internet — connect to your VPS over SSH and secure your VPS are our own walkthroughs for that part. Point an A record at the box and let it propagate before you ask Caddy for a certificate.Setze den VPS auf, leg einen Non-Root-Nutzer mit deinem SSH-Key darauf an, deaktiviere den Passwort-Login, und stelle die Firewall auf Standard-Deny, bevor Docker das Internet berührt — Verbindung zu deinem VPS per SSH und deinen VPS absichern sind unsere eigenen Anleitungen für diesen Teil. Richte einen A-Eintrag auf die Maschine ein und lass ihn sich verbreiten, bevor du Caddy um ein Zertifikat bittest.

NotificationsBenachrichtigungen

Notifications live under Settings → Notifications and apply per-monitor, not globally, so a noisy endpoint can page differently from a quiet one. Three that cover most setups:Benachrichtigungen liegen unter Einstellungen → Benachrichtigungen und gelten pro Monitor, nicht global, sodass ein lauter Endpunkt anders alarmieren kann als ein ruhiger. Drei, die die meisten Setups abdecken:

• Telegram — create a bot with @BotFather, paste the bot token in, then send the bot a message and use the Auto Get button next to Chat ID rather than hunting for it by hand.Telegram — erstelle einen Bot mit @BotFather, füge das Bot-Token ein, schick dem Bot dann eine Nachricht und nutze den Auto Get-Button neben der Chat-ID, statt sie von Hand zu suchen.
• E-mail (SMTP) — host, port, username, password, and whether it needs TLS. A provider that requires an app-specific password (rather than your normal login) will fail silently until you generate one.E-Mail (SMTP) — Host, Port, Benutzername, Passwort und ob TLS nötig ist. Ein Anbieter, der ein App-spezifisches Passwort verlangt (statt deines normalen Logins), scheitert stillschweigend, bis du eines erzeugst.
• Webhook — a plain JSON POST to any URL you give it, which is the escape hatch: point it at your own relay, at ntfy, at a Slack incoming webhook, or at anything else that takes a POST.Webhook — ein schlichter JSON-POST an jede URL, die du angibst; das ist die Fluchttür: richte ihn auf dein eigenes Relay, auf ntfy, auf einen eingehenden Slack-Webhook oder auf alles andere, das einen POST entgegennimmt.

Every provider has a Test button in its settings panel. Use it before you trust the monitor — a notification that silently fails to send is worse than no notification, because it looks configured.Jeder Anbieter hat einen Test-Button in seinem Einstellungsbereich. Nutze ihn, bevor du dem Monitor vertraust — eine Benachrichtigung, die stillschweigend nicht verschickt wird, ist schlimmer als keine, weil sie konfiguriert aussieht.

Status pagesStatusseiten

Uptime Kuma's status pages are a separate, public-facing view: pick monitors, group them under headings, and it publishes at /status/<slug> on the same domain, no login required to view it. Viewers see up/down and an uptime percentage per monitor; you can add incidents by hand when something is actually broken and want to say so in your own words rather than let a wall of red bars speak for you. The admin dashboard stays behind your login the whole time — the status page is a deliberately separate, read-only surface, and you can run more than one of them off the same instance for different audiences.Die Statusseiten von Uptime Kuma sind eine separate, öffentlich sichtbare Ansicht: Wähle Monitore aus, gruppiere sie unter Überschriften, und die Seite wird unter /status/<slug> auf derselben Domain veröffentlicht, ohne Login zum Ansehen. Besucher sehen Up/Down und eine Uptime-Prozentzahl pro Monitor; du kannst von Hand Incidents hinzufügen, wenn tatsächlich etwas kaputt ist und du das in eigenen Worten sagen willst, statt eine Wand roter Balken für sich sprechen zu lassen. Das Admin-Dashboard bleibt die ganze Zeit hinter deinem Login — die Statusseite ist bewusst eine separate, nur lesbare Oberfläche, und du kannst mehr als eine davon von derselben Instanz aus für unterschiedliche Zielgruppen betreiben.

Backups and updatesBackups und Updates

Everything lives in the uptime-kuma volume: an SQLite database plus any uploaded images. Because it is SQLite, copying the file while the container is writing to it risks a corrupt backup, so take it from inside the running container instead:Alles liegt im uptime-kuma-Volume: eine SQLite-Datenbank plus alle hochgeladenen Bilder. Weil es SQLite ist, riskiert das Kopieren der Datei, während der Container hineinschreibt, ein beschädigtes Backup — nimm es deshalb stattdessen aus dem laufenden Container heraus:

docker compose exec uptime-kuma sqlite3 /app/data/kuma.db ".backup /app/data/kuma-backup.db"
docker compose cp uptime-kuma:/app/data/kuma-backup.db ./kuma-backup.db

Use docker compose cp, not plain docker cp, for the second line. Compose v2 names containers <project>-<service>-<index>, and the project name defaults to your working directory's name, not to uptime-kuma — so a raw docker cp uptime-kuma-uptime-kuma-1:... only works if your directory happens to be called that. docker compose cp resolves the service name the same way exec does, regardless of what the project ended up being called.Nutze für die zweite Zeile docker compose cp, nicht schlichtes docker cp. Compose v2 benennt Container <project>-<service>-<index>, und der Projektname ist standardmäßig der Name deines Arbeitsverzeichnisses, nicht uptime-kuma — ein rohes docker cp uptime-kuma-uptime-kuma-1:... funktioniert also nur, wenn dein Verzeichnis zufällig so heißt. docker compose cp löst den Servicenamen genauso auf wie exec, egal wie das Projekt am Ende genannt wurde.

Copy that file off the server — a backup on the same disk as the thing it backs up is not a backup. back up your VPS covers what we actually do and do not provide by default.Kopiere diese Datei vom Server herunter — ein Backup auf derselben Platte wie das, was es sichert, ist kein Backup. Backup deines VPS beschreibt, was wir standardmäßig tatsächlich bereitstellen und was nicht.

Updating is the usual two lines:Updaten sind die üblichen zwei Zeilen:

docker compose pull
docker compose up -d

Uptime Kuma runs its own database migration on startup, and there is no supported way to move a migrated database back to an older version, so take the backup above before you pull, not after something looks wrong.Uptime Kuma führt beim Start seine eigene Datenbankmigration aus, und es gibt keinen unterstützten Weg, eine migrierte Datenbank zurück auf eine ältere Version zu bringen — nimm das Backup oben also vor dem Pull, nicht erst, nachdem etwas komisch aussieht.

On overnight.hostBei overnight.host

Full disclosure: this is what we sell. If you want the dashboard without the sysadmin, we run Uptime Kuma as a managed container with its own hostname and certificate — you get the app and a URL, not a root shell.Zur vollen Transparenz: Das ist, was wir verkaufen. Willst du das Dashboard ohne die Systemadministration, betreiben wir Uptime Kuma als gemanagten Container mit eigenem Hostnamen und Zertifikat — du bekommst die App und eine URL, keine Root-Shell.

One-click apps — EUR 4 to EUR 12 a month, hosted in Germany (EU). Eight apps: n8n, Uptime Kuma, Vaultwarden, Gitea, Nextcloud, Ghost, Managed WordPress, Private AI Chat. Each customer gets an isolated Docker network and volume, plus a hostname under apps.overnight.host on a real wildcard certificate. Memory and CPU are capped per plan by the container runtime.One-Click-Apps — 4 bis 12 EUR im Monat, gehostet in Deutschland (EU). Acht Apps: n8n, Uptime Kuma, Vaultwarden, Gitea, Nextcloud, Ghost, Managed WordPress, Private AI Chat. Jeder Kunde bekommt ein isoliertes Docker-Netzwerk und -Volume sowie einen Hostnamen unter apps.overnight.host mit einem echten Wildcard-Zertifikat. Arbeitsspeicher und CPU sind je Plan durch die Container-Runtime gedeckelt.

You order in the shop, pay by card (Stripe) or SEPA bank transfer, and your login details are e-mailed to you once the service is set up. Support is e-mail, run by one person, with no guaranteed response time. All prices are final totals under the German small-business rule (§19 UStG); no VAT is added or shown.Du bestellst im Shop, zahlst per Karte (Stripe) oder SEPA-Überweisung, und deine Zugangsdaten werden dir per E-Mail zugeschickt, sobald der Dienst eingerichtet ist. Support läuft per E-Mail, von einer einzelnen Person betrieben, ohne garantierte Reaktionszeit. Alle Preise sind Endpreise. Gemäß § 19 UStG wird keine Umsatzsteuer ausgewiesen.

Order one-click-uptime-kuma → · One-click apps overviewOne-Click-Uptime-Kuma bestellen → · Übersicht One-Click-Apps

Written by the person who runs overnight.host: a small, honest hosting company on dedicated bare metal — Linux VPS, game servers, web hosting. Live status at up.overnight.host.Geschrieben von der Person, die overnight.host betreibt: ein kleines, ehrliches Hosting-Unternehmen auf dedizierter Bare-Metal-Hardware — Linux-VPS, Gameserver, Webhosting. Live-Status unter up.overnight.host.