How to Self-Host Uptime Kuma in 2026: Alerts, TLS and Persistent Data

Most Uptime Kuma installation notes end at the first page load. That is too early: the data volume is read-only or container DNS cannot resolve monitored hosts. A useful production test is more demanding — create HTTP and TCP monitors, force one controlled failure and receive the alert and recovery notice through the chosen provider.

Uptime Kuma's role is straightforward: monitoring for existing services with alerts to more than 90 destinations. Its operational boundary includes more than the web process, so the dependency, stored state and public route all have to be named explicitly before real data arrives.

Define success for Uptime Kuma first

A useful Uptime Kuma diagram shows the public route, private port 3001, state boundary and every supporting requirement. Mark which arrows carry credentials and which are ordinary user traffic. The external requirement for Uptime Kuma is outbound access to every monitored endpoint and alert provider. Test outbound DNS, TLS and provider behavior without publishing another inbound service.

Prove the diagram with one real action: create HTTP and TCP monitors, force one controlled failure and receive the alert and recovery notice through the chosen provider. The likely pressure comes from monitor interval, retry count, status-page traffic and the number of outbound probes made at the same second; monitor that path rather than treating all HTTP requests as equal.

Operate Uptime Kuma around its real bottleneck

The first useful operational metric for Uptime Kuma is whether it can create HTTP and TCP monitors, force one controlled failure and receive the alert and recovery notice through the chosen provider. Pair that with saturation signals for monitor interval, retry count, status-page traffic and the number of outbound probes made at the same second. A process-only probe should not call expensive dependencies or restart the container because an upstream is briefly unavailable.

Treat upgrades as data changes because SQLite migrations and notification-provider changes can turn a quick image pull into a stateful application upgrade. Pin versions, rehearse on restored state and keep the previous image available until a rollback remains valid. When the data volume is read-only or container DNS cannot resolve monitored hosts, preserve logs from before the restart; they usually contain the causal message.

Record a known-good Uptime Kuma deployment

For Uptime Kuma, define a known-good transaction before launch: create HTTP and TCP monitors, force one controlled failure and receive the alert and recovery notice through the chosen provider. Put its prerequisites, expected response and cleanup steps in version control without secret values. Pin the image used to establish that reference.

Use the transaction to validate a replacement and an independent restore. The restored service is acceptable only when monitor history, notification credentials and maintenance windows reappear and a test alert still delivers. At the same time, observe monitor interval, retry count, status-page traffic and the number of outbound probes made at the same second and turn the slowest or most constrained part into a service-level alert.

The gate also needs a negative case: temporarily deny the test path used by outbound access to every monitored endpoint and alert provider. Confirm that Uptime Kuma produces an actionable error while preserving data, restore the valid condition and repeat the known-good transaction. Keeping both results prevents a superficial health endpoint from becoming the only production evidence.

Container settings worth reviewing

Use the container as a replaceable runtime, not as the location of truth.

docker run -d \
  --name uptime-kuma \
  --restart unless-stopped \
  -p 127.0.0.1:3001:3001 \
  -v uptime-kuma-data:/app/data \
  -e UPTIME_KUMA_PORT=3001 \
  louislam/uptime-kuma:1

Allow and verify the outbound or client-side path required for outbound access to every monitored endpoint and alert provider. Inspect the container user, writable paths and bound listener before exposing it. Run the complete action — create HTTP and TCP monitors, force one controlled failure and receive the alert and recovery notice through the chosen provider — and save the exact image reference that produced the result.

Restore Uptime Kuma on an empty host

Protect Uptime Kuma's state before optimizing its container. The required set is the SQLite database and uploaded assets in /app/data. Mount /app/data before bootstrap, write harmless sample data and replace the container to prove that path is actually persistent. If multiple stores must agree, document the order in which writes are paused and backups are taken.

Keep copies outside the deployment server and encrypt material containing credentials or private content. Recovery succeeds when monitor history, notification credentials and maintenance windows reappear and a test alert still delivers. The distinction between a persistent mount and an independent copy is covered in persistent storage and snapshots.

Give Uptime Kuma one canonical address

Publish one stable HTTPS origin through the reverse proxy. Send the chosen hostname to container port 3001, forward the original host and HTTPS scheme, and avoid publishing a second direct origin.

Test Uptime Kuma from a clean external client. Separate ingress failure from the known application boundary — the data volume is read-only or container DNS cannot resolve monitored hosts. A certificate, DNS or 502 error belongs to routing; a request that reaches Uptime Kuma and fails later belongs to application state, capacity or its supporting requirement. The custom-domain TLS guide covers the first group.

Security decisions specific to Uptime Kuma

The application-specific security risk is running the first-user setup on a publicly exposed instance. The operational answer is to finish the first-user setup privately, then protect dashboards and status-page administration separately. Finish bootstrap through a restricted route and remove temporary setup access immediately afterward.

UPTIME_KUMA_PORT controls behavior rather than confidentiality; validate its type and value, and store genuine Uptime Kuma credentials separately. Give the Uptime Kuma process only its documented mounts and dependency routes; avoid host root and Docker socket access. Log failed authentication and configuration errors, but redact tokens, connection strings and user content.

A Dockup deployment still needs an Uptime Kuma acceptance test

Routing, certificates, service replacement and attached storage are reasonable automation targets. Dockup handles those for Uptime Kuma and can provision the related managed database or connect to services on a customer's own server.

What it should not invent is the Uptime Kuma trust policy. After deployment, publish one stable HTTPS origin through the reverse proxy, enforce this boundary — finish the first-user setup privately, then protect dashboards and status-page administration separately — and verify the result of this scenario: create HTTP and TCP monitors, force one controlled failure and receive the alert and recovery notice through the chosen provider. The outcome is one-click infrastructure with an application-specific acceptance test.

Frequently asked questions

What does Uptime Kuma need for a production deployment?

Route the Uptime Kuma container on port 3001 through one HTTPS origin. The external delivery requirement is outbound access to every monitored endpoint and alert provider. Do not call Uptime Kuma ready until you can create HTTP and TCP monitors, force one controlled failure and receive the alert and recovery notice through the chosen provider.

Which Uptime Kuma data belongs in a backup?

Persist /app/data and include the SQLite database and uploaded assets in /app/data in the same recovery manifest. A clean Uptime Kuma restore passes only when monitor history, notification credentials and maintenance windows reappear and a test alert still delivers.

Does Uptime Kuma require HTTPS behind a reverse proxy?

Use HTTPS for the public Uptime Kuma origin and keep port 3001 on the internal route. Apply the Uptime Kuma setting correctly: publish one stable HTTPS origin through the reverse proxy. For Uptime Kuma, HTTPS protects credentials or user content in transit and keeps origin-sensitive client behavior consistent.

How should a Uptime Kuma upgrade be tested?

Restore current Uptime Kuma state into an isolated deployment, apply the candidate version and repeat its acceptance transaction. Pay particular attention because SQLite migrations and notification-provider changes can turn a quick image pull into a stateful application upgrade. Keep the previous Uptime Kuma image until its data-migration and rollback boundary are understood.