Install and configure Uptime Kuma for website monitoring with SSL and email alerts

Update system packages

Start by updating your package manager to ensure you get the latest versions of all dependencies.

sudo apt update && sudo apt upgrade -y

sudo dnf update -y

Install Node.js and npm

Uptime Kuma requires Node.js 16 or higher. Install the Node.js runtime and package manager from your distribution's repositories.

sudo apt install -y nodejs npm curl git

sudo dnf install -y nodejs npm curl git

Verify the Node.js installation meets the minimum version requirement:

node --version
npm --version

Create dedicated user for Uptime Kuma

Create a system user to run Uptime Kuma securely. This follows security best practices by avoiding running services as root.

sudo useradd --system --home /opt/uptime-kuma --create-home --shell /bin/bash uptimekuma
sudo usermod -aG uptimekuma uptimekuma

Install Uptime Kuma

Switch to the uptime-kuma user and install Uptime Kuma using npm. This installs the application in the user's home directory.

sudo -u uptimekuma bash
cd /opt/uptime-kuma
npm create uptime-kuma@latest

The installation will create a new directory with the Uptime Kuma application. Navigate to it and install dependencies:

cd uptime-kuma
npm ci --production
exit

Create systemd service

Create a systemd service file to manage Uptime Kuma as a system service. This enables automatic startup and proper process management.

[Unit]
Description=Uptime Kuma
After=network.target
Wants=network.target

[Service]
Type=simple
User=uptimekuma
Group=uptimekuma
WorkingDirectory=/opt/uptime-kuma/uptime-kuma
ExecStart=/usr/bin/node server/server.js
Restart=always
RestartSec=5
Environment=NODE_ENV=production
Environment=UPTIME_KUMA_PORT=3001
Environment=UPTIME_KUMA_HOST=127.0.0.1

Security settings
NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=strict
ProtectHome=true
ReadWritePaths=/opt/uptime-kuma

[Install]
WantedBy=multi-user.target

Set proper file permissions

Set the correct ownership and permissions for the Uptime Kuma directory. The uptimekuma user needs full access to manage the application files and database.

sudo chown -R uptimekuma:uptimekuma /opt/uptime-kuma
sudo chmod -R 755 /opt/uptime-kuma
sudo chmod 644 /etc/systemd/system/uptime-kuma.service

Enable and start Uptime Kuma service

Reload systemd configuration and start the Uptime Kuma service. Enable it to start automatically on boot.

sudo systemctl daemon-reload
sudo systemctl enable --now uptime-kuma
sudo systemctl status uptime-kuma

Install and configure Nginx reverse proxy

Install Nginx to act as a reverse proxy and handle SSL certificates. This provides better security and performance compared to exposing Node.js directly.

sudo apt install -y nginx certbot python3-certbot-nginx

sudo dnf install -y nginx certbot python3-certbot-nginx

Configure Nginx virtual host

Create an Nginx configuration file for your Uptime Kuma domain. Replace example.com with your actual domain name.

server {
    listen 80;
    server_name uptime.example.com;

    access_log /var/log/nginx/uptime-kuma-access.log;
    error_log /var/log/nginx/uptime-kuma-error.log;

    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;
        proxy_cache_bypass $http_upgrade;

        # WebSocket support
        proxy_set_header Sec-WebSocket-Extensions $http_sec_websocket_extensions;
        proxy_set_header Sec-WebSocket-Key $http_sec_websocket_key;
        proxy_set_header Sec-WebSocket-Version $http_sec_websocket_version;
        
        # Timeouts
        proxy_connect_timeout 60s;
        proxy_send_timeout 60s;
        proxy_read_timeout 60s;
    }

    # Security headers
    add_header X-Frame-Options DENY;
    add_header X-Content-Type-Options nosniff;
    add_header X-XSS-Protection "1; mode=block";
}

Enable the site and test the Nginx configuration:

sudo ln -s /etc/nginx/sites-available/uptime-kuma /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

Obtain SSL certificate

Use Certbot to obtain a free SSL certificate from Let's Encrypt. This automatically configures Nginx with SSL settings and redirects HTTP to HTTPS.

sudo certbot --nginx -d uptime.example.com

Follow the prompts to enter your email address and agree to the terms of service. Certbot will automatically configure SSL and set up automatic renewal.

Configure firewall rules

Open the necessary ports in your firewall to allow web traffic. This allows users to access your Uptime Kuma installation securely.

sudo ufw allow 'Nginx Full'
sudo ufw allow OpenSSH
sudo ufw enable
sudo ufw status

sudo firewall-cmd --permanent --add-service=http
sudo firewall-cmd --permanent --add-service=https
sudo firewall-cmd --permanent --add-service=ssh
sudo firewall-cmd --reload
sudo firewall-cmd --list-all

Access web interface and initial setup

Open your web browser and navigate to your Uptime Kuma domain. You'll be presented with the initial setup wizard to create your administrator account.

https://uptime.example.com

Create an administrator account with a strong password. This will be your main account for managing all monitoring configurations.

Configure email notifications

Navigate to Settings > Notifications in the Uptime Kuma interface. Click "Add New notification" and select "Email (SMTP)" as the notification type.

Enter your SMTP configuration details:

• SMTP Host: Your mail server hostname (e.g., smtp.gmail.com)
• SMTP Port: 587 for TLS or 465 for SSL
• Security: Choose TLS or SSL based on your provider
• Username: Your email username
• Password: Your email password or app-specific password
• From Email: The sender email address
• To Email: Where to send alerts

Test the notification to ensure email delivery works correctly before proceeding to monitor setup.

Add website monitors

Click "Add New Monitor" to create your first website monitor. Configure the following settings:

• Monitor Type: HTTP(s) for websites
• Friendly Name: Descriptive name for your monitor
• URL: The website URL to monitor
• Heartbeat Interval: How often to check (recommended: 60 seconds)
• Max Retries: Number of retry attempts (recommended: 3)
• Max Redirects: Maximum allowed redirects (recommended: 10)
• Accepted Status Codes: HTTP codes considered successful (default: 200-299)

Assign the email notification you configured earlier to this monitor. Enable "Advanced" settings to configure custom headers, authentication, or SSL certificate monitoring.

Configure SSL certificate monitoring

For SSL certificate monitoring, enable the "Ignore TLS/SSL error" option initially, then configure specific SSL monitoring:

• Set "Certificate Expiry" notification to warn before certificates expire
• Configure certificate expiry threshold (recommended: 7 days)
• Enable certificate domain verification

This ensures you receive alerts before SSL certificates expire, preventing service disruptions.

Create backup script

Create a backup script to regularly save your Uptime Kuma configuration and database. This protects against data loss and enables easy migration.

#!/bin/bash

Uptime Kuma backup script
BACKUP_DIR="/opt/uptime-kuma/backups"
DATE=$(date +"%Y%m%d_%H%M%S")
BACKUP_FILE="uptime-kuma-backup_${DATE}.tar.gz"

Create backup directory
mkdir -p "$BACKUP_DIR"

Stop Uptime Kuma service
sudo systemctl stop uptime-kuma

Create backup
tar -czf "${BACKUP_DIR}/${BACKUP_FILE}" -C /opt/uptime-kuma uptime-kuma/data

Start Uptime Kuma service
sudo systemctl start uptime-kuma

Remove backups older than 30 days
find "$BACKUP_DIR" -name "uptime-kuma-backup_*.tar.gz" -mtime +30 -delete

echo "Backup completed: ${BACKUP_DIR}/${BACKUP_FILE}"

Make the backup script executable and set proper ownership:

sudo chown uptimekuma:uptimekuma /opt/uptime-kuma/backup.sh
sudo chmod 755 /opt/uptime-kuma/backup.sh

Schedule automated backups

Create a systemd timer to run backups automatically. This provides more reliable scheduling than traditional cron jobs.

[Unit]
Description=Uptime Kuma Backup
Requires=uptime-kuma.service

[Service]
Type=oneshot
User=uptimekuma
Group=uptimekuma
ExecStart=/opt/uptime-kuma/backup.sh

[Unit]
Description=Run Uptime Kuma backup daily
Requires=uptime-kuma-backup.service

[Timer]
OnCalendar=daily
Persistent=true

[Install]
WantedBy=timers.target

Enable and start the backup timer:

sudo systemctl daemon-reload
sudo systemctl enable --now uptime-kuma-backup.timer
sudo systemctl list-timers | grep uptime-kuma