--- title: "How to install Uptime Kuma on a VPS and monitor sites and ports | StreetHosting" description: "Install Uptime Kuma with Docker on a VPS, serve it over HTTPS behind Nginx, and monitor sites, APIs and ports with Discord, Telegram and email alerts." url: "https://streethosting.com.br/en/guides/vps/uptime-kuma-vps-monitoring" type: "page" language: "en-US" --- VPS · 8 min · Intermediate Published on Jun 1, 2026 · Updated on Sep 28, 2026 # Uptime Kuma on a VPS: Docker install, HTTPS, monitors and alerts Uptime Kuma checks sites, APIs, ports and scheduled jobs at set intervals and alerts you when something goes down. Here is how to install it with Docker, serve it over HTTPS, pick the right monitor type and turn on alerts. By [Equipe StreetHosting](https://streethosting.com.br/en/autores#equipe-streethosting) · StreetHosting infrastructure and support team [Monitoring and alerts](https://streethosting.com.br/en/guides/topics/monitoring) [Errors and diagnostics](https://streethosting.com.br/en/guides/topics/troubleshooting) [Containers and Docker](https://streethosting.com.br/en/guides/topics/docker) [Network, DNS and domains](https://streethosting.com.br/en/guides/topics/networking) Summarize with: [](https://chat.openai.com/?q=Summarize%20the%20key%20points%20of%20this%20StreetHosting%20guide%3A%20https%3A%2F%2Fstreethosting.com.br%2Fen%2Fguides%2Fvps%2Fuptime-kuma-vps-monitoring.%20Highlight%20the%20step-by-step%20instructions%2C%20the%20prerequisites%20and%20the%20most%20common%20mistakes. "ChatGPT") [](https://claude.ai/new?q=Summarize%20the%20key%20points%20of%20this%20StreetHosting%20guide%3A%20https%3A%2F%2Fstreethosting.com.br%2Fen%2Fguides%2Fvps%2Fuptime-kuma-vps-monitoring.%20Highlight%20the%20step-by-step%20instructions%2C%20the%20prerequisites%20and%20the%20most%20common%20mistakes. "Claude") [](https://www.google.com/search?udm=50&aep=11&q=Summarize%20the%20key%20points%20of%20this%20StreetHosting%20guide%3A%20https%3A%2F%2Fstreethosting.com.br%2Fen%2Fguides%2Fvps%2Fuptime-kuma-vps-monitoring.%20Highlight%20the%20step-by-step%20instructions%2C%20the%20prerequisites%20and%20the%20most%20common%20mistakes. "Google AI Mode") [](https://x.com/i/grok?text=Summarize%20the%20key%20points%20of%20this%20StreetHosting%20guide%3A%20https%3A%2F%2Fstreethosting.com.br%2Fen%2Fguides%2Fvps%2Fuptime-kuma-vps-monitoring.%20Highlight%20the%20step-by-step%20instructions%2C%20the%20prerequisites%20and%20the%20most%20common%20mistakes. "Grok") [](https://www.perplexity.ai/search/new?q=Summarize%20the%20key%20points%20of%20this%20StreetHosting%20guide%3A%20https%3A%2F%2Fstreethosting.com.br%2Fen%2Fguides%2Fvps%2Fuptime-kuma-vps-monitoring.%20Highlight%20the%20step-by-step%20instructions%2C%20the%20prerequisites%20and%20the%20most%20common%20mistakes. "Perplexity") Share: [](https://x.com/intent/tweet?text=How%20to%20install%20Uptime%20Kuma%20on%20a%20VPS%20and%20monitor%20sites%20and%20ports&url=https%3A%2F%2Fstreethosting.com.br%2Fen%2Fguides%2Fvps%2Fuptime-kuma-vps-monitoring "Share on X") [](https://www.facebook.com/sharer/sharer.php?u=https%3A%2F%2Fstreethosting.com.br%2Fen%2Fguides%2Fvps%2Fuptime-kuma-vps-monitoring "Share on Facebook") [](https://www.linkedin.com/sharing/share-offsite/?url=https%3A%2F%2Fstreethosting.com.br%2Fen%2Fguides%2Fvps%2Fuptime-kuma-vps-monitoring "Share on LinkedIn") [](https://wa.me/?text=How%20to%20install%20Uptime%20Kuma%20on%20a%20VPS%20and%20monitor%20sites%20and%20ports%20https%3A%2F%2Fstreethosting.com.br%2Fen%2Fguides%2Fvps%2Fuptime-kuma-vps-monitoring "Share on WhatsApp") For agents: Copy as Markdown [.md](https://streethosting.com.br/en/guides/vps/uptime-kuma-vps-monitoring.md) In this guide 7 sections * [Why monitor, and where to run it](https://streethosting.com.br/en/guides/vps/uptime-kuma-vps-monitoring#por-que-monitorar) * [Install with Docker Compose](https://streethosting.com.br/en/guides/vps/uptime-kuma-vps-monitoring#instalar) * [Domain and HTTPS with Nginx](https://streethosting.com.br/en/guides/vps/uptime-kuma-vps-monitoring#dominio-https) * [Monitor types and setup](https://streethosting.com.br/en/guides/vps/uptime-kuma-vps-monitoring#configuracao-rapida) * [Discord, Telegram and email notifications](https://streethosting.com.br/en/guides/vps/uptime-kuma-vps-monitoring#notificacoes) * [Best practices and maintenance](https://streethosting.com.br/en/guides/vps/uptime-kuma-vps-monitoring#boas-praticas) * [Which VPS to use for Uptime Kuma](https://streethosting.com.br/en/guides/vps/uptime-kuma-vps-monitoring#qual-vps) Quick answer **VPS monitoring with Uptime Kuma** works like this: it checks your services at set intervals and sends alerts when it detects a failure. Install it with Docker Compose, serve the dashboard behind Nginx with HTTPS, and create HTTP, Keyword, TCP, Ping, DNS and Push monitors for each service. Whenever you can, run Uptime Kuma outside the VPS it monitors, because a monitor that goes down with the server never warns you. ## Why monitor, and where to run it[](https://streethosting.com.br/en/guides/vps/uptime-kuma-vps-monitoring#por-que-monitorar) Without monitoring, many outages are only noticed when a customer complains. With automatic alerts, your team reacts sooner and limits the impact. Uptime Kuma is an open-source tool that you host on your own machine: there is no monitor limit and no monthly fee, and the data stays with you. The most important decision comes before the install: where Uptime Kuma will run. On the same VPS it watches, it catches the application that froze, the site that started returning errors and the certificate that expired. But if the whole VPS goes down, loses its network or locks up from running out of memory, the monitor goes down with it and the alert never goes out. The setup that catches both kinds of failure is a small VPS used only for monitoring, watching your production machines from the outside. The full strategy, with internal metrics and alert thresholds, is in [how to monitor a VPS 24/7](https://streethosting.com.br/en/guides/vps/monitor-vps-24-7). ## Install with Docker Compose[](https://streethosting.com.br/en/guides/vps/uptime-kuma-vps-monitoring#instalar) The simplest way to install and update it is with Docker. If your VPS does not have it yet, start with [installing Docker on Ubuntu](https://streethosting.com.br/en/guides/vps/install-docker-ubuntu-vps). Then create a folder for the service and the `compose.yaml` file: `sudo mkdir -p /opt/uptime-kuma && cd /opt/uptime-kuma sudo nano compose.yaml` `services: uptime-kuma: image: louislam/uptime-kuma:2 container_name: uptime-kuma restart: unless-stopped ports: - "127.0.0.1:3001:3001" volumes: - ./data:/app/data` Two details make a difference. The `127.0.0.1:3001:3001` mapping publishes the dashboard on the VPS's localhost only: ports published by Docker bypass the UFW rules, and without that prefix port 3001 would be open to the internet even with the firewall enabled. And the `./data` folder holds the database, the monitors and the history; it is the folder that goes into your backup. `sudo docker compose up -d sudo docker compose logs -f` Whoever opens the dashboard first creates the admin account. Do the initial setup through an SSH tunnel before you publish the domain: `ssh -L 3001:127.0.0.1:3001 usuario@IP_DA_VPS` and then open http://localhost:3001 in your browser. In version 2, the first screen asks which database to use; for a few dozen monitors, SQLite works with no extra service. ## Domain and HTTPS with Nginx[](https://streethosting.com.br/en/guides/vps/uptime-kuma-vps-monitoring#dominio-https) Once the account exists, publish the dashboard on a subdomain such as `kuma.seu-dominio.com.br`. Uptime Kuma updates the screen over WebSocket, so the proxy has to pass the upgrade headers along; without them, the dashboard loads forever. The general Nginx proxy walkthrough is in [configuring Nginx as a reverse proxy](https://streethosting.com.br/en/guides/vps/nginx-reverse-proxy-vps); the specific block looks like this: `# /etc/nginx/sites-available/uptime-kuma server { listen 80; server_name kuma.seu-dominio.com.br; 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; 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; } }` `sudo ln -s /etc/nginx/sites-available/uptime-kuma /etc/nginx/sites-enabled/ sudo nginx -t && sudo systemctl reload nginx sudo certbot --nginx -d kuma.seu-dominio.com.br` Then, under Settings, Reverse Proxy, set Trust Proxy to yes. That way Uptime Kuma records the real IP of whoever connects, not the Nginx 127.0.0.1. While you are there, turn on two-factor authentication under Settings, Security: this dashboard stores the webhooks and tokens for all of your alert channels. ## Monitor types and setup[](https://streethosting.com.br/en/guides/vps/uptime-kuma-vps-monitoring#configuracao-rapida) Each monitor tests one thing only, and choosing the right type is what separates a useful alert from false reassurance. The most common ones: | Type | What it checks | Example use | | ------------------ | ------------------------------------------------------------ | ------------------------------------------------ | | HTTP(s) | Whether the URL responds with a success status | Site, dashboard, API health route | | HTTP(s) Keyword | Whether the response contains an expected word | Page that returns 200 but shows a database error | | HTTP(s) Json Query | The value of a field in a JSON response | API that reports an ok status in the body | | TCP Port | Whether the port accepts connections | SSH, database, game server over TCP | | Ping | Whether the host answers ICMP | Knowing the whole VPS is up | | DNS | Whether the record resolves to the expected value | Catching an accidental change to the A record | | Push | Whether something called the monitor URL within the interval | Backup, cron job, worker with no open port | | Docker Container | Whether the container is running | Services running on the same machine as Kuma | A plain HTTP check says the server answered, not that the application works. A store with its database down can return status 200 with an error page. A Keyword monitor, looking for a word that only appears when everything is right, catches that case. Likewise, ping proves the machine is up, but not that the service responds, and some servers block ICMP. Use ping as a complement, never as your only test. And remember that TCP Port does not test UDP: game servers that use UDP need the game-specific monitor. ### Interval, retries and certificate[](https://streethosting.com.br/en/guides/vps/uptime-kuma-vps-monitoring#intervalos) 1. A 60 second interval covers most services; use 30 seconds only for what is critical. 2. Under Retries, use 2 or 3, with a short retry interval: a single blip wakes nobody up. 3. On HTTP monitors, turn on the certificate expiry notice. The lead time, in days, is set in the notification settings. 4. Test a simulated outage by stopping the service, to validate both the monitor and the notification. Upside Down Mode alerts when the test passes. With a TCP monitor pointed at the database port or at `node_exporter` from another machine, you get a warning if a firewall rule disappears and the port ends up exposed. ## Discord, Telegram and email notifications[](https://streethosting.com.br/en/guides/vps/uptime-kuma-vps-monitoring#notificacoes) Notifications live under Settings, Notifications, with the Setup Notification button. Each channel is registered once and then attached to the monitors that will use it. * **Discord:** in your server, open Server Settings, Integrations, Webhooks, create a webhook in the team channel and paste the URL into the Discord type in Uptime Kuma. * **Telegram:** create a bot by chatting with @BotFather and copy the token. Send any message to the bot (or add the bot to your team group) and use the automatic fetch button to fill in the Chat ID. * **Email:**use your email provider's SMTP server, on port 587 with STARTTLS or 465 with SSL/TLS, with a username, an app password, a sender and a recipient. Check the option to enable it by default so new monitors start with the channel, and the option to apply it to all existing monitors when you are creating your first channel. Click Test before saving: it is the only way to know the alert arrives before you need it. How to organize channels, keep team alerts apart from public ones and cut down on noise is covered in [downtime alerts on Discord or Telegram](https://streethosting.com.br/en/guides/infrastructure/server-downtime-alerts-discord-telegram). For backups and scheduled jobs, the Push monitor flips the logic: the script calls the URL when it finishes successfully, and silence becomes the alert. `# last line of the script, only runs if everything before it succeeded curl -fsS -m 10 "https://kuma.seu-dominio.com.br/api/push/SEU_TOKEN?status=up&msg=OK" > /dev/null` ## Best practices and maintenance[](https://streethosting.com.br/en/guides/vps/uptime-kuma-vps-monitoring#boas-praticas) Give every monitor a clear name. It helps when the team gets an alert at peak hours: "API production: checkout" says far more than "monitor 7". * Monitor both the internal service and the public page. * Separate critical alerts from informational ones. * Log incidents so you can learn from failures. * Review alert contacts every month. * Create a maintenance window before restarting or updating a service. * Include the Uptime Kuma data folder in your backup. Maintenance windows pause alerts for the monitors you choose for a set period, so a planned update does not trigger a notification. Status pages publish the state of your services to customers or players, on your own domain; what to show on them and how to communicate an incident is covered in [creating a status page for incidents](https://streethosting.com.br/en/guides/infrastructure/incident-status-page). To update, just pull the new image and recreate the container. The data stays in the mounted folder and is not lost: `cd /opt/uptime-kuma sudo docker compose pull && sudo docker compose up -d` Before jumping to a new major version, read the release notes and copy the data folder. For a consistent copy with SQLite, stop the container, copy `./data` and start it again, or add the folder to your [automatic backup with restic](https://streethosting.com.br/en/guides/vps/vps-backup-restic-cron). Finally, keep only ports 22, 80 and 443 open in the [UFW firewall](https://streethosting.com.br/en/guides/vps/ufw-firewall-ubuntu-vps): the dashboard already goes through Nginx. ## Which VPS to use for Uptime Kuma[](https://streethosting.com.br/en/guides/vps/uptime-kuma-vps-monitoring#qual-vps) Uptime Kuma is lightweight. With SQLite and a few dozen monitors, it typically sits at a few hundred MB of RAM, and the smallest VPS plan already has room to spare. At StreetHosting, the Xeon VPS starts at R$ 26.00 per month with 2 vCPU, 2 GB of RAM and 20 GB of NVMe, with Anti-DDoS Enterprise, and it is the natural choice for a monitoring-only machine. The Ryzen 9 9950X VPS starts at R$ 40.00 with 1 vCPU, 2 GB of DDR5 and 20 GB of NVMe, if you would rather keep everything on the same line as production. Both are in São Paulo, with root access, activation within 60 seconds and payment by Pix, boleto or card. One honest caveat: a monitoring VPS in the same data center as production catches a machine, application or network failure on the VPS, but not a failure that takes down the whole data center. To cover that case, also keep a test running from another network, even if it is just a second Uptime Kuma instance at home watching the first. Compare the plans on the [VPS page](https://streethosting.com.br/en/vps). In this guide * [Why monitor, and where to run it](https://streethosting.com.br/en/guides/vps/uptime-kuma-vps-monitoring#por-que-monitorar) * [Install with Docker Compose](https://streethosting.com.br/en/guides/vps/uptime-kuma-vps-monitoring#instalar) * [Domain and HTTPS with Nginx](https://streethosting.com.br/en/guides/vps/uptime-kuma-vps-monitoring#dominio-https) * [Monitor types and setup](https://streethosting.com.br/en/guides/vps/uptime-kuma-vps-monitoring#configuracao-rapida) * [Discord, Telegram and email notifications](https://streethosting.com.br/en/guides/vps/uptime-kuma-vps-monitoring#notificacoes) * [Best practices and maintenance](https://streethosting.com.br/en/guides/vps/uptime-kuma-vps-monitoring#boas-praticas) * [Which VPS to use for Uptime Kuma](https://streethosting.com.br/en/guides/vps/uptime-kuma-vps-monitoring#qual-vps) ## Frequently asked questions Does Uptime Kuma replace technical support? No. It tells you when something fails, since when the service has been down and which error showed up, which shortens the diagnosis. Investigating and fixing the problem is still the job of whoever administers the server. Can I monitor more than one service? Yes. A single dashboard can watch sites, APIs, TCP ports, DNS records, containers and scheduled jobs across several VPSs at the same time, each monitor with its own interval and notifications. Is it hard to set up? No. With Docker, the install is a file of a few lines and one command. The parts that need more care are serving the dashboard over HTTPS, creating the admin account before you expose the port, and tuning retries to avoid false alarms. Can I install Uptime Kuma on the same VPS it monitors? You can, but it only sees application failures. If the whole VPS goes down, the monitor goes down with it and no alert is sent. To detect a machine outage, run Uptime Kuma on another VPS or on another network. How do I monitor a backup or a cron job with Uptime Kuma? Use a Push monitor. It generates a URL that your script calls with curl when it finishes successfully. If the call does not arrive within the configured interval, the monitor goes down and the alert fires. Next step See VPS plans Root VPS in Brazil with NVMe and Anti-DDoS. [See VPS plans](https://streethosting.com.br/en/vps) [See Xeon VPS Xeon VPS for steady workloads, automation and long-running projects.](https://streethosting.com.br/en/vps/xeon) ## Related guides [VPS Intermediate How to monitor a VPS 24/7: metrics, alerts and uptime An uptime monitor on its own will not tell you the disk is filling up or that backups stopped three weeks ago. Here is how to combine availability, resources, scheduled jobs and alerts into a routine that works day and night. 10 min Read guide](https://streethosting.com.br/en/guides/vps/monitor-vps-24-7) [Infrastructure Intermediate How to get server downtime alerts on Discord or Telegram The worst way to find out your server is down is a flood of complaints. With external monitoring and Discord or Telegram alerts, you hear about it first and act before it turns into chaos. 3 min Read guide](https://streethosting.com.br/en/guides/infrastructure/server-downtime-alerts-discord-telegram) [VPS Intermediate How to install Docker on Ubuntu 22.04 or 24.04 on a VPS (straight to the point) A stable Docker install on an Ubuntu VPS depends on the right package source and step by step validation. In this guide you set up the official repository, install Engine and Compose, test the daemon and apply basic security measures before deploying applications. 3 min Read guide](https://streethosting.com.br/en/guides/vps/install-docker-ubuntu-vps) [← Back to the Guide Center](https://streethosting.com.br/en/guides)