Upgrading Uptime Kuma from version 1 to 2 with Docker, without losing anything

How I went from Uptime Kuma 1.23 to 2.x: the backup you can't skip, the right tag, how to roll back, and the same with Portainer running outside compose.

IvánPublished on Updated on October 10, 20264 minLeer en español

Uptime Kuma 2 brings quite a few improvements (including support for other databases and a pile of fixes), but it’s a major version: the database structure changes. So you can’t just bump a number and hope.

Here’s how I did it on the Raspberry Pi. At the end I explain how I upgraded Portainer, which has its own quirk because it isn’t in compose.

1. Check which version you have

First, write down where you’re starting from. You’ll need it if you have to roll back:

docker inspect uptime-kuma --format '{{.Config.Image}}'
docker exec uptime-kuma node -e "console.log(require('./package.json').version)"

The first gives you the tag you launched it with (for example louislam/uptime-kuma:1). The second, the exact version running. I was on 1.23. The version also shows at the bottom of the web UI, under Settings → About.

2. Back up before anything else

Kuma keeps everything (monitors, history, notifications) in a data folder. For the backup, stop the container first, so there are no half-finished writes:

docker compose stop uptime-kuma
tar czf ~/backup/uptime-kuma-before-v2.tar.gz -C ~/services uptime-kuma

Check the backup can be read (a tar with errors won’t save you):

tar tzf ~/backup/uptime-kuma-before-v2.tar.gz | head

The SQLite WAL trap

Kuma uses SQLite in WAL mode. In that mode, recent changes aren’t in kuma.db but in kuma.db-wal until they’re checkpointed. If you ever copy the database “hot” to inspect it, copy all three files together:

kuma.db   kuma.db-wal   kuma.db-shm

If you copy only kuma.db, you’ll be missing the latest changes and think something got lost. With the container stopped, as above, there’s no problem: you copy the whole folder.

3. Change the image

In docker-compose.yml:

  uptime-kuma:
    image: louislam/uptime-kuma:2

I use the 2 tag, not latest. That way I get version 2 updates, but when a 3 comes out it won’t be installed behind my back.

docker compose pull uptime-kuma
docker compose up -d uptime-kuma
docker logs -f uptime-kuma

The first start takes longer than usual: it’s migrating the database. Don’t interrupt it. The logs show the migration progress; when it’s done, the web UI responds again. On a Raspberry Pi, with a fair number of monitors and weeks of history, be patient.

4. Check

  • Log into the web UI and make sure all the monitors are there.
  • Check the history is still there.
  • Review the notifications and send a test.

5. If it goes wrong: rolling back

This is what the backup is for. Putting louislam/uptime-kuma:1 back in compose isn’t enough: the database is already migrated and version 1 can’t read it. You have to restore the data too:

docker compose stop uptime-kuma
mv ~/services/uptime-kuma ~/services/uptime-kuma-v2-failed
tar xzf ~/backup/uptime-kuma-before-v2.tar.gz -C ~/services
# in compose, go back to: image: louislam/uptime-kuma:1
docker compose up -d uptime-kuma

Note that I don’t delete the version 2 folder: I rename it. If it later turns out the problem was something else, I haven’t lost anything.

What broke: the Python library

I’d created the monitors programmatically with an unofficial Python library that talks to Kuma’s API. With Kuma 2 it stopped working: the internal API changed.

If you automate Kuma with scripts, check this before upgrading. In my case, to look things up “behind the scenes” I now read the SQLite database directly (copying all three files, as above), and I make changes from the web UI.

Bonus: Portainer, which isn’t in compose

On my Pi, Portainer was started with a standalone docker run, not from docker-compose.yml. That means no docker compose pull: to upgrade it you have to stop, rename and relaunch it with the new tag. That’s how I went from 2.39.1 to 2.45.1.

First, back up the data volume (with Portainer stopped):

docker stop portainer
docker run --rm -v portainer_data:/data -v ~/backup:/backup alpine \
  tar czf /backup/portainer_data-pre-2.45.1.tar.gz -C /data .

Then rename the old one and launch the new one with the same ports and volumes it had:

docker rename portainer portainer-old
docker run -d --name portainer --restart=always \
  -p 8000:8000 -p 9443:9443 \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v portainer_data:/data \
  portainer/portainer-ce:2.45.1

If you don’t remember which options you used, docker inspect portainer-old tells you (ports under PortBindings, volumes under Mounts). Once the new one works, remove the old one with docker rm portainer-old. If it doesn’t, stop the new one, give the old one its name back and start it: you’re back where you were.

Here I use the exact version (2.45.1) rather than a generic tag, because Portainer doesn’t get upgraded by a stray pull: I decide when to move.

What not to do

  • Upgrade without a backup “because it’s just an image”. In a major version, the image changes the data.
  • Use latest: one day you pull for something else and a major version sneaks in.
  • Interrupt Kuma 2’s first start because it’s slow. That’s the migration.
  • Delete the old container or folder before checking the new one works.

Summary

  1. Write down your current version.
  2. Stop the container, copy the data folder and check the backup.
  3. Switch to the 2 tag, not latest, and let the migration finish.
  4. Check monitors, history and alerts.
  5. If it goes wrong, old image and old data.
  6. If you have scripts using its API, make sure they still work.

A major upgrade with a backup is a ten-minute chore. Without one, it’s a gamble.

Mini quiz

Did it stick?

Three quick questions. Each right answer is worth 10 XP.

  1. Which files do you need to copy together for a complete backup of Kuma's SQLite database?
  2. Which image tag did I use to stay on version 2 without surprises from future versions?
  3. You've started Kuma 2 and something's wrong. Is putting image 1 back in compose enough?
  • #uptime-kuma
  • #docker
  • #upgrades
  • #sqlite
  • #backup
Esc