# How to self-host Uptime Kuma with Docker Compose

> Deploy Uptime Kuma 2 with Docker Compose in 5 minutes: persistent data, first admin account, HTTPS reverse proxy, status pages, backups and safe upgrades.

## Key facts

| Fact | Value |
|---|---|
| App | Uptime Kuma (https://appsgit.com/apps/uptime-kuma) |
| Difficulty | beginner |
| Time | about 10 minutes |
| Requirements | 1 vCPU / 512 MB RAM; Docker + Docker Compose v2; Local disk for the data folder (not NFS); A domain name (optional, for status pages) |
| Last updated | 2026-10-06 |

## What is Uptime Kuma?

Uptime Kuma is a self-hosted monitoring tool that checks websites, APIs, ports, DNS records, Docker containers and more, then alerts you when something goes down. It is open source under the MIT license and has a polished real-time dashboard, public status pages and more than 90 notification channels, including email, Slack, Discord, Telegram and ntfy.

## Requirements

- Any small Linux server: 1 vCPU and 512 MB of RAM handle hundreds of monitors.
- Docker Engine and Docker Compose v2.
- Local storage for the data folder. The project warns that SQLite on NFS or other network file systems can corrupt the database.

## Step 1: Prepare the server

This guide assumes Ubuntu 24.04 with Docker installed. If you need Docker, follow the [Docker Engine install guide](https://docs.docker.com/engine/install/ubuntu/). Ideally, run Uptime Kuma on a different machine or provider than the services it monitors, so it can still alert you when they fail.

```bash
mkdir -p ~/uptime-kuma && cd ~/uptime-kuma
```

## Step 2: Create the Docker Compose file

Uptime Kuma is a single container. Save this as `docker-compose.yml`:

```yaml
services:
  uptime-kuma:
    image: louislam/uptime-kuma:2
    container_name: uptime-kuma
    restart: unless-stopped
    ports:
      - "3001:3001"
    volumes:
      - ./data:/app/data
      # Optional: let Kuma monitor containers on this host (read-only socket).
      # - /var/run/docker.sock:/var/run/docker.sock:ro
    environment:
      TZ: "Europe/London"
```

The `2` tag follows the latest 2.x release, which is what the official Compose file uses. Uptime Kuma needs no secrets in the Compose file. The admin account is created in the browser.

Think twice before mounting the Docker socket. Even read-only, it exposes details about every container on the host, and anyone who takes over the app could use it. Only add it if you need Docker container monitors.

## Step 3: Start and open the app

```bash
docker compose up -d
```

Open `http://YOUR_SERVER_IP:3001`. Uptime Kuma 2 first asks which database to use. Choose **SQLite** unless you plan to run a very large number of monitors. Next, create the admin account with a strong password. Then click "Add New Monitor", pick a type (HTTP(s), TCP port, ping, DNS, keyword and more), set the interval, and attach a notification channel under Settings, Notifications.

## Step 4: Put it behind HTTPS

Uptime Kuma uses WebSockets for its live dashboard, so the proxy must pass them. [Caddy](https://caddyserver.com/docs/) does that automatically:

```caddyfile
status.example.com {
    reverse_proxy 127.0.0.1:3001
}
```

With Nginx Proxy Manager, create a proxy host for port 3001 and enable "Websockets Support". After HTTPS works, change the port mapping to `"127.0.0.1:3001:3001"` so the dashboard is only reachable through the proxy, and set Settings, Reverse Proxy, "Trust Proxy" to Yes so login logs show real client IPs. Then enable two-factor authentication under Settings, Security.

## Backups and upgrades

All state is in the `./data` folder: the SQLite database `kuma.db`, uploaded status-page logos and settings. Stop the container briefly for a consistent copy:

```bash
docker compose stop && tar czf kuma-$(date +%F).tgz data && docker compose start
```

To upgrade within version 2:

```bash
docker compose pull && docker compose up -d
```

If you are coming from Uptime Kuma 1.x, back up `data` first. The first start on version 2 runs a database migration that can take a long time with a big history, and you should not interrupt it.

## Troubleshooting

- **Dashboard loads but stays on "Connecting...":** the reverse proxy is not forwarding WebSockets. Enable WebSocket support on the proxy host.
- **"SQLITE_BUSY" or corruption errors:** the data folder is on NFS or a network share. Move it to local disk.
- **Monitors for `localhost` services fail:** inside the container, `localhost` is the container itself. Use the host's LAN IP or the Docker service name on a shared network.
- **Notifications never arrive:** use the "Test" button on the notification settings page and check `docker compose logs uptime-kuma` for the provider's error.

## Next steps

Create a public status page for your services, add maintenance windows for planned work, set up a second, external check that watches Uptime Kuma itself, and group monitors with tags.

## FAQ

### What port does Uptime Kuma use?

Uptime Kuma listens on port 3001 by default. You open the dashboard at http://SERVER_IP:3001, or on your own domain behind a reverse proxy.

### Is Uptime Kuma free?

Yes. Uptime Kuma is free and open source under the MIT license, with no paid tier or monitor limits.

### What is the default Uptime Kuma login?

There is none. On first launch Uptime Kuma asks you to create the admin username and password, so nobody else can sign in with a default account.

### Should I use SQLite or MariaDB with Uptime Kuma 2?

SQLite is fine for most setups with up to a few hundred monitors. Uptime Kuma 2 also offers embedded or external MariaDB for very large installations with many monitors and long history.

### Uptime Kuma vs UptimeRobot?

Uptime Kuma gives you unlimited monitors, fast intervals and public status pages for free on your own server. UptimeRobot monitors from outside your network, so pair a self-hosted Kuma with an external check if you need to know when the whole server is down.

Prefer not to do it yourself? [appsgit installation help](https://appsgit.com/services/install) installs it on your server for a fixed quote.

---

Canonical page: https://appsgit.com/guides/uptime-kuma
Source: appsgit (https://appsgit.com), the app store for github. Data from the GitHub API, refreshed nightly.
Machine access: JSON API https://appsgit.com/api/v1/apps (OpenAPI: https://appsgit.com/openapi.json), MCP server https://mcp.appsgit.com/mcp, full index https://appsgit.com/llms-full.txt.