Proactive VPS monitoring: Beszel and Uptime Kuma v2

Why proactive monitoring matters, and why classic tools fall short

What this stack delivers to an agency

• Unified view of all your client servers in a single Beszel interface, without multiplying SSH access.
• Metric alerts (CPU, RAM, disk, network) with configurable thresholds per host.
• HTTP(s), TCP, DNS, and SSL certificate availability checks via Uptime Kuma v2 — every 60 seconds by default.
• Telegram or SMTP notifications live within the first hour, no third-party subscription required.
• Detection of disk saturation or memory leaks before they block an application service.
• Public Uptime Kuma status pages shareable with end clients.
• Total stack consumption under 150 MB of RAM on the monitoring VPS.
• Reproducible deployment via Docker Compose, versionable and redeployable in minutes.

Resource requirements

Full deployment: Beszel hub, agents, Uptime Kuma v2 and alerts

1. 01

   Create the Docker Compose structure on the monitoring VPS

   Connect to the VPS dedicated to monitoring. Create a working directory and the Compose file:

   mkdir -p /opt/monitoring && cd /opt/monitoring

   Create docker-compose.yml with both services:

   services:
     beszel:
       image: henrygd/beszel:latest
       restart: unless-stopped
       volumes:
         - ./beszel_data:/beszel_data
       ports:
         - "8090:8090"
       environment:
         - DATA_DIR=/beszel_data
   
     uptime-kuma:
       image: louislam/uptime-kuma:2
       restart: unless-stopped
       volumes:
         - ./uptime-kuma-data:/app/data
       ports:
         - "3001:3001"
       healthcheck:
         test: ["CMD", "node", "extra/healthcheck"]
         interval: 30s
         timeout: 10s
         retries: 3

   Note the healthcheck block on Uptime Kuma: it is essential to avoid the crash-loop trap (see the Pitfalls section).

2. 02

   Start the stack and create administrator accounts

   Start both containers:

   docker compose up -d

   Check that both containers are in healthy or running state:

   docker compose ps

   Access Beszel at http://<vps-ip>:8090 and create the administrator account on first access. Do the same for Uptime Kuma at http://<vps-ip>:3001. Both interfaces should then be placed behind a reverse proxy with SSL to avoid exposing them over plain HTTP.

3. 03

   Deploy the Beszel agent on each VPS to monitor

   On each client VPS to be monitored, copy the public key generated in the Beszel interface (Settings → SSH Key), then run:

   curl -sL https://raw.githubusercontent.com/henrygd/beszel/main/supplemental/scripts/install-agent.sh | bash -s -- -p 45876 -k "<your-public-key>"

   Alternatively, use Docker on the supervised host:

   services:
     beszel-agent:
       image: henrygd/beszel-agent:latest
       restart: unless-stopped
       network_mode: host
       volumes:
         - /var/run/docker.sock:/var/run/docker.sock:ro
       environment:
         - KEY=<your-public-key>
         - PORT=45876

   In Beszel, add each host from the interface (Systems → Add System) with its IP and agent port. The connection is established from the hub to the agent: the supervised host does not need to expose this port publicly.

4. 04

   Configure metric alerts in Beszel

   In Beszel, open a system's detail page and go to the Alerts tab. Configure thresholds on critical metrics:

   - Disk: alert at 80% and critical at 90% — covers the PostgreSQL scenario from the opening case.
   - RAM: alert if usage exceeds 85% sustained for 5 minutes.
   - CPU: alert if load exceeds 90% for more than 3 minutes.

   Beszel supports Telegram, Discord, Slack, Gotify, Ntfy and generic webhooks. For Telegram, you need a bot token (obtained via @BotFather) and your chat or group ID.

5. 05

   Configure Uptime Kuma v2 monitors and SMTP or Telegram alerts

   In Uptime Kuma, start by configuring a notification channel (Settings → Notifications). Two common options:

   Telegram. Enter the bot token and chat ID. The same bot as for Beszel works — use a single bot for both tools and distinguish them by different channels.

   SMTP. Enter the SMTP server, port (587 with STARTTLS), credentials, and destination address. Use a dedicated account for alert sending.

   Then create monitors for each critical service: HTTP(s) URL for websites, TCP for databases and application ports. For the PostgreSQL case, add a TCP monitor on port 5432 for each VPS hosting an instance — if PostgreSQL stops, the port stops responding and the alert fires within seconds.

6. 06

   Put everything behind a reverse proxy with SSL

   Add an nginx or Caddy service to the Compose to expose Beszel and Uptime Kuma over HTTPS:

     caddy:
       image: caddy:alpine
       restart: unless-stopped
       ports:
         - "80:80"
         - "443:443"
       volumes:
         - ./Caddyfile:/etc/caddy/Caddyfile
         - caddy_data:/data

   With a minimal Caddyfile:

   monitoring.your-domain.com {
       reverse_proxy beszel:8090
   }
   
   status.your-domain.com {
       reverse_proxy uptime-kuma:3001
   }

   Caddy automatically issues and renews Let's Encrypt certificates. Remove the ports sections from beszel and uptime-kuma in the Compose once they are proxied — they should no longer be directly accessible.

7. 07

   Verify the setup and configure data retention

   Test everything by manually stopping a service on a test VPS (docker compose stop <service>) and verifying that the Telegram or SMTP alert arrives within two minutes.

   For Beszel, configure data retention in Settings → Retention: the default is 7 days for high-resolution data and 30 days for hourly aggregates. Adjust based on your disk capacity.

   For Uptime Kuma, retention is configured in Settings → Advanced → Auto Cleanup. Keep at least 90 days to have monthly uptime trends to present to clients.

Pitfalls to know before going to production

Alert coverage by stack configuration

Scroll the table

Troubleshooting common issues

Going further