Uptime Kuma Deployment & Usage Guide

1. Prerequisites

For Docker Deployment

• Docker Engine (>= 20.10) and Docker Compose (>= 1.29) installed
• Sufficient disk space for data persistence (monitoring history, screenshots, etc.)
• Network access to pull the louislam/uptime-kuma Docker image

For Native (Non-Docker) Deployment

• Node.js (>= 20.4) with npm
• Git
• PM2 (process manager for running in background)
• Supported OS: Linux (Debian, Ubuntu, Fedora, ArchLinux), Windows 10/Server 2012 R2+
• Unsupported: FreeBSD, OpenBSD, NetBSD, Replit, Heroku

General

• A domain name (optional, for reverse proxy/HTTPS)
• Open port 3001 (default) or custom port if changed

2. Installation

Method A: Docker Compose (Recommended)

# Create a directory for Uptime Kuma
mkdir uptime-kuma && cd uptime-kuma

# Download the official compose.yaml
curl -o compose.yaml https://raw.githubusercontent.com/louislam/uptime-kuma/master/compose.yaml

# Start the container
docker compose up -d

Method B: Docker Run

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

To restrict access to localhost only:

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

Method C: Native (Non-Docker)

# Clone the repository
git clone https://github.com/louislam/uptime-kuma.git
cd uptime-kuma

# Install dependencies and build frontend
npm run setup

# Option 1: Quick test (runs in foreground)
node server/server.js

# Option 2: Production (run with PM2)
npm install pm2 -g && pm2 install pm2-logrotate
pm2 start server/server.js --name uptime-kuma

# Optional: Save PM2 configuration for auto-start on boot
pm2 startup && pm2 save

3. Configuration

Docker Environment Variables

You can customize the Docker container using environment variables in compose.yaml:

services:
  uptime-kuma:
    image: louislam/uptime-kuma:2
    environment:
      - UPTIME_KUMA_PORT=3001          # Default: 3001
      - UPTIME_KUMA_BASE_URL=https://status.example.com  # For reverse proxy
      - NODE_ENV=production
    volumes:
      - ./data:/app/data
    ports:
      - "3001:3001"

Data Directory

• Docker: Mount a volume to /app/data (as shown above). This stores:
  • SQLite database (kuma.db)
  • Uploaded files (notification service credentials, etc.)
  • Screenshots (if enabled)
  • Docker TLS certificates (if using Docker monitoring)
• Native: Data is stored in ./data relative to the project directory by default.

Important Notes

• Do NOT use NFS/network file systems for the data volume. Use local storage only.
• For production, always use a reverse proxy (nginx, Traefik, Caddy) for:
  • HTTPS termination
  • Domain-based routing
  • Security headers

4. Build & Run

Development (Local Testing)

# After cloning and running npm run setup, start the dev server:
npm run dev

# This will start Vite dev server with hot-reload. Access at http://localhost:3001

Production (Native)

# Start with PM2 (already covered in Installation)
pm2 start server/server.js --name uptime-kuma

# View logs
pm2 logs uptime-kuma

# Monitor resource usage
pm2 monit

Docker (Production)

The Docker image already runs in production mode. Just use the docker compose up -d command.

5. Deployment

Recommended Platforms

1. Docker on a VPS (DigitalOcean, Linode, AWS EC2, etc.)

   • Use Docker Compose for easy management
   • Set up a reverse proxy (nginx example below)

2. Native on a VPS (if you need direct filesystem access)

   • Use PM2 to keep the process running
   • Configure a systemd service (optional, PM2 handles it)

Reverse Proxy Configuration (nginx example)

server {
    listen 80;
    server_name status.example.com;
    return 301 https://$server_name$request_uri;
}

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

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location / {
        proxy_pass http://localhost: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;
    }
}

Using Cloudflare Tunnels (Alternative to Reverse Proxy)

1. Install cloudflared on your server
2. Create a tunnel in Cloudflare dashboard pointing to localhost:3001
3. Set cloudflared to run as a service

6. Troubleshooting

Common Issues

1. Port Already in Use

• Docker: Change the host port mapping: -p 3002:3001 (host:container)
• Native: Change the port in the app by setting PORT environment variable:

  PORT=3002 node server/server.js
  

2. Permission Denied on Data Directory

• Docker: Ensure the host directory has proper permissions (read/write for the Docker user, usually root inside container but mapped to your user's UID/GID). On Linux:

  sudo chown -R 1000:1000 ./uptime-kuma/data  # UID 1000 is typical for first user
  

• Native: Ensure your user has write access to the data directory.

3. NFS/Network File System Not Supported

• Solution: Move data directory to a local disk. For Docker, use a local volume or bind mount to a local path.

4. Database Errors (SQLite)

• If the database is corrupted, delete ./data/kuma.db (Docker: in the mounted volume) and restart. Warning: This deletes all monitoring history and settings.
• For large deployments, consider switching to MariaDB/MySQL (see wiki for advanced setup).

5. Container Keeps Restarting

• Check logs: docker logs uptime-kuma
• Common causes:
  • Port conflict
  • Permission issues on volume
  • Out of memory (increase Docker memory limit)

6. Notifications Not Sending

• Verify notification service credentials in Uptime Kuma settings.
• Check server outbound connectivity (firewall rules).
• Some services require specific IP whitelisting.

7. WebSocket Connection Failed (in browser)

• Ensure reverse proxy passes Upgrade and Connection headers (see nginx config above).
• If using Cloudflare, disable "Proxy" (orange cloud) for the subdomain or enable "Full" SSL mode.

Getting Help

• Logs:
  • Docker: docker logs uptime-kuma
  • PM2: pm2 logs uptime-kuma
• GitHub Issues: https://github.com/louislam/uptime-kuma/issues
• Wiki: https://github.com/louislam/uptime-kuma/wiki
• Community Discord: Available from the project's GitHub README

Quick Start Verification

After installation, access http://your-server-ip:3001 (or domain if using reverse proxy). You should see the Uptime Kuma setup screen to create an admin account.