# How to Properly Backup, Move, and Migrate Uptime Kuma (Docker + Direct Install)

A practical no-nonsense guide to safely migrate Uptime Kuma without losing monitors, notifications, or configs

Author: Ruhani Rabin
Canonical: https://rabin.blog/how-to-properly-backup-move-uptime-kuma-docker-or-direct/
Published: 2026-05-07T11:46:00.000Z
Updated: 2026-10-22T08:43:55.000Z

There are two kinds of Uptime Kuma migrations:

1. The one that works.
2. The one where people export JSON, assume life is good, then discover half their setup is missing.

This guide is for the first one.

The **safest and least error-prone** way to migrate Uptime Kuma is:

> Move the ENTIRE data directory.

Not screenshots.\
Not copy-paste.\
Not “I exported a backup JSON so I should be fine.”

The actual source of truth is the database and app data.

***

## What Actually Needs to Be Backed Up

Uptime Kuma stores everything in its data directory.

Critical files:

```text
kuma.db
kuma.db-wal
kuma.db-shm
uploads/
```

The **important** one is the **_kuma.db_** - the rest can be ignored.

```text
kuma.db
```

**That is your monitors, notifications, users, settings, status pages, and integrations.**

If you lose that file, congratulations, you now own an empty monitoring dashboard.

***

## Before You Start

### Recommended Approach

1. Stop Uptime Kuma completely
2. Copy the entire data folder
3. Restore the folder on the new system
4. Start Uptime Kuma again

This avoids:

* SQLite corruption
* Partial copies
* Missing WAL data
* Broken monitors
* Silent failures

***

## METHOD 1 — Docker-Based Uptime Kuma Migration

This is the most common setup.

### Step 1 — Find Your Data Directory

```yml
services:
  uptime-kuma:
    image: louislam/uptime-kuma:latest
    container_name: uptime-kuma
    volumes:
      - /opt/uptime-kuma:/app/data
```

In this example:

```text
/opt/uptime-kuma
```

Is your actual data?

### Step 2 — Stop the Container

```bash
docker stop uptime-kuma
```

### Step 3 — Create a Proper Backup

```bash
tar -czvf uptime-kuma-backup.tar.gz -C /opt uptime-kuma
```

### Step 4 — Move Backup to New Server

```bash
scp uptime-kuma-backup.tar.gz user@newserver:/root/
```

### Step 5 — Install Fresh Uptime Kuma on New Server

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

Then stop it again:

```bash
docker stop uptime-kuma
```

### Step 6 — Restore Your Backup

```bash
rm -rf /opt/uptime-kuma/*
tar -xzvf uptime-kuma-backup.tar.gz -C /opt/
```

### Step 7 — Start Uptime Kuma

```bash
docker start uptime-kuma
```

***

## METHOD 2 — Direct Install Migration (Non-Docker)

### Step 1 — Find the Data Directory

```bash
find / -type f -name "kuma.db" 2>/dev/null
```

### Step 2 — Stop Uptime Kuma Properly

#### Check systemd first

```bash
systemctl status uptime-kuma
sudo systemctl stop uptime-kuma
```

#### If using PM2

```bash
pm2 list
pm2 stop uptime-kuma
```

#### If manually started

```bash
ps aux | grep node
kill PID
```

### Step 3 — Backup the Data Folder

```bash
tar -czvf uptime-kuma-direct-backup.tar.gz -C /opt/uptime-kuma data
```

### Step 4 — Move Backup to New Server

```bash
scp uptime-kuma-direct-backup.tar.gz user@newserver:/root/
```

### Step 5 — Install Fresh Uptime Kuma

```bash
git clone https://github.com/louislam/uptime-kuma.git
cd uptime-kuma
npm install
```

### Step 6 — Restore Data

```bash
rm -rf /opt/uptime-kuma/data/*
tar -xzvf uptime-kuma-direct-backup.tar.gz -C /opt/uptime-kuma/
```

### Step 7 — Start Uptime Kuma Again

```bash
sudo systemctl start uptime-kuma
```

***

## The Migration Method People SHOULD Use

If you want the least chance of disaster:

* [Docker](https://rabin.blog/manage-multiple-docker-hosts-with-komodo/)
* Bind-mounted persistent volume
* Nightly tar backup
* rsync to NAS

> This is a **boring** setup.
>
> **Boring** is good.
>
> **Boring** restores at 3AM when **something** dies.

***

## What NOT To Do

> Do NOT rely only on JSON export.

**Inside Settings → Backup**, there is a JSON export.

Treat it as **convenience**, not disaster recovery.

**Note**: Do not use it for full state backup.

***

## Recommended Backup Script

```bash
#!/bin/bash


BACKUP_DIR="/backup/uptime-kuma"
DATE=$(date +%F-%H%M)


mkdir -p "$BACKUP_DIR"


docker stop uptime-kuma


tar -czvf "$BACKUP_DIR/uptime-kuma-$DATE.tar.gz" -C /opt uptime-kuma


docker start uptime-kuma
```

***

## Final Thoughts

People massively overcomplicate monitoring stacks.

Uptime Kuma itself is actually simple.

The important thing is respecting the database.

If you:

* stop the service properly
* move the entire data folder
* restore it cleanly

Then migration is usually painless.

If you skip steps because “***it should probably work***”…

**That is usually where the suffering begins.**

## Related reading

* [Automate Dockerized n8n backups](https://rabin.blog/automated-backups-dockerized-n8n-sqlite-gitlab-github/)
* [Back up Proxmox configuration with Git](https://rabin.blog/proxmox-config-backup-git-version-control-pve-nodes/)