Uptime Kuma v2: Breaking Changes You Need to Know

Christian Lempa just released an 18-minute walkthrough on upgrading Uptime Kuma to version 2, and if you're running this monitoring tool in your homelab, you should probably watch it. Or at least read this, because the upgrade path includes a few landmines.

Uptime Kuma v2 arrived months after its first beta dropped in October, which tells you something about how these community-driven projects move. The headline feature is MariaDB support, replacing the SQLite-only limitation. There's also Docker Swarm secret support, new notification providers, and the usual collection of performance improvements that every major version promises.

But the interesting part isn't what's new—it's what broke.

The Tag Deprecation Nobody Expected

Lempa walks through several breaking changes, but the most consequential is this: the latest Docker tag is dead. Not updating. Not deprecated. Dead.

"If you're using the latest tag," Lempa explains, "you actually never really know what version you are using and pulling down. Therefore, the developers also made the decision to deprecate the latest tag completely."

I've been hearing this advice since Docker became popular—don't use latest in production. It's the kind of wisdom that gets repeated so often it stops sounding meaningful. But Uptime Kuma's developers actually pulled the trigger. If you're sitting on latest, your container isn't upgrading to v2. You have to explicitly switch to 2 or a specific version tag like 2.1.3.

This is either refreshingly principled or annoyingly paternalistic, depending on whether you had backups.

Alpine Images: Another Casualty

The developers also dropped Alpine Linux support entirely. Lempa doesn't use Alpine images in his templates anyway, citing previous headaches with PostgreSQL and Nginx. Alpine promises smaller images, but as he notes, "they don't always include all the right tools and the dependencies that might be needed for certain features."

The counterargument—that Alpine's minimalism is a security feature—doesn't get airtime here. Which is fair. If you're running Uptime Kuma in your basement and the Alpine image breaks twice a year, the security posture improvement probably isn't worth the support tickets you're filing with yourself.

The SQLite to MariaDB Migration Nobody Wants to Support

Here's where things get interesting. Uptime Kuma v2 supports MariaDB, but the developers explicitly don't support migrating from SQLite to MariaDB. You're on your own with third-party tools.

Lempa demonstrates the process using sqlite3-to-mysql, a Homebrew-installable tool that converts the database format. The actual conversion works—he shows it completing on his test instance. But notice what he's careful to say: "Just know that it is not officially supported by the maintainers of Uptimekuma."

This is the homelab version of warranty-voiding. The developers built the feature but won't help you use it. It's a reasonable position—database migrations are messy, SQLite and MariaDB have different quirks, and supporting every edge case would consume the project. But it creates a two-tier system: people who stick with SQLite get full support, people who want the better backend get a "good luck."

Lempa's migration took "six or seven minutes" on his production instance. For a test installation, it was seconds. The variable here is database size, obviously, but also—and this matters—whether you interrupt the process. Stop the container mid-migration and you're restoring from backup.

"You should also not stop the container while it's migrating," he warns, "otherwise the database is damaged and you will certainly need to restore from the backup and start over."

Which brings us to the real point of the video.

Backups: The Unsexy Part Everyone Skips

The migration guide says "back up your data directory" multiple times. Lempa emphasizes it repeatedly. He demonstrates creating backups before and after the v2 migration, using a BusyBox container with a tarball command to package the Docker volume.

This is the part where I notice how many "upgrade guide" videos I've watched that gloss over backups. They'll mention it—"obviously back up first"—and then spend fifteen minutes on the exciting stuff. Lempa spends actual time showing the backup commands, explaining what's in the archive, demonstrating how to extract it.

Because here's the truth about homelab upgrades: the interesting part is when they fail. And they fail regularly enough that the backup ceremony isn't paranoia, it's literacy.

"If we execute a docker volume ls," he explains, "you can see there is my uptime kuma docker volume that contains all of the important data. And to back up this, I'm always using a small and simple busybox docker image with a simple tarball command."

The whole video is structured around this assumption: something might break. Take backups before the v1-to-v2 migration. Take another backup after v2 is running before you attempt the SQLite-to-MariaDB conversion. Have a disaster recovery plan that's more sophisticated than "I hope this works."

Why MariaDB Anyway?

Toward the end, Lempa addresses the obvious question: why go through all this? For small homelabs, SQLite works fine. The answer is Docker Swarm redundancy.

"The main reason for moving to a true MariaDB database backend is that it is better for performance and scalability, especially if you're using Docker Swarm and you want to have some form of redundancy."

With MariaDB as a separate service, you can move the Uptime Kuma container between nodes during updates without caring about volume location. The database is the source of truth, not the container's filesystem.

This makes sense if you're running Docker Swarm. But how many people watching an 18-minute Uptime Kuma upgrade guide are running Docker Swarm? Lempa knows his audience—he mentions it as an option, not a requirement. For most viewers, SQLite is probably adequate.

Which raises an uncomfortable question about software development: when do you build features for the advanced users at the expense of complicating things for everyone else? Uptime Kuma v2 adds MariaDB support, which is great. But it also breaks latest tags and drops Alpine images, which affects everyone. The features are optional. The breaking changes aren't.

This is how mature software evolves. The early days are about adding features fast. Later comes the period where you fix your technical debt by breaking backwards compatibility. Some users upgrade smoothly. Others restore from backup and postpone the decision.

Lempa's video exists because version 2 is the second kind of release. If it were seamless, he wouldn't need eighteen minutes to explain it.

—Mike Sullivan, Technology Correspondent