fix(docker): normalize container CPU usage

apps/docs/docs/getting-started/upgrade-v2.mdx

@@ -1,74 +0,0 @@
----
-title: Upgrade from v1 to v2
-sidebar_position: 2
-tags:
-  - Getting started
-  - Upgrade
-  - Migration
-  - Backup
----
-
-Homarr v2 upgrades the existing v1 database in place. Keep the same data storage, database configuration, and
-`SECRET_ENCRYPTION_KEY`; only change the Homarr image or package version for the first start.
-
-:::danger Back up before starting v2
-
-In Homarr v1, go to **Management → Tools → Backup**, export a backup, and keep the downloaded file somewhere safe
-before starting v2. See [Backup and restore](/docs/management/backup) for details.
-
-:::
-
-## Upgrade
-
-1. Pin the Homarr image to `ghcr.io/homarr-labs/homarr:v2.0.0` for the first v2 start.
-2. Keep the existing `/appdata` mount, database variables, Redis configuration, and `SECRET_ENCRYPTION_KEY` unchanged.
-3. Start one Homarr replica and follow its logs. Startup must reach `Migration complete`; Homarr aborts startup when a
-   database migration fails.
-4. Open Homarr and sign in. Confirm **Management → About** reports v2 before starting additional replicas.
-5. After validation, keep the version pinned or return to your normal stable release policy.
-
-For Docker Compose, the change is limited to the image tag before the usual update:
-
-```yaml
-services:
-  homarr:
-    image: ghcr.io/homarr-labs/homarr:v2.0.0
-```
-
-```sh
-docker compose pull
-docker compose up -d
-docker compose logs --follow homarr
-```
-
-Do not add `-v` when stopping the Compose deployment; that can remove named volumes.
-
-## What v2 migrates
-
-The startup migration:
-
-- creates the Custom Widget v2, Assistant, header preference, and branding storage;
-- adds Base/Mobile layout roles and left/right board gutters;
-- converts legacy Categories and dynamic sections into Containers and rails;
-- preserves legacy Custom Widget definitions, encrypted secrets, and board references for explicit migration.
-
-Legacy Custom Widgets are not silently rewritten. In **Management → Custom Widgets**, entries marked
-**Migration required** provide a credential-free migration prompt. Review and test the resulting v2 definition before
-removing the archived v1 version. See [Custom Widgets: Import and Workshop](/docs/management/custom-widgets#import-and-workshop).
-
-## Verify the upgraded instance
-
-- Sign in with each enabled authentication method and verify administrator access.
-- Open every important board on desktop and mobile. Check Containers, former Categories, rails, item placement, and
-  home-board assignments.
-- Test at least one read and one permitted action for each critical integration. Recheck integration and board access
-  for representative Viewer, Editor, and Admin groups.
-- Check Docker or Podman endpoints, search engines, uploaded media, trusted certificates, scheduled tasks, WebSockets,
-  and external Redis when used.
-- Review every legacy Custom Widget and migrate it only after its v2 preview and requests work.
-- Restart Homarr once more and confirm the logs contain no migration, database, Redis, authentication, or task errors.
-
-## Roll back
-
-Use the backup exported before the upgrade if you need to restore your v1 installation. Do not reuse a database that
-v2 has already migrated with v1.

packages/request-handler/src/docker.ts

@@ -481,13 +481,14 @@ export function calculateCpuUsage(stats: ContainerStats): number {
     return 0;
   }
 
-  const numberOfCpus = stats.cpu_stats.online_cpus;
+  const cpuDelta = stats.cpu_stats.cpu_usage.total_usage - (stats.precpu_stats?.cpu_usage?.total_usage ?? 0);
-  const usage = stats.cpu_stats.system_cpu_usage;
+  const systemDelta = (stats.cpu_stats.system_cpu_usage ?? 0) - (stats.precpu_stats?.system_cpu_usage ?? 0);
-  if (!usage || usage === 0) {
+
+  if (systemDelta <= 0 || cpuDelta < 0) {
     return 0;
   }
 
-  return (stats.cpu_stats.cpu_usage.total_usage / usage) * numberOfCpus * 100;
+  return (cpuDelta / systemDelta) * 100;
 }
 
 export function calculateMemoryUsage(stats: ContainerStats): number {

packages/request-handler/src/test/docker.spec.ts

@@ -72,16 +72,16 @@ describe("calculateCpuUsage", () => {
     const stats = createStats({
       cpu_stats: { online_cpus: 4, cpu_usage: { total_usage: 2000 }, system_cpu_usage: 10000 },
     });
-    // (2000 / 10000) * 4 * 100 = 80
+    // (2000 / 10000) * 100 = 20
-    expect(calculateCpuUsage(stats)).toBe(80);
+    expect(calculateCpuUsage(stats)).toBe(20);
   });
 
   test("should handle fractional CPU usage", () => {
     const stats = createStats({
       cpu_stats: { online_cpus: 2, cpu_usage: { total_usage: 500 }, system_cpu_usage: 100000 },
     });
-    // (500 / 100000) * 2 * 100 = 1
+    // (500 / 100000) * 100 = 0.5
-    expect(calculateCpuUsage(stats)).toBe(1);
+    expect(calculateCpuUsage(stats)).toBe(0.5);
   });
 });