Uptime Kuma Docker Guide: Self-Hosted Monitoring, Alerts & Status Pages

Uptime Kuma is a self-hosted monitoring tool for checking whether websites and services are reachable, responsive and available.

It can be useful when you want:

• HTTP/HTTPS uptime checks.
• TCP and other service checks.
• Notifications when a monitor changes state.
• Private monitoring dashboards.
• Public status pages.
• Control over your own monitoring data.

But self-hosted monitoring has one important limitation: if the monitoring server fails at the same time as the service it monitors, you may lose the alert too.

Last verified: September 26, 2026. Uptime Kuma release tags, monitor types, notification providers and proxy behavior can change; verify the current project documentation before major upgrades.

---

1. What Uptime Kuma Can Monitor

Uptime Kuma supports multiple monitor types depending on the current release and configuration.

Common practical use cases include:

• HTTP/HTTPS websites and APIs.
• TCP ports and reachable services.
• DNS checks.
• Ping/ICMP where the deployment permissions allow it.
• Keyword/content checks on HTTP responses.
• Certificate-expiry checks.
• Docker/container-related monitoring where configured.
• Public status pages for customers or internal teams.

Monitor availability and simple response behavior with Uptime Kuma, but use separate telemetry for host CPU, RAM, disk, database internals, application traces and deep performance diagnostics.

---

2. Where Should You Host Uptime Kuma?

Choose an environment that is separate enough from the services you want to monitor.

If you host Uptime Kuma on the same VPS as your production WordPress site, a full VPS outage can take down:

• The website.
• The monitoring dashboard.
• The alerting process.

For meaningful external detection, a separate host/provider/location is usually better than placing the monitor inside the exact failure domain it is supposed to detect.

If you do use a separate VPS, the goal is monitoring independence—not high compute capacity. Choose enough storage and memory for your monitor history and alerting needs, then keep the host patched, backed up and independently reachable.

---

3. Docker Is a Practical Deployment Method

Docker keeps the application and its runtime isolated from the base operating system.

A simple deployment can use a named volume so persistent data survives container replacement.

docker run -d \
  --restart=always \
  -p 127.0.0.1:3001:3001 \
  -v uptime-kuma:/app/data \
  --name uptime-kuma \
  louislam/uptime-kuma:2

Use the current official image/tag guidance for your deployment rather than copying an old version from a stale tutorial.

The project also publishes 2-slim and rootless v2 variants. Rootless images can reduce container privileges, but Uptime Kuma's own documentation warns that some features may not work as expected and does not recommend rootless images as the upgrade path from v1 to v2. Use them only after testing the features your deployment needs.

The examples in this guide bind port 3001 to 127.0.0.1 when a reverse proxy runs on the same host. If you intentionally need direct remote access during initial setup, choose an explicit network exposure and firewall policy rather than publishing the port accidentally.

---

4. Prefer Docker Compose for Maintainable Deployments

services:
  uptime-kuma:
    image: louislam/uptime-kuma:2
    container_name: uptime-kuma
    restart: unless-stopped
    ports:
      - "127.0.0.1:3001:3001"
    volumes:
      - uptime-kuma:/app/data

volumes:
  uptime-kuma:

This makes the service configuration easier to document and reproduce.

Before and after starting the stack, validate the Compose model and inspect the actual container state:

docker compose config -q
docker compose up -d
docker compose ps
docker compose logs --tail=100 uptime-kuma

docker compose config -q catches invalid Compose syntax/model errors before deployment. A running container is still not proof that reverse proxying, monitors and notifications work, so continue with the application-level checks later in this guide.

Storage warning: Uptime Kuma's SQLite data requires filesystem support for POSIX file locking. The official installation documentation warns about file-locking problems commonly encountered with NFS. Keep /app/data on a local directory or compatible volume unless you have verified the storage behavior.

Do not treat a Docker named volume as a backup. It survives container replacement, but host/storage failure can still remove it. Back up /app/data to independent storage and test restoration on another instance.

---

5. Bind to localhost When Using a Reverse Proxy

If Uptime Kuma should only be reachable through Nginx, Apache, Caddy or another reverse proxy, avoid exposing port 3001 to the whole internet.

Example:

ports:
  - "127.0.0.1:3001:3001"

This keeps direct container access local while the reverse proxy handles public traffic.

---

6. Use a Subdomain, Not a Subdirectory

Current Uptime Kuma reverse-proxy documentation says normal subdirectory deployment is not supported.

Prefer:

status.example.com

rather than:

example.com/uptimekuma

---

7. Configure DNS for the Monitoring Subdomain

Create the DNS record needed for the hostname you will use, for example:

status.example.com → monitoring server

For A/AAAA/CNAME, TTL and DNS troubleshooting, use our DNS Configuration Best Practices Guide.

---

8. Reverse Proxy With Nginx

Uptime Kuma uses WebSockets, so the reverse proxy must pass the correct upgrade headers.

server {
    listen 443 ssl http2;
    server_name status.example.com;

    location / {
        proxy_pass http://127.0.0.1:3001/;
        proxy_http_version 1.1;

        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

Add your actual TLS certificate configuration or use an automated certificate workflow supported by your server.

Before reloading Nginx, validate the configuration with nginx -t. After reload, verify the dashboard's real-time updates still work; a page that loads but has broken WebSocket proxying is not a complete reverse-proxy test.

---

9. Use HTTPS for Public Access

If the dashboard or status pages are available over the public internet, use HTTPS.

HTTPS protects credentials and session traffic in transit.

Do not expose an administrative monitoring dashboard over plain HTTP on an untrusted network.

---

10. Trusted Proxy Headers

Current Uptime Kuma documentation includes a Trust Proxy setting for deployments fully behind a reverse proxy.

Enable it only when:

• All public access really passes through the trusted proxy.
• Direct access to the backend is blocked appropriately.

This allows forwarded client-address headers to be interpreted correctly.

---

11. First Login and Admin Security

After deployment:

• Create the administrator account.
• Use a strong unique password.
• Enable two-factor authentication where appropriate and store recovery material safely.
• Do not share the admin account.
• Restrict direct port access.
• Patch the host operating system.

For the host, SSH, firewall and Docker exposure controls around the monitoring server, use the Linux VPS Security Hardening Guide.

---

12. Create an HTTP/HTTPS Monitor

For a public website, monitor the URL visitors actually use.

For example:

https://www.example.com/

Use an interval appropriate to how quickly you need to detect outages.

---

13. Monitor a Health Endpoint Where Appropriate

A homepage check answers:

Can this URL return a response?

A dedicated health endpoint can answer something more specific if your application supports it.

For example, it might verify that:

• The application process is running.
• The database is reachable.
• A critical dependency is available.

Do not expose sensitive internal details in public health responses.

---

14. Uptime Is Not the Same as Performance

A service can be technically “up” while responding very slowly.

That means you should separately monitor:

• Availability.
• Response time.
• Application errors.
• Resource health.

Do not present uptime monitoring as a substitute for performance diagnostics.

For slow-response diagnosis, see the TTFB & Server Response Time Guide. If the reverse proxy returns gateway errors, use the Nginx 502 & 504 Troubleshooting Guide. For ongoing release-regression governance, use the Web Performance Budgets & Regression Monitoring Guide.

---

15. Design Monitors Around What You Need to Prove

Availability monitoring is a signal, not a complete observability stack. Combine it with application logs, workflow-specific alerts and host telemetry where the failure mode requires deeper evidence.

---

16. Use Push Monitors for Jobs That Must Report Success

Not every important process exposes a URL that Uptime Kuma can poll. For scheduled jobs, backup jobs, cron tasks or automation workflows, a Push monitor can reverse the model: the job sends a heartbeat to Uptime Kuma, and Kuma alerts when the expected heartbeat does not arrive.

The current API documentation exposes a push endpoint in the form:

https://status.example.com/api/push/<push-token>?status=up&msg=OK

Treat the push token as a secret. Possession of the token permits heartbeat updates for that monitor. Do not publish it in screenshots, public repositories, client-side JavaScript or documentation.

Choose the expected heartbeat interval with enough margin for legitimate job variation. A heartbeat monitor can prove that the job reported success on schedule; it does not automatically prove every internal business step completed correctly unless your job only sends the heartbeat after those checks succeed.

---

17. Notification Channels

Current Uptime Kuma documentation supports a broad range of notification services and also integrates with Apprise for additional providers.

Common categories include:

• Email.
• Chat/messaging services.
• Push services.
• Webhooks.

Choose a channel that still works when the monitored service fails. If the notification webhook, mail server or chat relay is hosted on the same infrastructure as the monitored service, that alert path can disappear during the same outage.

If monitoring events need to trigger broader self-hosted workflows, see How to Self-Host n8n with Docker.

---

18. Always Test Notifications

A configured notification is not the same as a working notification.

After setup:

1. Use the built-in test where available.
2. Trigger a controlled failure.
3. Confirm the alert arrives.
4. Confirm recovery notifications arrive.

---

19. Avoid Alert Fatigue

Too many noisy monitors can make real incidents easier to miss.

Prioritize alerts for:

• Customer-facing downtime.
• Critical APIs.
• Certificate failures.
• Important infrastructure.

Use sensible retry/failure thresholds so one transient packet loss event does not create unnecessary noise.

---

20. Public Status Pages

Uptime Kuma supports public status pages.

They can be useful for publishing:

• Current service status.
• Service groups.
• Recent availability history.
• Planned incident communication.

A public status page is not the admin dashboard. Publish only the service names, incident details and operational information you are comfortable exposing publicly.

The project documents an iframe-based workaround for custom/subdirectory presentation, but it requires disabling frame-same-origin protection and explicitly warns that this can introduce clickjacking risk. Prefer a normal hostname/subdomain status-page deployment unless you have a specific reason to accept that trade-off.

---

21. Status Pages Cache Results

Current official status-page documentation says public status pages cache results for 5 minutes and refresh the page every 5 minutes. That is appropriate for public communication, but it is intentionally less responsive than the live dashboard.

Do not treat the public status page as a real-time operations console.

---

22. Monitor From More Than One Location When It Matters

A single monitor can confuse:

• A local network issue.
• A DNS issue.
• A regional routing problem.
• A real global outage.

For critical services, consider independent monitoring from another provider or location. Compare failures before declaring a global outage: one failing probe can represent the probe's own network, DNS resolver, region or provider rather than the monitored service.

---

23. Monitoring WordPress Specifically

For WordPress, useful checks can include:

• Homepage.
• Key landing page.
• Login endpoint availability.
• WooCommerce checkout or synthetic transaction health only where the test is explicitly designed to avoid real orders, charges, emails or inventory changes.
• Critical API endpoint.

If monitoring reveals repeated WordPress-specific security or login problems, use our WordPress Security Hardening Guide.

---

24. Monitor Certificate Expiry

Certificate-expiry monitoring can prevent avoidable HTTPS outages.

Still keep certificate renewal automated where possible.

Monitoring should verify automation—not replace it.

---

25. Be Careful With Docker/Container Monitoring

Uptime Kuma can be configured for Docker-related monitoring, but do not mount /var/run/docker.sock into the monitoring container merely because a tutorial suggests it.

Docker daemon/socket access is highly privileged. Docker's security documentation treats daemon access as a sensitive administrative boundary because a client able to control Docker can create privileged containers, mount host filesystems and effectively gain host-level control. If container monitoring requires Docker access, understand and restrict that trust boundary explicitly.

If your goal is only to check whether a containerized application is reachable, an HTTPS, TCP or application-health monitor is often sufficient and avoids granting the monitoring application Docker-daemon control.

---

26. Back Up Uptime Kuma Data

Your configuration and historical data live in the persistent data directory/volume.

Back up the data used at:

/app/data

Backups are particularly important before:

• Major upgrades.
• Host migration.
• Storage changes.
• Rebuilding the server.

For a named Docker volume, one practical backup pattern is to stop or quiesce the application, archive the volume contents, and store the archive somewhere independent of the monitoring host.

A restore test should verify more than “the archive extracted.” Start a disposable Uptime Kuma instance against the restored data, confirm monitors and notification settings exist, verify the dashboard loads, and run a controlled test notification/failure. A backup that has never been restored is not yet proven recovery evidence.

---

27. Upgrade Workflow

For Docker deployments, the current official process is to pull the updated image and recreate the container using the same persistent volume. The project's update page was revised September 16, 2026 and still recommends the :2 tag for v2. The currently published release verified for this article is 2.5.5.

For higher-change-control environments, you can pin a tested release such as 2.5.5 instead of automatically following the moving :2 tag, then deliberately advance that pin after reviewing release notes, making a backup and testing restoration. The current upstream security page recommends staying on supported/current v2 tags; do not leave a production pin abandoned indefinitely.

docker pull louislam/uptime-kuma:2
docker stop uptime-kuma
docker rm uptime-kuma

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

For Docker Compose:

docker compose config -q
docker compose pull
docker compose up -d --force-recreate
docker compose ps
docker compose logs --tail=100 uptime-kuma

After upgrade, verify container health/logs, dashboard access, WebSocket updates, several representative monitors, notification tests, status-page rendering and free disk space before deleting the previous backup.

Before upgrading, back up /app/data and review release/migration notes—especially when crossing major versions.

---

28. Example Docker Compose With Local-Only Binding

services:
  uptime-kuma:
    image: louislam/uptime-kuma:2
    container_name: uptime-kuma
    restart: unless-stopped
    ports:
      - "127.0.0.1:3001:3001"
    volumes:
      - uptime-kuma:/app/data

volumes:
  uptime-kuma:

This is a better starting point when Nginx/Caddy/Apache is the only intended public entry point.

---

29. Firewall Rules

If the reverse proxy and Uptime Kuma are on the same host:

• Expose only required public ports such as 80/443.
• Keep the Uptime Kuma backend port local where practical.
• Restrict SSH.
• Keep the OS firewall enabled.

---

30. Monitor the Monitoring Stack

A self-hosted monitor is still an application that can fail. Add external checks for the monitoring endpoint itself when the alerting path matters.

• Check the public Uptime Kuma hostname from another provider/location.
• Monitor free disk space on the host separately; historical monitoring data and logs can grow over time.
• Watch container restart loops and Docker daemon health.
• Keep notification channels independent from the monitored application where possible.
• Test recovery after upgrading or restoring /app/data.

---

31. Common Uptime Kuma Mistakes

• Hosting the monitor on the same server as every monitored service.
• Exposing port 3001 publicly without a reason.
• Using a subdirectory reverse proxy even though the application expects a hostname/root path.
• Forgetting WebSocket proxy headers.
• Using HTTP for the public admin dashboard.
• Not testing notifications.
• Having no backup of /app/data.
• Assuming uptime means the application is healthy.
• Publishing the admin dashboard instead of a status page.
• Mounting the Docker socket without understanding the host-level privilege it grants.
• Treating uptime alerts as intrusion detection or application tracing.
• Assuming a Docker named volume is automatically an off-host backup.
• Publishing Push monitor tokens in documentation, screenshots or repositories.
• Following latest and expecting v2 even though the project deprecates that tag for v2 use.
• Interrupting a v1→v2 database migration.
• Publishing sensitive internal dependency details on a public status page.
• Treating a running Docker container as proof that monitoring works; validate the dashboard, representative monitors, WebSocket updates and alert delivery.
• Testing WooCommerce or other state-changing workflows in a way that creates real transactions.

---

32. Uptime Kuma vs Managed Monitoring vs Infrastructure Health Checks

---

33. Deployment Checklist

• Choose an independent-enough monitoring host.
• Install Docker.
• Create persistent storage.
• Bind backend locally when using a reverse proxy.
• Create monitoring subdomain.
• Configure HTTPS reverse proxy.
• Pass WebSocket headers.
• Create admin account and enable 2FA where appropriate.
• Create monitors that match the failure mode you need to detect.
• Configure notifications and keep at least one alert path independent of the monitored failure domain where practical.
• Test failure/recovery alerts.
• Create public status page only if needed.
• Back up /app/data to an independent location and perform a test restore.
• Document and test the upgrade/restore procedure.
• Record the deployed image tag/version and review release notes before future upgrades.

---

34. Final Uptime Kuma Decision Framework

Need basic self-hosted monitoring?
   ↓
Deploy Uptime Kuma

Need independent outage detection?
   ↓
Use a separate host/location

Need public access?
   ↓
Subdomain + HTTPS reverse proxy + WebSockets

Need alerts?
   ↓
Configure + test notification channel

Need customer-facing status?
   ↓
Publish status page, not admin dashboard

Before upgrade?
   ↓
Record version + back up /app/data + test restore

Migrating v1 → v2?
   ↓
Read migration notes + watch logs + never interrupt migration

Uptime Kuma is most valuable when it is simple, independent enough to detect real outages, and backed by notifications you have actually tested.

---

Frequently Asked Questions

Which Docker tag should I use for Uptime Kuma v2?

The current Uptime Kuma Docker documentation recommends louislam/uptime-kuma:2 for the latest v2 release. The latest tag is deprecated for v2 use and still points to v1.

Can I store Uptime Kuma data on NFS?

Be careful. The official installation documentation warns that Uptime Kuma's SQLite data requires POSIX file locking and specifically calls out potential NFS locking problems. Use local or otherwise compatible storage unless you have verified locking behavior.

Is Uptime Kuma free?

Uptime Kuma is an open-source self-hosted monitoring project. You still pay for any server, storage, domain or notification infrastructure you use.

Should I host Uptime Kuma on the same VPS as my website?

You can, but it reduces monitoring independence. If the whole VPS fails, the website and monitor can fail together.

Can Uptime Kuma run behind Nginx?

Yes. The official documentation provides reverse-proxy examples and notes that WebSocket upgrade headers are required.

Can I run Uptime Kuma under /uptimekuma?

The current official reverse-proxy documentation says normal subdirectory deployment is not supported. Use a domain or subdomain instead.

Should port 3001 be public?

Not necessarily. If a reverse proxy is on the same host, binding the backend to localhost reduces unnecessary direct exposure.

Does Uptime Kuma replace server monitoring?

No. It is useful for service availability and response checks, but CPU, RAM, disk, database and application metrics require additional monitoring.

Can Uptime Kuma send alerts?

Yes. It supports many native notification services and can use Apprise for additional integrations.

Should I back up Uptime Kuma?

Yes. Back up the persistent data directory/volume, especially before upgrades or migration.

What is the current Uptime Kuma v2 release?

This article was verified against Uptime Kuma 2.5.5, released September 16, 2026, on September 26, 2026. The recommended moving Docker tag remains louislam/uptime-kuma:2; check official releases before future upgrades.

Should I use the Uptime Kuma latest Docker tag?

Not for v2. The project currently marks latest as deprecated for v2 use and says it still points to v1. Use the recommended :2 tag or deliberately pin a tested 2.x.x release.

Can I use a rootless Uptime Kuma image?

Rootless v2 images are available, but the project warns that some features may not work as expected and does not recommend rootless images as the direct v1→v2 upgrade path. Test your required monitor types and integrations before adopting one.

What is a Push monitor?

A Push monitor waits for a job or workflow to send a heartbeat to a tokenized endpoint. It is useful for cron jobs, backups and automations that must report success. Treat the push token as a secret because it authorizes updates to that monitor.

Why shouldn't I interrupt a v1 to v2 migration?

The v2 migration transforms historical heartbeat data and can take time on larger databases. The official migration guide says not to interrupt it; if interruption occurs, restore from backup before retrying.