mirrors/uptime-kuma
1
0
Fork 1
mirror of https://github.com/louislam/uptime-kuma.git synced 2025-12-05 01:10:52 +00:00
Code Issues Packages Projects Releases Wiki Activity
Page: Migration From v1 To v2
Pages
3rd Party Addons Apps Badge Cloudflare Side Note Development Side Notes Docker Tags Environment Variables Home How to Monitor Docker Containers Internal API Maintenance Migration From v1 To v2 Notification Methods OpenRC Script Prometheus API Keys Prometheus Integration Reset Password via CLI Reverse Proxy with Cloudflare Tunnel Reverse Proxy Setup Development Environment Status Page Systemd Unit File Test Pull Requests Troubleshooting _Menu 🆙 How to Update 🔧 How to Install
Clone
24
Migration From v1 To v2
Louis Lam edited this page 2025-11-22 07:05:01 +08:00
Table of Contents

Warning

It is a major version update. It contains some breaking changes. Please read the migration guide carefully if you want to upgrade from v1 to v2.

Note

Before You Start

Stop your Uptime Kuma and:

  • Backup your data directory.
  • Make sure you have a backup of your data directory again.
  • Make sure you have a backup of your data directory again and again.

The migration process could take some time to complete, depending on the size of your database. This is because we need to aggregate the heartbeat table into the new, more optimised format.

  • You should be able to view logs of the migration process in the console.
  • Do NOT interrupt the migration process. If the migration process is interrupted, you must restore from backup and retry the upgrade.
  • FYI: My Uptime Kuma had 20 monitors and 90 days of data, and it took around 7 minutes to migrate. On slower hardware or with more monitors, this can take hours.

Breaking Changes

  • The :duration of these badge endpoints now accept values 24, 24h, 30d, 1y only
    • <kuma-url>/api/badge/:monitorID/ping/:duration
    • <kuma-url>/api/badge/:monitorID/uptime/:duration
  • Dropped support for legacy browsers
  • Removed deprecated feature Backup/Restore from JSON. Backing up the data directory is currently the only supported backup method.
  • Removed deprecated feature DNS Cache for HTTP monitors. Consider using the bundled nscd for docker installation.
  • Updated default retries for NEWLY created monitors from 1 to 0 to prevent user confusion
  • Switched Email (SMTP) notification subject/body templating from a custom-regex to LiquidJS. In LiquidJS,
    • variables are now case-sensitive, and
    • all non-matching variables are ignored.
    • These are the supported variables: name, msg, status, heartbeatJSON, monitorJSON, hostnameOrUrl. We don't have documentation for these yet, but you can refer to the source code for the data structure.

Docker only Breaking Changes

Non Docker Breaking Changes

  • Dropped support for Node.js 14, 16 and 18. The minimum supported version of Node.js is 20.4.

Docker Tags

There are some new tags available in v2, like *-slim, *-rootless tags.

Please read https://github.com/louislam/uptime-kuma/wiki/Docker-Tags

Warning

Rootless images are not recommended for upgrading from v1 to v2, you will likely run into startup issues.

Migration Steps (Docker)

  1. Stop your Uptime Kuma container.
docker stop uptime-kuma
  1. Backup your data directory.
  2. Change the image tag to louislam/uptime-kuma:2.
docker run -d --restart=unless-stopped -p <YOUR_PORT>:3001 -v <YOUR_DIR OR VOLUME>:/app/data --name uptime-kuma louislam/uptime-kuma:2
  1. Check the logs to see the migration process.
docker logs -f uptime-kuma

Migration Steps (Docker Compose)

  1. Stop your Uptime Kuma stack.
docker compose down

  1. Backup your data directory.

  2. Change the image tag to louislam/uptime-kuma:2.

services:
    uptime-kuma:
        image: louislam/uptime-kuma:2
....
  1. Start your Uptime Kuma stack.
docker compose up -d
  1. Check the logs to see the migration process.
docker compose logs -f

Migration Steps (Non-Docker)

  1. Stop your Uptime Kuma.
pm2 stop uptime-kuma
  1. Backup your data directory.
  2. Check your Node.js version, Node.js >= 20.4 is required.
node --version
  1. Follow https://github.com/louislam/uptime-kuma/wiki/%F0%9F%86%99-How-to-Update#--non-docker to update

FAQ

Can I migrate my existing SQLite database to MariaDB?

Cannot be done directly and is not supported by us. You will need to export your data from SQLite and import it into MariaDB using 3rd party tools such as sqlite3tomysql.

Important

We don't have the capacity to deal with issues that come from such migrations. If you run into any issues afterwards, please reproduce that your issue is caused by us and not the migration you did using a fresh installation first.

Installation & Configuration

Features

Network

Integrations

Development & Contributions

More

Edit this page