This guide covers multiple deployment methods for Uptime Kuma on Linux servers. Choose the approach that best fits your infrastructure and operational requirements.
Latest Stable Version: v2.1.1 (February 13, 2026)
Recommended Method: Docker Compose for production deployments
| Method | Best For | Complexity | Maintenance |
|---|---|---|---|
| Docker Compose | Production, easy updates | Low | Automatic |
| Docker (single command) | Quick testing, development | Low | Manual |
| Ansible | Multi-server, automation | Medium | Automated |
| Native (Node.js) | Custom environments, debugging | High | Manual |
# Update package index
sudo apt-get update
# Install prerequisites
sudo apt-get install -y ca-certificates curl gnupg
# Add Docker's official GPG key
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg
# Add Docker repository
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
# Install Docker
sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
# Verify installation
docker --version
docker compose version
# Install Docker
sudo dnf install -y docker docker-compose-plugin
# Enable and start Docker
sudo systemctl enable --now docker
# Verify installation
docker --version
docker compose version
# Create directory for Uptime Kuma
sudo mkdir -p /opt/uptime-kuma
cd /opt/uptime-kuma
Create docker-compose.yml:
services:
uptime-kuma:
image: louislam/uptime-kuma:2
container_name: uptime-kuma
restart: unless-stopped
ports:
- "3001:3001"
volumes:
- uptime-kuma-data:/app/data
networks:
- uptime-kuma-network
environment:
- TZ=Europe/Berlin
- UPTIME_KUMA_DISABLE_FRAME_SAMEORIGIN=0
healthcheck:
test: ["CMD", "curl", "-f", "http://localhost:3001"]
interval: 30s
timeout: 10s
retries: 3
start_period: 40s
volumes:
uptime-kuma-data:
driver: local
networks:
uptime-kuma-network:
driver: bridge
# Start the container
docker compose up -d
# Check status
docker compose ps
# View logs
docker compose logs -f
Open your browser and navigate to:
http://your-server-ip:3001
Create your admin account on first launch.
For quick testing or minimal setups:
docker run -d --restart=always \
-p 3001:3001 \
-v uptime-kuma:/app/data \
--name uptime-kuma \
-e TZ=Europe/Berlin \
louislam/uptime-kuma:2
Verify:
docker ps | grep uptime-kuma
docker logs uptime-kuma
# Install Node.js 20.x
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs
# Verify installation
node --version # Should be v20.4+
npm --version
# Install NVM
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
# Load NVM
source ~/.bashrc
# Install Node.js 20.x
nvm install 20
nvm use 20
nvm alias default 20
# Verify
node --version
# Install Git
sudo apt-get install -y git # Debian/Ubuntu
sudo dnf install -y git # RHEL/Fedora
# Clone Uptime Kuma repository
git clone https://github.com/louislam/uptime-kuma.git /opt/uptime-kuma
cd /opt/uptime-kuma
# Install Node.js dependencies
npm ci --production
# Install PM2 globally
sudo npm install -g pm2
# Setup PM2 to start on boot
pm2 startup
# Run the command output by pm2 startup
# Start with PM2
pm2 start server.js --name uptime-kuma
# Save PM2 configuration
pm2 save
# Monitor application
pm2 logs uptime-kuma
pm2 monit
Create /etc/systemd/system/uptime-kuma.service:
[Unit]
Description=Uptime Kuma Monitoring
After=network.target
[Service]
Type=forking
User=www-data
Group=www-data
WorkingDirectory=/opt/uptime-kuma
ExecStart=/usr/bin/pm2 start server.js --name uptime-kuma
ExecStop=/usr/bin/pm2 stop uptime-kuma
Restart=on-failure
Environment=NODE_ENV=production
[Install]
WantedBy=multi-user.target
# Enable and start service
sudo systemctl daemon-reload
sudo systemctl enable --now uptime-kuma
sudo systemctl status uptime-kuma
For automated multi-server deployment, see Uptime Kuma Ansible Setup.
Quick example:
- name: Deploy Uptime Kuma
hosts: monitoring-servers
become: true
vars:
app_root: /opt/uptime-kuma
app_port: 3001
docker_image: louislam/uptime-kuma:2
tasks:
- name: Install Docker
ansible.builtin.include_role:
name: geerlingguy.docker
- name: Create application directory
file:
path: "{{ app_root }}"
state: directory
mode: "0755"
- name: Deploy Docker Compose
copy:
dest: "{{ app_root }}/docker-compose.yml"
content: |
services:
uptime-kuma:
image: {{ docker_image }}
restart: unless-stopped
ports:
- "{{ app_port }}:3001"
volumes:
- uptime-kuma-data:/app/data
- name: Start Uptime Kuma
command: docker compose up -d
args:
chdir: "{{ app_root }}"
# Backup Docker volume
docker run --rm \
-v uptime-kuma:/source \
-v $(pwd):/backup \
alpine tar czf /backup/uptime-kuma-backup-$(date +%Y%m%d).tar.gz -C /source .
# Navigate to installation directory
cd /opt/uptime-kuma
# Pull latest image
docker compose pull
# Restart with new image
docker compose up -d
# Verify version in UI
cd /opt/uptime-kuma
# Pull latest changes
git pull
# Install updated dependencies
npm ci --production
# Restart application
pm2 restart uptime-kuma
Important: Always backup your data before upgrading. v2.0.0+ requires database migration from v1.x.
# Check logs
docker logs uptime-kuma
# Check port conflicts
sudo netstat -tlnp | grep 3001
# Verify volume permissions
ls -la /var/lib/docker/volumes/uptime-kuma-data/
# Backup first
cp -r /app/data /app/data.backup
# Check database file permissions
ls -la /app/data/
# Review migration logs
docker logs uptime-kuma 2>&1 | grep -i migration
⚠️ NFS is not supported. Use local storage only:
# Wrong (NFS)
-v /mnt/nfs/uptime-kuma:/app/data
# Correct (local)
-v uptime-kuma:/app/data
Any questions?
Feel free to contact us. Find all contact information on our contact page.