Have you ever wondered how big companies know exactly when their websites go down? They use powerful monitoring tools, and one of the best for students and hobbyists is Uptime Kuma. Today, we are going to learn how to safely upgrade this tool to version 2.0, ensuring your data stays protected.
Uptime Kuma is an essential open-source service that tracks the status of your websites, APIs, and servers. While version 1.0 served us well, version 2.0 introduces several professional-grade features. The most significant change is the support for MariaDB as a database backend. In the past, we were limited to SQLite, which is like a small notebook for data. MariaDB is more like a large, organized filing cabinet, offering better performance and scalability. Additionally, this update adds support for Docker Secrets—which is vital for keeping your passwords safe—and many new notification providers to alert you if something goes wrong.
Before we begin the technical steps, we must address the golden rule of IT: always back up your data. Upgrading to a major version involves structural changes to how the software reads your information. If something goes wrong during the process, having a backup ensures you don’t lose your monitoring history or configurations. To start, you should navigate to your project directory and stop your current instance using the command docker-compose down. Please ensure you do not use the -v flag, as that would delete your persistent data volumes.
To create a proper backup of a Docker volume, we can use a temporary container. Think of this as a “helper” that packs your files into a suitcase before the big move. You can run a command using the busybox image to create a compressed .tar file of your uptime-kuma-data. This file will contain your kuma.db (the SQLite database), your uploaded files, and your SSL certificates. Once you have this archive safe on your hard drive, we can proceed with confidence.
The next step involves modifying your compose.yaml file. In previous versions, many users simply used the :latest tag for their Docker image. However, the developers have deprecated this for version 1.0 to prevent accidental upgrades that might break a system. To move to the new version, you must manually change the image tag from louislam/uptime-kuma:1 or louislam/uptime-kuma:latest to louislam/uptime-kuma:2. Using a specific version like 2.1.3 is even better because it ensures your environment remains stable and predictable.
Once you have updated the image tag, you can start the service again by running docker-compose up -d. This is where the magic happens. Uptime Kuma 2.0 will detect your old version 1.0 data and begin an automated migration process. It is crucial that you monitor this process by checking the logs with the command docker logs -f uptime-kuma. You will see a progress bar indicating that it is “Migrating Aggregate Table.” For a small setup, this might take a few seconds, but for a large monitoring environment with years of data, it could take several minutes. Whatever you do, do not stop the container while this is running! Stopping it mid-migration is like turning off a game console while it’s saving your progress; it can corrupt the database.
For those of you who want to take your home lab to the next level, you might want to switch from SQLite to MariaDB. This is an advanced step and is not officially supported for direct migration by the developers yet, but it is possible using community tools like sqlite3-to-mysql. To do this, you would first set up a MariaDB container in your Docker Compose file and then use the conversion tool to “inject” your old SQLite data into the new MariaDB instance. You would then need to add environment variables to your Uptime Kuma service, such as UPTIME_KUMA_DB_TYPE=mariadb, along with the host, username, and password for the database.
Successfully upgrading your tools is a key skill in becoming a proficient IT administrator. By moving to Uptime Kuma 2.0, you are not just getting new buttons and colors; you are moving toward a more robust, industry-standard architecture. Remember to always read the official migration guides provided by the developers, as they contain specific details about breaking changes that might affect your unique setup. I recommend that you verify all your monitors and notification settings once the upgrade is complete to ensure everything is functioning as expected. Keep exploring, and happy monitoring!