![\"Mascote](\"\/wp-content\/uploads\/2026\/09\/uptime-kuma-linux-monitoramento-v1.webp\")
<\/p>\n<\/p>\n
When a site, API, or server stops responding, finding out from the user is too late. The Uptime Kuma<\/strong> is a monitoring tool self-hosted<\/em> with a web interface: it performs checks at regular intervals, records history, and sends alerts when a service changes state. In this guide, we'll install it with Docker Compose, publish it with Nginx, and configure the first monitors securely.<\/p>\n Kuma makes sense when you need to quickly know if something the user consumes remains accessible: a website, an API, a TCP port, a DNS resolution, or a job completion. It brings together checking, history, state change, notification, and a status page in a simple interface. How it works self-hosted<\/em>, URLs, notification credentials, and history stay on your infrastructure, instead of in a third-party monitoring account.<\/p>\n This doesn't make it a universal replacement. Uptime is not complete observability: an endpoint can respond and still be slow, out of disk space, or have a backlog. The best choice is to use it as the availability and quick alert layer, alongside metrics and logs when the operation needs deep diagnosis.<\/p>\n Uptime Kuma is a Node.js<\/strong>, application, predominantly in JavaScript. The web interface uses Vue 3<\/strong> and Vite<\/strong>; the repository also includes TypeScript in the development stack. That's why running without Docker requires Node.js 20.4 or higher, but the container path avoids installing Node and project dependencies directly on the host.<\/p>\n The project is a lightweight alternative for monitoring service availability without outsourcing the dashboard. It supports HTTP(S), TCP, keyword search, and JSON query monitors over HTTP(S), WebSocket, ping, DNS, push<\/em>, Steam servers and Docker containers. It also offers public status pages, latency graphs, certificate information, proxy support, two-factor authentication, and notification integrations.<\/p>\n It doesn't replace detailed metrics: for CPU, memory, disk, and server time series, combine it with Prometheus and Node Exporter<\/a>. Kuma answers another question: \u201cis this endpoint accessible right now and has someone been notified?\u201d.<\/p>\n The commands below are for Ubuntu 22.04 LTS, 24.04 LTS or later supported by Docker. They use the official Docker repository, which delivers the Engine and the modern plugin On a new host, install the prerequisites, Nginx, and the repository key:<\/p>\n Add the APT source. The command automatically reads the codename and architecture of the current installation:<\/p>\n Install Docker Engine, Compose, and enable the services:<\/p>\n The first test command downloads a small image and exits; it confirms the daemon is working. Keep You need a Linux host with Docker Engine and the Docker Compose plugin. The example uses a dedicated directory in The Uptime Kuma database lives in the data directory. Do not place this directory on NFS: the project does not support it because file locks required by SQLite are not suitable for this scenario. Include Create the directory and the file Use this configuration. The tag Start and confirm the status:<\/p>\n On first launch, create the administrative account. Store this password in a password manager and enable 2FA in settings. To monitor the startup, use Choose a subdomain, for example First, issue a TLS certificate for the subdomain using the method adopted on your server. Do not open the interface or create the administrative account before HTTPS is active<\/strong>: HTTP login exposes the credential. Then, create the server block<\/em> final. Adjust the certificate paths to your environment; WebSocket support is important for the interface to update in real time:<\/p>\n Test before reloading:<\/p>\n Validate In the dashboard, click on Add New Monitor<\/strong>. Start with a few checks that represent a real journey:<\/p>\n Avoid aggressive intervals by default. A monitor with too many false positives is quickly ignored. Set the timeout, retries, and interval according to the service's criticality and capacity.<\/p>\n Open Settings \u2192 Notifications<\/strong>, set up your chosen channel, and use the test button. Uptime Kuma integrates with SMTP, Telegram, Discord, Slack, Gotify, Pushover, and many other services. Then assign the notification to each monitor \u2014 creating the channel alone does not enable alerts.<\/p>\n Start with a channel that someone actually watches. For critical services, use more than one destination and document who responds to each type of alert.<\/p>\n Under Status Pages<\/strong>, create a page with the monitors that can be shown publicly. It is separate from the admin dashboard: publish only information that is appropriate to disclose. A status page helps reduce support requests during an outage, but should not list internal services, private addresses, or infrastructure details.<\/p>\n Back up the data directory before updating. During a maintenance window, the basic workflow is:<\/p>\n Check the official release notes<\/a> before updating, especially when moving to a new major version. The project also provides specific guidance for migrating from v1 to v2<\/a>.<\/p>\n In short: choose Kuma for its quick-to-use interface and ready-made checks; Gatus for version-controlled configuration; Prometheus\/Blackbox for metrics and alerts as code; and Zabbix when you need to monitor the entire infrastructure.<\/p>\n Uptime Kuma is excellent as a simple availability and alerting layer: a dashboard for your endpoints, jobs, and status pages. For in-depth host monitoring, complement your strategy with Prometheus<\/a>; to explore traditional alternatives, read the histories of Nagios<\/a> and Zabbix<\/a>. The official installation instructions, advanced proxy configuration, and source code are available in the Uptime Kuma repository<\/a>.<\/p>","protected":false},"excerpt":{"rendered":" Install Uptime Kuma with Docker Compose, publish it with Nginx and configure alerts, status page and backup with security.<\/p>","protected":false},"author":0,"featured_media":0,"comment_status":"closed","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[21,2,120,3],"tags":[156,126,240,466,203,465,5,464],"class_list":["post-1557","post","type-post","status-publish","format-standard","hentry","category-infra","category-linux","category-servidores","category-ubuntu","tag-docker","tag-monitoramento","tag-nginx","tag-node-js","tag-self-hosted","tag-status-page","tag-ubuntu","tag-uptime-kuma"],"_links":{"self":[{"href":"https:\/\/www.linuxpro.com.br\/en\/wp-json\/wp\/v2\/posts\/1557","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/www.linuxpro.com.br\/en\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/www.linuxpro.com.br\/en\/wp-json\/wp\/v2\/types\/post"}],"replies":[{"embeddable":true,"href":"https:\/\/www.linuxpro.com.br\/en\/wp-json\/wp\/v2\/comments?post=1557"}],"version-history":[{"count":2,"href":"https:\/\/www.linuxpro.com.br\/en\/wp-json\/wp\/v2\/posts\/1557\/revisions"}],"predecessor-version":[{"id":1559,"href":"https:\/\/www.linuxpro.com.br\/en\/wp-json\/wp\/v2\/posts\/1557\/revisions\/1559"}],"wp:attachment":[{"href":"https:\/\/www.linuxpro.com.br\/en\/wp-json\/wp\/v2\/media?parent=1557"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/www.linuxpro.com.br\/en\/wp-json\/wp\/v2\/categories?post=1557"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/www.linuxpro.com.br\/en\/wp-json\/wp\/v2\/tags?post=1557"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}Why use Uptime Kuma<\/h2>\n
What language is it developed in<\/h2>\n
What Uptime Kuma monitors<\/h2>\n
Install Docker, Compose, and Nginx on Ubuntu<\/h2>\n
docker compose<\/code>. On a machine that already runs containers, don't remove or replace packages without reviewing the impact: Docker's documentation lists docker.io<\/code>, docker-compose<\/code>, containerd<\/code> and runc<\/code> among the packages that can conflict with the official installation.<\/p>\nsudo apt update\nsudo apt install -y ca-certificates curl nginx\nsudo install -m 0755 -d \/etc\/apt\/keyrings\nsudo curl -fsSL https:\/\/download.docker.com\/linux\/ubuntu\/gpg \n -o \/etc\/apt\/keyrings\/docker.asc\nsudo chmod a+r \/etc\/apt\/keyrings\/docker.asc<\/code><\/pre>\nsudo tee \/etc\/apt\/sources.list.d\/docker.sources <<EOF\nTypes: deb\nURIs: https:\/\/download.docker.com\/linux\/ubuntu\nSuites: $(. \/etc\/os-release && echo \"${UBUNTU_CODENAME:-$VERSION_CODENAME}\")\nComponents: stable\nArchitectures: $(dpkg --print-architecture)\nSigned-By: \/etc\/apt\/keyrings\/docker.asc\nEOF\n\nsudo apt update<\/code><\/pre>\nsudo apt install -y docker-ce docker-ce-cli containerd.io \n docker-buildx-plugin docker-compose-plugin\nsudo systemctl enable --now docker nginx\nsudo docker run hello-world\ndocker compose version<\/code><\/pre>\nsudo<\/code> in Docker commands or configure post-installation access thoughtfully: belonging to the group docker<\/code> is effectively equivalent to having administrative power over the host. Before exposing container ports, also review the firewall: rules published by Docker can bypass UFW rules.<\/p>\nBefore you begin<\/h2>\n
\/opt<\/code>, a local volume for the data, and the service port limited to 127.0.0.1<\/code>. so the interface is not directly exposed to the internet; Nginx will be the only entry point.<\/p>\n\/opt\/uptime-kuma\/data<\/code> in the server backup.<\/p>\nDeploy Uptime Kuma with Docker Compose<\/h2>\n
compose.yaml<\/code>:<\/p>\nsudo install -d -m 0755 \/opt\/uptime-kuma\nsudoedit \/opt\/uptime-kuma\/compose.yaml<\/code><\/pre>\n:2<\/code> follows the latest version of the 2 line and is the recommended one by the project. To freeze a specific release, use a tag 2.x.x<\/code>. Do not use :latest<\/code> as a shortcut for version 2: that name is deprecated and still points to the 1 line.<\/p>\nservices:\n uptime-kuma:\n image: louislam\/uptime-kuma:2\n container_name: uptime-kuma\n restart: unless-stopped\n volumes:\n - .\/data:\/app\/data\n ports:\n - \"127.0.0.1:3001:3001\"<\/code><\/pre>\ncd \/opt\/uptime-kuma\nsudo docker compose up -d\nsudo docker compose ps\ncurl -I http:\/\/127.0.0.1:3001<\/code><\/pre>\nsudo docker compose logs -f<\/code>.<\/p>\nPublish with Nginx and HTTPS<\/h2>\n
status-admin.exemplo.com<\/code>, and point the DNS to the server. Uptime Kuma should be at the root of this subdomain; it does not support installation in a subdirectory like exemplo.com\/kuma\/<\/code>.<\/p>\nserver {\n listen 80;\n server_name status-admin.exemplo.com;\n return 301 https:\/\/$host$request_uri;\n}\n\nserver {\n listen 443 ssl;\n server_name status-admin.exemplo.com;\n\n ssl_certificate \/etc\/letsencrypt\/live\/status-admin.exemplo.com\/fullchain.pem;\n ssl_certificate_key \/etc\/letsencrypt\/live\/status-admin.exemplo.com\/privkey.pem;\n\n location \/ {\n proxy_pass http:\/\/127.0.0.1:3001;\n proxy_http_version 1.1;\n proxy_set_header Upgrade $http_upgrade;\n proxy_set_header Connection \"upgrade\";\n proxy_set_header Host $host;\n proxy_set_header X-Real-IP $remote_addr;\n proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;\n proxy_set_header X-Forwarded-Proto $scheme;\n }\n}<\/code><\/pre>\nsudo nginx -t\nsudo systemctl reload nginx<\/code><\/pre>\nhttps:\/\/status-admin.exemplo.com<\/code> and only then perform the first login. When enabling the option Trust Proxy<\/em> on Kuma, do this only if all requests come through a reverse proxy you control; otherwise, forwarded headers can spoof the origin IP. For an Nginx review on Debian or Ubuntu, see our guide on Nginx and PHP versions<\/a>.<\/p>\nCreate monitors that actually notify you of something useful<\/h2>\n
\n
ok<\/code>.<\/li>\nConfigure notifications before failure<\/h2>\n
Public status page, without exposing the admin panel<\/h2>\n
Updates and backups<\/h2>\n
cd \/opt\/uptime-kuma\nsudo docker compose pull\nsudo docker compose up -d --force-recreate\nsudo docker compose logs --tail=100<\/code><\/pre>\nSecurity considerations<\/h2>\n
\n
3001<\/code> directly; keep it bound to 127.0.0.1<\/code> behind HTTPS and authentication.<\/li>\ndata<\/code>: it may contain URLs, notification tokens, and information about your infrastructure.<\/li>\nAlternatives: which to use in each scenario<\/h2>\n
\n
Where Kuma fits in your operations<\/h2>\n