Monitor Websites and Servers with Uptime Kuma: Docker Install, HTTPS Proxy and Telegram Alerts

Finding out from a customer that your site has been down for an hour is the worst way to learn about an outage. Uptime Kuma is a free, self-hosted monitoring tool that checks websites, ports, ping and DNS every few seconds to minutes, warns you before SSL certificates expire, publishes a status page and sends alerts to Telegram, email and dozens of other channels. This guide installs it with Docker, puts it behind Nginx with HTTPS and sets up Telegram notifications.

Step 1: Install Docker

Install Docker and Docker Compose as described in our Docker installation guide. Uptime Kuma needs very little: 1 CPU core and 512 MB to 1 GB of RAM are plenty for a few hundred monitors.

Step 2: Start Uptime Kuma

The web interface listens on port 3001. Binding it to 127.0.0.1 keeps it off the public internet until Nginx with HTTPS is in front of it.

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

docker ps --filter name=uptime-kuma
curl -I http://127.0.0.1:3001

The :1 tag follows the long-standing stable release line. Check the project's GitHub releases before moving to a newer major version, because major upgrades can migrate the database.

Step 3: Publish It over HTTPS with Nginx

Point a subdomain such as status.example.com to the monitoring server, issue a certificate (see free SSL with Certbot or acme.sh) and proxy to the container. Uptime Kuma uses WebSockets, so the upgrade headers are required.

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

    ssl_certificate     /etc/letsencrypt/live/status.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/status.example.com/privkey.pem;

    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;
    }
}

nginx -t && systemctl reload nginx

Open https://status.example.com and create the administrator account straight away; the first visitor to the setup page becomes the admin.

Step 4: Add Monitors

• HTTP(s): checks a URL and its status code. Use HTTP(s) - Keyword to also confirm that a word from your page is present, which catches error pages that still return 200.
• TCP Port: checks that a service accepts connections, for example SSH on 22, RDP on 3389 or MySQL on 3306.
• Ping: basic reachability. Some networks drop ICMP, so prefer a TCP check for critical servers.
• DNS: confirms that a record still resolves to the expected value.

A check interval of 60 seconds with 2 or 3 retries is a good balance: real outages are reported within a few minutes and a single lost packet does not wake you up. On HTTP monitors, enable Certificate Expiry Notification to be warned about SSL certificates before they expire.

Step 5: Send Alerts to Telegram

Create a bot and find the chat ID the alerts should go to.

# 1. In Telegram, talk to @BotFather, send /newbot and copy the token
# 2. Send any message to your new bot (or add it to a group and post there)
# 3. Read the chat ID from the bot's updates
curl -s "https://api.telegram.org/bot<YOUR_BOT_TOKEN>/getUpdates" | grep -o '"chat":{"id":-\?[0-9]*'

In Uptime Kuma open Settings → Notifications → Setup Notification, choose Telegram, paste the bot token and chat ID, click Test and enable Default enabled and Apply on all existing monitors. Group chat IDs start with a minus sign.

Step 6: Create a Status Page

Under Status Pages you can publish a public page that shows the state of selected monitors, which is useful for customers and for your own team. You can serve it on its own domain and add maintenance notices during planned work.

Step 7: Back Up and Update

# Back up the data volume (monitors, history, settings)
docker run --rm -v uptime-kuma:/data -v "$PWD":/backup alpine \
  tar czf /backup/uptime-kuma-$(date +%F).tgz -C /data .

# Update to the latest release of the same major version
docker pull louislam/uptime-kuma:1
docker rm -f uptime-kuma
docker run -d --name uptime-kuma --restart=always \
  -p 127.0.0.1:3001:3001 -v uptime-kuma:/app/data louislam/uptime-kuma:1

FAQ

I get alerts for short blips that are not real outages

Increase the retries to 3 and the retry interval to 30 to 60 seconds. A monitor is then marked down only after several consecutive failures.

Ping always fails but the website works

The server or its firewall drops ICMP. Use a TCP Port or HTTP monitor instead.

Can I monitor how my site performs from mainland China?

Uptime Kuma measures from where it runs. To see the China experience, run a second instance on a server with good China routes, such as a Hong Kong CN2 GIA server, or use the network testing tools from several locations.

Still stuck after following these steps? Open a support ticket and the IMIDC 24/7 technical team will help. Include the server IP, OS version, the command you ran and the full error output so we can pinpoint the issue faster.