Install and maintain Uptime Kuma on Ubuntu

Uptime Kuma is cloned to /opt/uptime-kuma, built with Node.js, supervised by PM2 and systemd, and exposed through Nginx with TLS.

Before you start

• Use a clean, supported Ubuntu server with root or sudo access.
• Point app.example.com to the server before requesting a public TLS certificate.
• Replace every value written as CHANGE_ME and store the generated credentials in a password manager.
• Take a snapshot before changing an existing installation.
• A domain and enough storage for monitor history and notification configuration.
• Select a supported Node.js major explicitly; do not substitute an application tag where the NodeSource major is expected.

What the AppStore installation creates

• Node.js and npm
• Uptime Kuma Git checkout at /opt/uptime-kuma
• PM2 runtime plus a systemd unit
• Nginx websocket reverse proxy and TLS

1. Install Node.js and base packages

Use the Node.js major supported by the selected Uptime Kuma release.

sudo apt update
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo bash -
sudo apt install -y nodejs git nginx certbot python3-certbot-nginx ufw fail2ban
sudo npm install -g pm2

2. Clone and build Uptime Kuma

sudo git clone https://github.com/louislam/uptime-kuma.git /opt/uptime-kuma
cd /opt/uptime-kuma
sudo git checkout SELECTED_RELEASE_TAG
sudo npm run setup
sudo npm run build

3. Create the service

Run the server through PM2 with the application bound on its expected local port, and enable PM2/systemd startup.

cd /opt/uptime-kuma
sudo pm2 start server/server.js --name uptime-kuma
sudo pm2 save
sudo pm2 startup systemd
sudo systemctl daemon-reload

4. Configure Nginx and TLS

Proxy HTTP and websocket traffic to 127.0.0.1:3001.

sudo nano /etc/nginx/sites-available/uptime-kuma
sudo ln -s /etc/nginx/sites-available/uptime-kuma /etc/nginx/sites-enabled/uptime-kuma
sudo nginx -t
sudo systemctl reload nginx
sudo certbot --nginx -d status.example.com -m [email protected] --agree-tos --redirect

Important files and data

• Application checkout: /opt/uptime-kuma
• SQLite data and uploads: normally /opt/uptime-kuma/data
• PM2 state: inspect with pm2 status
• Nginx site configuration

Health checks and logs

Run these checks after installation and after each upgrade:

sudo pm2 status
sudo pm2 logs uptime-kuma --lines 100
curl -I http://127.0.0.1:3001
sudo nginx -t

Routine maintenance

Review release notes and take a backup or snapshot before upgrading. Use the following playbook-aligned commands as the starting point:

cd /opt/uptime-kuma
sudo pm2 stop uptime-kuma
# Back up /opt/uptime-kuma/data first.
sudo git fetch --tags
sudo git checkout SELECTED_RELEASE_TAG
sudo npm run setup
sudo npm run build
sudo pm2 restart uptime-kuma
sudo pm2 save

Backup scope

• /opt/uptime-kuma/data, including the SQLite database
• Notification secrets through an encrypted backup
• Nginx and PM2/systemd configuration

A usable backup needs both application files and application data. Test restoration on a separate server; an untested backup is not a recovery plan.

Troubleshooting

• Confirm DNS with dig +short app.example.com before retrying Certbot.
• Test the web-server configuration before reloading it: sudo nginx -t or sudo apache2ctl configtest.
• Check free space with df -h and listening ports with sudo ss -ltnup.
• If a service fails, inspect its systemd journal before changing configuration.
• If the site loads but live status does not update, verify websocket proxy headers in Nginx.
• Do not update directly from master on production; check out a selected release tag.

Security notes

• Do not paste passwords, API keys, repository credentials, private keys, or access tokens into tickets or public logs.
• Expose only the documented public ports. Keep database and application backend ports bound to localhost or a private network.
• Keep SSH access working before enabling UFW, then allow only the ports this guide lists.
• Renewal can be tested safely with sudo certbot renew --dry-run where Certbot manages TLS.