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.
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 straypull: 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 youpullfor 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
- Write down your current version.
- Stop the container, copy the data folder and check the backup.
- Switch to the
2tag, notlatest, and let the migration finish. - Check monitors, history and alerts.
- If it goes wrong, old image and old data.
- 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.
Did it stick?
Three quick questions. Each right answer is worth 10 XP.