This guide covers configuration options for Uptime Kuma, including environment variables, database settings, monitoring configuration, notification setup, and operational best practices for production deployments.
Latest Version: v2.1.1 (February 13, 2026)
Configuration Method: Environment variables, UI settings, Docker secrets
| Variable | Description | Default | Required |
|---|---|---|---|
PORT |
Application port | 3001 |
No |
HOSTNAME |
Bind hostname | 0.0.0.0 |
No |
TZ |
Timezone | UTC |
No |
NODE_ENV |
Runtime environment | production |
No |
UPTIME_KUMA_DISABLE_FRAME_SAMEORIGIN |
Clickjacking protection | 1 |
No |
| Variable | Description | Default | Required |
|---|---|---|---|
DATABASE_TYPE |
Database type | sqlite |
For external DB |
DATABASE_HOST |
Database host | - | For MySQL/PostgreSQL |
DATABASE_PORT |
Database port | - | For MySQL/PostgreSQL |
DATABASE_NAME |
Database name | - | For MySQL/PostgreSQL |
DATABASE_USER |
Database username | - | For MySQL/PostgreSQL |
DATABASE_PASSWORD |
Database password | - | For MySQL/PostgreSQL |
DATABASE_SSL |
Enable SSL for DB | false |
No |
DATABASE_SSL_REJECT_UNAUTHORIZED |
Reject unauthorized SSL | true |
No |
| Variable | Description | Example |
|---|---|---|
DATABASE_PASSWORD_FILE |
Path to password secret file | /run/secrets/db_password |
DATABASE_USERNAME_FILE |
Path to username secret file | /run/secrets/db_username |
| Variable | Description | Default | Notes |
|---|---|---|---|
UPTIME_KUMA_ARGS |
Additional CLI arguments | - | Pass to Node.js |
IS_DOCKER |
Docker detection | auto |
Auto-detected |
No configuration required. Data stored in /app/data/kuma.db.
volumes:
- uptime-kuma-data:/app/data
Note: SQLite is suitable for most deployments. Use external databases for high-availability or large-scale deployments.
Prerequisites:
Environment Variables:
environment:
- DATABASE_TYPE=mysql
- DATABASE_HOST=mariadb
- DATABASE_PORT=3306
- DATABASE_NAME=uptime_kuma
- DATABASE_USER=uptime_kuma
- DATABASE_PASSWORD=your-secure-password
- DATABASE_SSL=false
Database Setup:
CREATE DATABASE uptime_kuma
CHARACTER SET utf8mb4
COLLATE utf8mb4_unicode_ci;
CREATE USER 'uptime_kuma'@'%' IDENTIFIED BY 'your-secure-password';
GRANT ALL PRIVILEGES ON uptime_kuma.* TO 'uptime_kuma'@'%';
FLUSH PRIVILEGES;
Prerequisites:
Environment Variables:
environment:
- DATABASE_TYPE=postgres
- DATABASE_HOST=postgres
- DATABASE_PORT=5432
- DATABASE_NAME=uptime_kuma
- DATABASE_USER=uptime_kuma
- DATABASE_PASSWORD=your-secure-password
- DATABASE_SSL=true
- DATABASE_SSL_REJECT_UNAUTHORIZED=true
Database Setup:
CREATE DATABASE uptime_kuma
OWNER uptime_kuma
ENCODING 'UTF8'
LC_COLLATE='en_US.UTF-8'
LC_CTYPE='en_US.UTF-8';
| Type | Description | Use Case |
|---|---|---|
| HTTP(s) | Web endpoint monitoring | Websites, APIs |
| HTTP(s) Keyword | Content verification | Page content checks |
| HTTP(s) JSON Query | JSON API validation | REST API monitoring |
| TCP Port | Port availability | Service ports |
| Ping | ICMP host check | Server availability |
| DNS Record | DNS validation | DNS health |
| Push | Heartbeat monitoring | Cron jobs, backups |
| Docker Container | Container status | Docker health |
| WebSocket | WebSocket endpoint | Real-time services |
| Steam Game Server | Game server status | Game servers |
| Criticality | Interval | Use Case |
|---|---|---|
| Critical | 20-30 seconds | Production APIs, payment systems |
| High | 1-2 minutes | Customer-facing services |
| Normal | 5 minutes | Internal services |
| Low | 15-30 minutes | Non-critical systems |
Note: v2.1.0+ supports intervals as low as 1 second for critical monitoring.
| Setting | Recommended | Description |
|---|---|---|
| Retries | 3 | Attempts before marking down |
| Retry Interval | 60 seconds | Wait between retries |
| Resend Interval | 0 (disabled) | Re-alert interval |
# Example notification routing
notifications:
- name: "Critical Alerts"
type: "telegram"
monitors: ["production-api", "payment-gateway"]
escalation_delay: 0
- name: "Team Notifications"
type: "slack"
monitors: ["all"]
escalation_delay: 300
- name: "Email Reports"
type: "smtp"
monitors: ["all"]
escalation_delay: 900
{
"content": "🚨 {{monitorName}} is {{status}}",
"embeds": [
{
"title": "{{monitorName}}",
"description": "{{message}}",
"color": {{statusColor}},
"fields": [
{
"name": "Response Time",
"value": "{{responseTime}}ms",
"inline": true
},
{
"name": "Time",
"value": "{{timestamp}}",
"inline": true
}
]
}
]
}
# ntfy with custom tags and priority
server: https://ntfy.sh
topic: uptime-kuma-alerts
priority: urgent
tags: warning,rotating_light
title: "Uptime Alert: {{monitorName}}"
message: "{{message}}"
Create separate status pages for different audiences:
| Page | Audience | Monitors |
|---|---|---|
| Public | Customers | Customer-facing services |
| Internal | Team | All internal services |
| Partner | Partners | Shared infrastructure |
| Setting | Recommendation | Description |
|---|---|---|
| Title | “Service Status” | Page title |
| Description | Brief service overview | Page description |
| Theme | Light/Dark | Visual theme |
| Show Tags | Enabled | Display monitor tags |
| Show Certificate Info | Enabled | SSL expiry display |
| Domain Mapping | Custom domain | Map to status.example.com |
# Scheduled maintenance template
maintenance:
title: "Scheduled Database Upgrade"
description: "Database migration with expected 5-minute downtime"
start: "2026-02-20T02:00:00Z"
end: "2026-02-20T03:00:00Z"
affected_monitors:
- "production-database"
- "api-gateway"
notify_subscribers: true
| Setting | Recommendation | Description |
|---|---|---|
| 2FA | Enabled | Two-factor authentication |
| Session Timeout | 24 hours | Admin session duration |
| Password Policy | Strong | Minimum 12 characters |
| Login Rate Limiting | Enabled | Prevent brute force |
Configure via reverse proxy:
add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;
add_header X-Frame-Options "SAMEORIGIN" always;
add_header X-Content-Type-Options "nosniff" always;
add_header X-XSS-Protection "1; mode=block" always;
add_header Referrer-Policy "strict-origin-when-cross-origin" always;
add_header Content-Security-Policy "default-src 'self'; script-src 'self' 'unsafe-inline'; style-src 'self' 'unsafe-inline';" always;
# Docker network isolation
networks:
monitoring-network:
driver: bridge
ipam:
config:
- subnet: 172.28.0.0/16
driver_opts:
com.docker.network.bridge.enable_icc: "false"
| Path | Description | Priority |
|---|---|---|
/app/data/kuma.db |
SQLite database | Critical |
/app/data/config.json |
Application config | Critical |
/app/data/notification-*.db |
Notification history | High |
#!/bin/bash
set -e
BACKUP_DIR="/backup/uptime-kuma"
DATE=$(date +%Y%m%d_%H%M%S)
DATA_DIR="/opt/uptime-kuma/data"
# Create backup
tar czf ${BACKUP_DIR}/uptime-kuma-${DATE}.tar.gz -C ${DATA_DIR} .
# Verify
tar tzf ${BACKUP_DIR}/uptime-kuma-${DATE}.tar.gz > /dev/null
# Cleanup (keep 30 days)
find ${BACKUP_DIR} -name "uptime-kuma-*.tar.gz" -mtime +30 -delete
echo "Backup completed: uptime-kuma-${DATE}.tar.gz"
| Frequency | Retention | Method |
|---|---|---|
| Daily | 7 days | Automated script |
| Weekly | 4 weeks | Off-site copy |
| Monthly | 12 months | Archive storage |
# Meta-monitoring configuration
monitors:
- name: "Uptime Kuma Health"
type: http
url: "http://localhost:3001"
interval: 60
retries: 2
- name: "Uptime Kuma Database"
type: tcp
hostname: "localhost"
port: 3001
interval: 60
SQLite:
-- Enable WAL mode for better concurrency
PRAGMA journal_mode = WAL;
PRAGMA synchronous = NORMAL;
PRAGMA cache_size = 10000;
MySQL/MariaDB:
-- Optimize for Uptime Kuma workload
SET GLOBAL innodb_buffer_pool_size = 256M;
SET GLOBAL innodb_log_file_size = 64M;
SET GLOBAL query_cache_size = 16M;
PostgreSQL:
-- Tune for monitoring workload
ALTER SYSTEM SET shared_buffers = '256MB';
ALTER SYSTEM SET effective_cache_size = '768MB';
ALTER SYSTEM SET work_mem = '16MB';
| Setting | Value | Description |
|---|---|---|
| Max History Days | 90 | Data retention period |
| Ping Chart Points | 50 | Chart data points |
| Concurrent Checks | 10 | Parallel monitor checks |
Database Connection Failed:
# Test connectivity
docker exec uptime-kuma nc -zv database-host 3306
# Check environment
docker exec uptime-kuma env | grep DATABASE
Notifications Not Sending:
# Check notification logs
docker logs uptime-kuma 2>&1 | grep -i notification
# Test webhook connectivity
curl -X POST https://webhook-url -d '{"test": true}'
High Memory Usage:
Slow Dashboard Loading:
Any questions?
Feel free to contact us. Find all contact information on our contact page.