iTechGuides is reader-supported. When you buy through links on our site, we may earn an affiliate commission. As an Amazon Associate I earn from qualifying purchases. Learn more
Need a server to try this on? Antihost offers Linux VPS plans with NVMe storage, full root access and a 14-day free trial.
Upgrade Uptime Kuma in place only after stopping it and making several restorable copies of the complete data directory. Keep the existing data mount, change the application to the v2 image or release, and watch the migration logs without interrupting them. Uptime Kuma 2.0 is a major release: it rewrites the heartbeat table, removes several features, drops older Node.js versions, and changes some defaults.
What changes in the 1.x to 2.0 upgrade
The official migration guide, edited by Louis Lam on April 28, 2026, describes v2 as a major version update with breaking changes. This is not a routine image refresh. The upgrade runs a database migration that aggregates the heartbeat table into a new optimized format. Your monitors, settings, and retained history remain tied to the files in data, so preserving that directory and allowing the migration to finish are the two conditions that determine whether an in-place upgrade is safe.
PC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11Outdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware match
There is no guaranteed migration-time benchmark. The guide gives one example: an installation with 20 monitors and 90 days of data took about seven minutes. A larger database or slower storage can take hours. The process reports progress in the application logs; an apparently quiet period is not, by itself, evidence that it has stopped.
Preflight checklist before touching the installation
Stop every Uptime Kuma process
Do not copy a live database and then start the new version against that copy. Stop the container, Compose stack, or PM2 process first, and confirm that no second instance is writing to the same directory.
#1 Best Overall
Make multiple restorable copies of data
Copy the complete data directory, including its database, configuration, certificates, attachments, and any other files created by Uptime Kuma. Keep more than one copy on separate storage; an external SSD or USB backup drive is optional storage, not an Uptime Kuma component. Verify that each copy can be read and that its contents are materially complete before proceeding.
Version 2 no longer supports the old JSON Backup/Restore feature. A filesystem-level copy of data is the supported backup method, both before this upgrade and for future recovery.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Check the runtime and host constraints
| Installation or dependency | What to check | Required action |
|---|---|---|
| Docker image | Use the v2 image while retaining the existing /app/data mount. |
Do not point v2 at a new, empty data path. |
| Rootless Docker image | The migration guide warns that rootless images are likely to encounter startup issues during a 1.x-to-2.0 upgrade. | Use the supported image or prepare a separate, tested recovery plan before attempting rootless. |
| Alpine-based image | Alpine images are no longer supported. | Move to a supported non-Alpine image before the upgrade. |
| Debian or Raspbian Buster host | A documented libseccomp2 startup problem affects these hosts. |
Do not perform the upgrade on Buster; upgrade the host first or use another supported host. |
| Non-Docker runtime | Node.js 14, 16, and 18 support has been dropped. | Install Node.js 20.4 or newer and verify it with node --version. |
| Web browser | Legacy browsers are not supported by v2. | Plan to administer the upgraded instance with a current, supported browser. |
Record the current deployment details
- Write down the current 1.x image or application version.
- Record the host port and the exact host-directory or volume mounted at
/app/data. - Save your Compose file, environment variables, reverse-proxy settings, and process-manager configuration.
- Note any scripts that call badge endpoints, SMTP templates, or monitor-creation APIs; those are the areas most likely to need edits after the upgrade.
How long the migration takes and why it must not be interrupted
During first startup, v2 converts the heartbeat table to its optimized format. Work is proportional to the amount of stored data and constrained by database and storage speed. Logs show migration progress, but the guide publishes no universal time estimate. Seven minutes for 20 monitors and 90 days of data is an illustration, not a service-level guarantee; installations with substantially more history can require hours.
Never stop the container, kill the process, reboot the host, or replace files while migration is active. Louis Lam’s migration warning is explicit: “Do NOT interrupt the migration process. If the migration process is interrupted, you must restore from backup and retry the upgrade.” If you interrupt it, do not attempt a repair on the partially migrated directory. Stop the new version, restore the untouched backup, and start the upgrade again.
Upgrade a Docker installation
The Docker path is an in-place replacement: the application image changes, while the existing data mount does not.
- Stop the old container. Run
docker stop uptime-kuma. If your container has a different name, substitute that name. - Back up the mounted data. Copy the complete host directory or Docker volume used by
/app/datato multiple backup locations. Do not create a new empty directory for the v2 container. - Change the image tag. Replace the 1.x image reference with
louislam/uptime-kuma:2. Keep the same port mapping and the same/app/datavolume or bind mount. - Recreate the container. The official guide’s pattern is:
docker run -d --restart=unless-stopped -p <YOUR_PORT>:3001 -v <YOUR_DIR OR VOLUME>:/app/data --name uptime-kuma louislam/uptime-kuma:2Substitute your existing port and data path or volume. Preserve any additional settings your original container required; the example shows the essential port, restart policy, name, and data mount.
Do these 3 things before closing this tab:
1Clear out junk files and repair common Windows errors2Fix the driver behind crashes, sound loss and screen glitches3Repair Windows errors before they cause bigger problems- Follow the migration output. Run
docker logs -f uptime-kumaand leave the process alone until the migration completes and normal startup messages appear. - Open the web interface only after startup finishes. Sign in with a current browser and begin the post-upgrade checks described below.
Docker rollback
If startup fails for a host or image-compatibility reason, stop the v2 container. Restore the complete pre-upgrade data copy, then recreate the container with the exact 1.x image tag and original port and volume mapping. Restoring the files is essential: do not aim a 1.x image at a directory that v2 has partially migrated.
Upgrade a Docker Compose stack
- Stop the stack. From the directory containing the Compose file, run
docker compose down. - Back up the data directory or volume. Use the same complete, multi-copy backup procedure as for a single container.
- Change only the application image first. The service should point to v2, for example:
services:
uptime-kuma:
image: louislam/uptime-kuma:2Retain the existing volume declaration that maps the old data location to /app/data, along with your established ports, networks, restart policy, and environment settings.
- Start the updated stack. Run
docker compose up -d. - Watch all service output. Run
docker compose logs -fand wait for migration completion. Do not interrupt the stack because the first startup is still transforming the database.
Compose rollback
Bring the stack down, restore the pre-upgrade data copy, change the service image back to the recorded 1.x tag, and run docker compose up -d again. A rollback without restoring the data directory is unsafe if v2 had started or been interrupted during migration.
Upgrade a non-Docker installation managed by PM2
- Stop Uptime Kuma. Run
pm2 stop uptime-kumaand make sure the process is no longer writing to its data directory. - Back up the complete data directory. Keep multiple copies before changing application files.
- Verify Node.js. Run
node --version. The required version is Node.js 20.4 or newer; versions 14, 16, and 18 are no longer supported. - Update the application using the project’s non-Docker instructions. Keep the existing data-directory location and PM2 configuration. Do not substitute an Alpine-based package or an unsupported host runtime.
- Start and monitor the process. Start the updated PM2 application and follow its process logs until the database migration completes. Keep the terminal or log view available for the entire first startup.
Non-Docker rollback
Stop the updated PM2 process, restore the original data-directory copy, reinstall or check out the recorded 1.x application version, and start it with the original PM2 configuration. If the migration was interrupted, always restore the backup before trying again.
Quick wins for a faster PC:
Clear out junk files and repair common Windows errorsFree Scan →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Breaking changes to audit after startup
Once the interface loads, test the integrations that depend on changed v2 behavior. These changes are independent of whether you used Docker, Compose, or PM2.
| Area | Version 2 behavior | What you should do |
|---|---|---|
| Badge duration parameters | Endpoints accept forms such as 24, 24h, 30d, and 1y. The limits are 720 hours, 1,440 minutes, and 365 days. |
Review dashboards, README badges, scripts, and cached URLs that send the old duration syntax. Test a representative badge at each unit you use. |
| Browser support | Legacy browsers are no longer supported. | Use a current browser when signing in or diagnosing the upgraded instance. |
| Backups | JSON Backup/Restore has been removed. | Keep versioned copies of the complete data directory and document where they are stored. |
| HTTP-monitor DNS cache | The DNS Cache feature for HTTP monitors was removed. | If you depended on it in Docker, evaluate the bundled nscd option suggested by the migration guide and retest monitor resolution. |
| New-monitor retries | The default retry count for newly created monitors changed from 1 to 0. | Decide explicitly how many retries each new monitor should use; existing monitor behavior should be checked rather than assumed. |
| SMTP templates | Templates use case-sensitive LiquidJS variables. Supported names are name, msg, status, heartbeatJSON, monitorJSON, and hostnameOrUrl. |
Audit every subject and body template for capitalization and remove unsupported variable names, then send a controlled test notification. |
Can you migrate SQLite to MariaDB during this upgrade?
Not as an officially supported, single-step operation. The documented v1-to-v2 procedure upgrades the existing database in place. A SQLite-to-MariaDB move is a separate third-party export/import project and should not be combined with the first v2 startup.
| Question | SQLite kept in place | SQLite to MariaDB |
|---|---|---|
| Official support | Yes, this is the database path used by the in-place v2 migration. | No direct, officially supported migration is documented. |
| Tooling | Use the normal v2 startup migration. | Requires a third-party export/import workflow and independent validation. |
| Index and performance risk | The official migration creates the optimized heartbeat format. | The guide specifically says sqlite3tomysql is not recommended because it does not create all required indexes and can significantly reduce performance. |
| Timing | Part of the 1.x-to-2.0 upgrade and visible in startup logs. | A separate maintenance project with its own backup, testing, and rollback window. |
The safest sequence is to complete and verify the v2 upgrade on the existing database first. Only then, if MariaDB is a requirement, plan an independently tested export/import with a restorable copy and a measured way to compare monitors, history, notifications, and query performance. Do not treat a successful third-party import as evidence that the official in-place migration has been completed.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Troubleshooting migration and startup problems
The migration appears stuck
First check the appropriate log stream: docker logs -f uptime-kuma for a standalone container, docker compose logs -f for Compose, or the PM2 process logs for a non-Docker installation. Compare the elapsed time with the size of your retained history and storage speed. The seven-minute example applies only to the guide’s 20-monitor, 90-day installation; larger data sets can take hours.
The Tool Desk
Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Do not stop the process merely because progress is slow or intermittent. If the logs show an actual error and the process exits, preserve the logs, stop the failed v2 instance, restore the untouched backup, and retry after correcting the underlying compatibility issue.
The process was interrupted
Restore the complete pre-upgrade data directory, not selected database files. Recreate the same deployment and rerun the migration from the beginning. Continuing with a partially migrated directory risks an inconsistent database.
Best Value
The container exits immediately
- Confirm that the host is not Debian or Raspbian Buster with the documented
libseccomp2problem. - Confirm that you changed away from an unsupported Alpine image.
- If you used a rootless image, return to the supported image or follow a separately tested recovery plan; the migration guide warns of startup issues with rootless images.
- Check that the original data volume is mounted at
/app/dataand is accessible to the container.
The non-Docker process will not start
Run node --version and upgrade to Node.js 20.4 or newer if necessary. Node.js 14, 16, and 18 are not supported in v2. Then verify that the PM2 process still points to the same application directory and data path used before the upgrade.
Monitors or history seem missing
Stop and verify the mount or data path before making any further changes. A newly created empty data directory produces an apparently clean installation with no monitors. If the original path was mounted correctly but migration was interrupted, restore the backup and repeat the migration rather than importing individual files.
Recommended Free Tools
Alerts, badges, or HTTP checks changed behavior
Use the breaking-change table as a targeted audit: test badge duration syntax and limits, inspect SMTP variable casing, set retries explicitly on new monitors, and review any HTTP-monitor DNS-cache dependency. These checks should be performed after the database migration has completed, not by restarting repeatedly during migration.
Docker versus non-Docker: operational differences
| Comparison point | Docker or Compose | Non-Docker with PM2 |
|---|---|---|
| Stop command | docker stop uptime-kuma, or docker compose down for a stack. |
pm2 stop uptime-kuma. |
| Runtime prerequisite | Supported v2 image; avoid Alpine, Buster hosts, and untested rootless images. | Node.js 20.4 or newer; Node.js 14, 16, and 18 are dropped. |
| Data preservation | Keep the existing host directory or volume mounted at /app/data. |
Keep the existing application data-directory path and PM2 configuration. |
| Migration logs | docker logs -f uptime-kuma or docker compose logs -f. |
Follow the PM2 application’s process logs. |
| Rollback | Stop v2, restore the pre-upgrade data copy, and recreate the prior 1.x image or Compose service. | Stop v2, restore the pre-upgrade data copy, reinstall the recorded 1.x release, and restart PM2. |
Post-upgrade verification checklist
- Sign in with a current browser and confirm the expected server version.
- Check that every monitor appears with its URL, interval, notification settings, and status.
- Open representative monitor history and confirm that the migrated data is available.
- Trigger a controlled notification and verify SMTP subject and body rendering.
- Load each badge or dashboard URL used by another system, including duration parameters.
- Create a test monitor in a safe context and confirm its retry setting is what you intend; the new default is zero.
- Exercise HTTP monitors that previously depended on the removed DNS Cache feature.
- Record the successful v2 deployment details and retain the pre-upgrade backup until the new installation has been stable for your chosen retention period.
After these checks pass, future backups should continue to be complete copies of the data directory. The removed JSON Backup/Restore feature is not a substitute for that filesystem backup.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
