Do these 3 things before closing this tab:
1Fix the driver behind crashes, sound loss and screen glitches2Repair Windows errors before they cause bigger problems3Scan for outdated or missing drivers - takes under a minuteUpgrade Uptime Kuma 1.x to 2.0 in place: stop the server, make and verify multiple copies of the complete data directory, keep the existing /app/data mount, change only the application version, and watch the migration logs until they finish. Uptime Kuma 2.0 is a major release with breaking changes. Do not interrupt its database migration; an interrupted run requires restoring the backup and retrying.
Need a server to try this on? Antihost offers Linux VPS plans with NVMe storage, full root access and a 14-day free trial.
What changes during a 1.x-to-2.0 upgrade
Uptime Kuma 2.0 performs a database migration as it starts for the first time against your 1.x data. The heartbeat table is aggregated into a new, optimized format. Your monitors, settings, notification configuration and historical data are intended to remain in the existing data store, but the conversion can take a significant amount of time because the duration depends on database size and hardware.
As an Amazon Associate I earn from qualifying purchases.
The project’s migration guide describes this as a major-version update with breaking changes. Treat it as a maintenance operation, not as a routine image refresh. Schedule a maintenance window, make recovery copies before stopping the service, and have console access to the host so you can follow the logs.
One published example is a Uptime Kuma installation with 20 monitors and 90 days of data that took about seven minutes to migrate. That is an illustration, not a benchmark or a completion guarantee. A larger history, slower storage or less powerful hardware may take hours.
#1 Best Overall
- Read Before You Buy — No Video Output: These adapters support charging and USB 2.0 data transfer, but cannot transmit video signals. Except for standard USB webcams (which use USB data only), they are not compatible with HDMI/DisplayPort cables, video-capable USB-C hubs, or docking stations with video output.
- Convert USB-A Ports to USB-C: Designed to connect USB-C earphones, cables, flash drives, card readers, and other USB-C accessories to standard USB-A ports. Plug-and-play with no drivers or software required.
- Aluminum Alloy Housing: Built with a sturdy aluminum alloy shell that aids in heat dissipation and protects against daily wear and scratches. Designed to maintain a stable and secure connection.
- Compact & Travel-Friendly: The ultra-compact design allows the adapter to stay plugged into your device without blocking adjacent ports or adding bulk, reducing wear and tear on your original USB ports.
- 12-Month Warranty: Backed by a 12-month manufacturer warranty for peace of mind. Designed to meet strict quality control standards for reliable everyday performance.
Preflight checklist before touching the installation
Stop monitoring changes and schedule downtime
Do not allow users or automation to edit monitors while you are taking the backup. Stop Uptime Kuma cleanly first, then copy its complete data directory. The copy must include the database and every other file under data; backing up only a database file is not the documented v2 backup method.
Choose a maintenance period long enough for a slow conversion and a verification pass. Notify anyone who depends on status pages, badges or alerting. Keep an administrator session and a shell session available throughout the first v2 startup so that a delayed migration is not mistaken for a dead service.
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 →Make multiple, restorable copies
Store at least two independent copies of the complete data directory, preferably on different storage. An external SSD or USB backup drive can be used as optional storage; Uptime Kuma does not require a particular drive, brand or capacity. After copying, check that the backup contains the expected files, has a plausible size, and can be read by the account that will perform a restore. Keep the original copy unchanged until the upgraded instance has been verified.
Where a named Docker volume is involved, make a copy of the volume contents rather than assuming the volume name alone is a backup. For a bind mount, record the exact host path. Write down ownership and permissions before changing containers, because a backup that cannot be read by the replacement process is difficult to use during an outage.
Version 2 removed the old JSON Backup/Restore feature. A data-directory copy is therefore the supported backup and recovery method. Do not rely on an export made with the removed JSON feature for this upgrade.
Check runtime and image constraints
- Node.js for non-Docker installs: Node.js 20.4 or newer is required. Support for Node.js 14, 16 and 18 was dropped.
- Docker base image: Alpine-based images are no longer supported for this migration.
- Host operating system: Debian or Raspbian Buster hosts have a documented
libseccomp2startup problem and should not be upgraded until the host issue is addressed. - Rootless containers: The migration guide warns that rootless images are likely to encounter startup issues during a v1-to-v2 upgrade. Do not switch to a rootless image as part of this change unless you have a separately tested recovery plan.
- Legacy browsers: They are no longer supported by v2, so confirm that administrators have a current browser available for the post-upgrade checks.
These checks are part of the upgrade, not optional cleanup. A perfectly copied database can still appear broken if the host has the Buster libseccomp2 problem, the image is Alpine-based, or a non-Docker process is using an old Node.js release.
Build a rollback plan before starting
Decide in advance which copy is the primary restore source and which is the untouched fallback. Record the old image tag or application version, the container name, the port mapping, the volume or bind-mount path, and the PM2 process name if applicable. This avoids searching for deployment details while an installation is unavailable.
If startup fails after an interruption, stop the v2 process first. Move the changed data directory aside, restore the complete pre-upgrade directory with its permissions intact, and use the prior application version while you reassess. Never overwrite both backup copies during troubleshooting. A rollback is a restore-and-retry operation, not an attempt to make v2 continue from a partially converted database.
Upgrade a Docker installation
1. Stop the existing container
Use the actual container name if yours differs from uptime-kuma:
Rank #2
- 5-in-1 USB-C Hub: Experience comprehensive connectivity featuring a Power Delivery input, two USB-A 2.0 ports, a USB-A 3.0 port, and an HDMI port. (Note: The USB-C power delivery input port is only for connecting an external wall charger to power your laptop and cannot power peripheral devices.)
- 90W Pass-Through Charging: Achieve optimal charging with 90W pass-through power to your laptop, supported by a total input of 100W, with the hub reserving 10W for operational efficiency. (Note: Wall charger not included.)
- Quick Data Transfers: Accelerate your productivity with rapid data transfers using a high-speed 5Gbps USB 3.0 port and two 480Mbps USB 2.0 ports.
- 4K HDMI Display: Enhance your visual experience with a hub capable of delivering 4K resolution at 30Hz in both mirror and extend modes. Please note that this hub is compatible with MacBook (macOS 12 and newer), Windows 10 and 11, ChromeOS, and laptops equipped with DP Alt Mode and Power Delivery. Note: This device is not compatible with Linux.
- What You Get: Anker USB-C Hub (5-in-1, 4K HDMI), welcome guide, 18-month warranty, and our friendly customer service.
docker stop uptime-kumaDo not remove the container or its volume before the backup is complete. The purpose of stopping it is to ensure the database is quiescent while you copy the data.
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 & 11Crashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minute2. Back up the mounted data
Identify the host directory or named volume mapped to /app/data. Copy that complete directory or volume to separate backup storage, and make the second copy before proceeding. Preserve ownership, permissions and hidden files. The mount is the important link between the 1.x container and the 2.0 container.
Check the mapping twice before recreating anything. A typo in the host path can create a new empty directory that looks valid to Docker but contains none of the old monitors. Keep the old container definition available until the v2 instance has passed its checks.
3. Change the image tag without changing the data mount
Replace the old image tag with louislam/uptime-kuma:2. Keep the same port mapping, container name and /app/data source. A representative command from the official migration procedure 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 host directory or volume for the angle-bracketed values. Do not accidentally create a new empty volume: if v2 starts with an empty /app/data, it cannot migrate the 1.x installation you intended to upgrade.
4. Follow the migration logs to completion
docker logs -f uptime-kumaKeep this command attached during the first start. The log output reports migration progress. A quiet period is not proof that the process has failed; the operation can be I/O-intensive. Do not press Ctrl+C on the Uptime Kuma process, restart the container, kill the host process or otherwise interrupt the migration while it is working.
Upgrade a Docker Compose stack
1. Shut down the stack cleanly
docker compose downUse the Compose project directory that owns the existing service. Confirm that the named volume or bind mount used by the service is still present; removing volumes at this point would remove the very data you need to migrate.
2. Back up the data directory or volume
Make and verify the multiple copies before editing the YAML file. The backup requirement is identical to a single-container installation: preserve the complete data directory, not just selected database files.
3. Change only the service image
Update the Uptime Kuma service to the v2 tag while retaining its existing volume and port declarations:
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Rank #3
- Sleek 7-in-1 USB-C Hub: Features an HDMI port, two USB-A 3.0 ports, and a USB-C data port, each providing 5Gbps transfer speeds. It also includes a USB-C PD input port for charging up to 100W and dual SD and TF card slots, all in a compact design.
- Flawless 4K@60Hz Video with HDMI: Delivers exceptional clarity and smoothness with its 4K@60Hz HDMI port, making it ideal for high-definition presentations and entertainment. (Note: Only the HDMI port supports video projection; the USB-C port is for data transfer only.)
- Double Up on Efficiency: The two USB-A 3.0 ports and a USB-C port support a fast 5Gbps data rate, significantly boosting your transfer speeds and improving productivity.
- Fast and Reliable 85W Charging: Offers high-capacity, speedy charging for laptops up to 85W, so you spend less time tethered to an outlet and more time being productive.
- What You Get: Anker USB-C Hub (7-in-1), welcome guide, 18-month warranty, and our friendly customer service.
services:
uptime-kuma:
image: louislam/uptime-kuma:2Keep the existing /app/data mapping and any other settings your deployment relies on. Do not combine this upgrade with an untested rootless or Alpine image change.
4. Start the stack and watch its logs
docker compose up -d
docker compose logs -fLeave the log stream running until the migration has completed and the service reports a normal startup. If you have multiple services, focus on the Uptime Kuma service output when diagnosing a delay.
Upgrade a non-Docker installation managed by PM2
- Stop the PM2 process:
pm2 stop uptime-kuma. - Copy and verify multiple complete backups of the
datadirectory. - Check the runtime:
node --version. The result must be Node.js 20.4 or newer; Node.js 14, 16 and 18 are no longer supported. - Follow the project’s non-Docker update procedure to install the v2 application files and dependencies.
- Start the process using your normal PM2 command and monitor its process output while the database migration runs.
Keep the pre-upgrade application files available until the new process has been checked. The data directory is still the recovery anchor if the migration fails or is interrupted.
Do not upgrade Node.js, change the process manager and alter the data location simultaneously unless those changes have already been tested. Keeping the runtime change isolated makes a startup error easier to diagnose and preserves a straightforward rollback.
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 →Repair Windows errors before they cause bigger problemsFix Now →Will monitors and history survive?
They should, provided that you point v2 at the same data directory and allow the migration to finish. The migration transforms the heartbeat table into the v2 optimized format; it is not a fresh installation. Because the operation changes the database in place, the project requires a complete backup before starting and instructs you to restore that backup if an interruption occurs.
After startup, sign in with a supported browser and check the items that matter to your operation:
- Several monitors from different monitor types, including one with a long history.
- Recent heartbeats and historical charts across the migration boundary.
- Notification channels and their test settings.
- Status pages, tags, maintenance windows and other site-specific configuration.
- Any external dashboards, badges or scripts that read Uptime Kuma endpoints.
Do not delete the backup until these checks pass and you have observed normal monitoring for a period appropriate to your environment. A successful web login alone does not prove that every notification, badge or historical chart survived correctly.
Breaking changes to audit after the upgrade
Badge duration syntax and limits
Badge endpoints now accept duration forms such as 24, 24h, 30d and 1y. The documented limits are 720 hours, 1,440 minutes and 365 days. Review every badge URL in dashboards, README files and automation. If a script sends an older duration format, update it to one of the accepted forms and test the resulting badge.
Check both hand-written URLs and generated URLs. A dashboard can continue loading while quietly showing an incorrect period, so compare a known badge with the corresponding history in the v2 interface.
Rank #4
- Dual Converters, Infinite Potential：Includes 2× USB C male to USB A female adapters and 2× USB A male to USB C female adapters. Perfect for a wide range of uses—tablets with Bluetooth keyboards, expand USB ports on macbook, and more. Two different converters for all your daily needs
- Next-Level 10Gbps & 3A Charging: No more slow 480Mbps, this usb to usb c adapter has a transfer speed of up to 10Gbps, allowing you to do more transferring in less time. This usb adapter fits both USB A and USB C charger, supporting up to 3A fast charging
- Upgraded Exquisite Craftsmanship: With an aluminum alloy housing and metal connector, the usbc to usb adapter is extremely durable and sturdy. Rigorously tested to withstand more than 10,000 times of plugging and unplugging, ensuring long-lasting performance
- Broad Compatible: The usb c to usb adapter widely supports all USB C/ USB A devices like laptops, tablets, cellphones, car chargers, and phone chargers. Such as compatible with MacBook Pro/Air 2023/2022, Thunderbolt 4/3 Devices,Apple MagSafe Watch 9/8/7/SE/Ultra, iPad Pro 2022/2021, Samsung Galaxy S23/S20/S10, and iPhone 17/16/15 Pro. Plug and play
- Please Note: To reach 10Gbps speed, keep the cable under 3.3 ft. For USB A Male to USB C adapters, try flipping the USB C connector. USB C Male to USB A adapters support bidirectional 10Gbps transfer within 3.3 ft
SMTP LiquidJS variables are case-sensitive
SMTP subject and body templates now use case-sensitive LiquidJS variable names. The supported names are:
namemsgstatusheartbeatJSONmonitorJSONhostnameOrUrl
Audit existing templates for incorrect capitalization and variables that are no longer supported. Send a test notification after correcting them rather than waiting for the next real incident.
New monitors now default to zero retries
For newly created monitors, the default retry count changed from 1 to 0. Existing monitors should be reviewed according to your desired alerting behavior, and provisioning scripts should set retries explicitly if they depend on a nonzero value.
Free tools Windows power users keep installed
One-click scans. No signup required.
Removed features and changed browser support
- The JSON Backup/Restore feature was removed; retain data-directory backups for future recovery.
- DNS Cache for HTTP monitors was removed. For Docker installations, the guide suggests using the bundled
nscdoption where DNS caching is needed. - Legacy browsers are unsupported, so use a current browser for administration.
SQLite to MariaDB: a separate, unsupported migration
Changing databases is not part of the normal 1.x-to-2.0 upgrade. A direct SQLite-to-MariaDB migration is not officially supported. The documented route is a third-party export/import process, and the migration guide specifically warns that sqlite3tomysql is not recommended because it does not create all required indexes and can significantly reduce performance.
The safer sequencing for most installations is to upgrade Uptime Kuma to v2 on the existing SQLite database first. Only after that installation is stable should you design and independently validate a database move, with a separate backup and rollback plan.
| Question | SQLite during the v1-to-v2 upgrade | SQLite to MariaDB move |
|---|---|---|
| Official support | Supported in-place path when the existing data directory is preserved. | Direct migration is not officially supported. |
| Tooling | Uptime Kuma performs its own v2 database migration at startup. | Third-party export/import is required; the guide does not endorse a complete tool. |
| Index and performance risk | The heartbeat table is converted to the v2 optimized format. | sqlite3tomysql may omit necessary indexes and significantly reduce performance. |
| When to do it | As the normal application upgrade, after a verified backup. | As a separate project after v2 is working, with independent validation and recovery copies. |
Do not combine a database move with the first v2 startup. If both operations happen at once, an error could come from the application migration, the export/import tool, missing indexes or database connectivity, making rollback ambiguous.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.What to do if migration appears stuck
First distinguish a slow migration from a failed one. Check the live Docker or PM2 logs, host CPU and disk activity, and available storage. The migration time depends on database size; the seven-minute example for 20 monitors and 90 days of data cannot be used as a deadline for another installation.
Recommended Free Tools
If logs are still progressing
- Leave the process running and continue watching the logs.
- Do not restart the container, stop the process, reboot the host or edit the database while migration is active.
- Keep the maintenance window open until the service reports a completed migration and normal startup.
A long period of disk activity with no web interface can be normal during heartbeat aggregation. Avoid repeatedly opening new shells that restart or recreate the service simply because the browser request times out.
If the process was interrupted or the startup fails
- Stop the v2 container or PM2 process so it cannot continue writing to the damaged or partially migrated database.
- Move the affected data directory aside rather than overwriting your only backup.
- Restore a complete pre-upgrade
datadirectory copy, including its original permissions. - Retry the upgrade from the known-good v1 data, using the supported v2 image or runtime prerequisites.
- Follow the logs from the beginning and allow the migration to finish without interruption.
This restore-and-retry procedure is required when an interrupted migration has left the database in an unusable state. Never attempt to repair a partial conversion by deleting tables or importing an unverified database dump.
Best Value
- 5-in-1 Connectivity: Equipped with a 4K HDMI port, a 5 Gbps USB-C data port, two 5 Gbps USB-A ports, and a USB C 100W PD-IN port. Note: The USB C 100W PD-IN port supports only charging and does not support data transfer devices such as headphones or speakers.
- Powerful Pass-Through Charging: Supports up to 85W pass-through charging so you can power up your laptop while you use the hub. Note: Pass-through charging requires a charger (not included). Note: To achieve full power for iPad, we recommend using a 45W wall charger.
- Transfer Files in Seconds: Move files to and from your laptop at speeds of up to 5 Gbps via the USB-C and USB-A data ports. Note: The USB C 5Gbps Data port does not support video output.
- HD Display: Connect to the HDMI port to stream or mirror content to an external monitor in resolutions of up to 4K@30Hz. Note: The USB-C ports do not support video output.
- What You Get: Anker 332 USB-C Hub (5-in-1), welcome guide, our worry-free 18-month warranty, and friendly customer service.
Docker and non-Docker procedures compared
| Concern | Docker or Compose | Non-Docker with PM2 |
|---|---|---|
| Stop command | docker stop uptime-kuma or docker compose down |
pm2 stop uptime-kuma |
| Runtime prerequisite | Use the supported v2 image; avoid Alpine and be cautious with rootless images. | Node.js 20.4 or newer; Node.js 14, 16 and 18 are unsupported. |
| Data path | Preserve the existing host directory or named volume mounted at /app/data. |
Preserve the existing complete data directory. |
| Log command | docker logs -f uptime-kuma or docker compose logs -f |
Use the PM2/process logs for the application. |
| Recovery | Stop v2, restore the pre-upgrade data directory or volume, then retry with the prior image and supported procedure. | Stop v2, restore the pre-upgrade data directory and application files, then retry. |
Final verification checklist
- The service starts without repeated migration errors.
- Several existing monitors show current heartbeats and expected historical data.
- Notification tests arrive with correctly rendered SMTP variables.
- Badge URLs and dashboards still return data with accepted duration syntax.
- New monitors have the retry behavior you intend.
- Any DNS-caching requirement has an approved v2-compatible arrangement.
- The original data-directory backups remain readable and have not been overwritten.
Once these checks pass, document the v2 image tag, Node.js version or host image used, the backup location and the date of the migration. Keep the old application version available until your normal retention policy allows its removal.
Frequently Asked Questions
How long does the Uptime Kuma 1.x-to-2.0 migration take?
There is no guaranteed duration. One published example—20 monitors with 90 days of data—took about seven minutes, while larger databases or slower storage can take hours. Follow the logs rather than using that example as a deadline.
Will my monitors and history be preserved?
They should be preserved when v2 uses the same complete data directory and the heartbeat migration finishes normally. Verify monitors, charts, notifications, status pages and badges before deleting backups.
What if the migration hangs?
Watch Docker or PM2 logs and host CPU and disk activity. If logs are progressing, leave the process alone. Do not restart or reboot. If it was interrupted or failed, stop v2, restore the complete pre-upgrade data copy and retry.
Can I upgrade and move from SQLite to MariaDB at the same time?
No. Direct SQLite-to-MariaDB migration is not officially supported. Upgrade to v2 on the existing database first, then treat any third-party export/import as a separate, tested project.
Can I keep using an Alpine or rootless image?
Alpine-based images are no longer supported for this migration. Rootless images are warned to have likely startup issues, so do not switch to one without a separately tested recovery plan.
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 problemsWhat Node.js version does a non-Docker installation need?
Node.js 20.4 or newer is required. Node.js 14, 16 and 18 are no longer supported.
What should I check in badges and email templates?
Badge durations now use forms such as 24, 24h, 30d and 1y, with documented limits. SMTP LiquidJS variables are case-sensitive; use only name, msg, status, heartbeatJSON, monitorJSON and hostnameOrUrl, then send a test notification.
Is the old JSON Backup/Restore feature still available?
No. Version 2 removed it. The supported backup method is a complete copy of the data directory, made before the migration and retained until verification is complete.
The Bottom Line
Back up the entire data directory twice, preserve the existing mount, change only the application version, and watch the migration logs without interruption. Check runtime and host constraints first, audit v2 breaking changes afterward, and treat any SQLite-to-MariaDB move as a separate unsupported project.
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.
