fix(startup): only chown runtime paths for custom PUID/PGID

Recursively chowning the entire /app tree on startup is extremely slow
on network- or HDD-backed storage (e.g. TrueNAS Apps). The Next.js
standalone bundle and its node_modules contain tens of thousands of
tiny files, turning the advertised ~10s ownership step into 15+ minutes.

Only chown the paths the non-root user actually writes to at runtime:
the /appdata volume, the Next.js cache directory and the nginx runtime
directories. Application code, DB migrations and native modules are only
read/executed and stay owned by root.

The known /appdata subdirectories are created and their existing content
recursively re-owned before dropping privileges, so a persistent volume
with stale or root-owned entries stays writable after a PUID/PGID change.
These trees are small, unlike the /app tree.

Closes #2190

apps/docs/docs/integrations/truenas/index.mdx

@@ -27,8 +27,6 @@ import Alert from '@theme/Admonition';
       ]}
 />
 
-The storage values shown by these widgets use the root ZFS dataset's usable `used` and `available` space, including RAIDZ parity overhead and dataset limits.
-
 ### Adding the integration
 <AddingIntegration />
 

apps/docs/docs/widgets/smart-home-entity-state/index.mdx

@@ -43,7 +43,6 @@ import temperature from './img/temperature.png';
 ### Interactions
 
 - Toggle entity state by clicking on the entity (only when clickable enabled).
-- After a successful toggle, the displayed state refreshes immediately.
 
 ### Adding the widget
 
@@ -65,4 +64,4 @@ import retrieveEntityId from './img/retrieve-entity-id.png';
 
 <div>
   <img src={retrieveEntityId} alt="homeassistant retrieve-entity-id" width={256 * 2} />
-</div>
+</div>

apps/docs/docs/widgets/smart-home-execute-automation/index.mdx

@@ -47,7 +47,4 @@ import withDisplayname from './img/with-displayname.png';
 <AddingWidget />
 
 ### Configuration
-
-Use the Home Assistant entity ID (for example, `automation.turn_on_lights`) in the **Automation ID** field, not the automation's internal ID.
-
 <WidgetConfig configuration={smartHomeExecuteAutomationWidget.configuration} />

e2e/onboarding.spec.ts

@@ -7,6 +7,42 @@ import { createHomarrContainer } from "./shared/create-homarr-container";
 import { createSqliteDbFileAsync } from "./shared/e2e-db";
 
 describe("Onboarding", () => {
+  test("Credentials onboarding should be successful", async () => {
+    // Arrange
+    const { db, localMountPath } = await createSqliteDbFileAsync();
+    const homarrContainer = await createHomarrContainer({
+      mounts: {
+        "/appdata": localMountPath,
+      },
+    }).start();
+
+    const browser = await chromium.launch();
+    const context = await browser.newContext();
+    const page = await context.newPage();
+    const actions = new OnboardingActions(page, db);
+    const assertions = new OnboardingAssertions(page, db);
+
+    try {
+      // Act
+      await page.goto(`http://${homarrContainer.getHost()}:${homarrContainer.getMappedPort(7575)}`);
+      await actions.startOnboardingAsync("scratch");
+      await actions.processUserStepAsync({
+        username: "admin",
+        password: "Comp(exP4sswOrd",
+        confirmPassword: "Comp(exP4sswOrd",
+      });
+      await actions.processSettingsStepAsync();
+      await actions.processIntegrationsStepAsync();
+
+      // Assert
+      await assertions.assertFinishStepVisibleAsync();
+      await assertions.assertUserAndAdminGroupInsertedAsync("admin");
+      await assertions.assertDbOnboardingStepAsync("finish");
+    } finally {
+      await Promise.all([browser.close(), homarrContainer.stop()]);
+    }
+  }, 60_000);
+
   test("External provider onboarding setup should be successful", async () => {
     // Arrange
     const { db, localMountPath } = await createSqliteDbFileAsync();

packages/api/src/router/widgets/smart-home.ts

@@ -1,4 +1,3 @@
-import { TRPCError } from "@trpc/server";
 import { z } from "zod/v4";
 
 import { getIntegrationKindsByCategory } from "@homarr/definitions";
@@ -42,13 +41,6 @@ export const smartHomeRouter = createTRPCRouter({
       const client = await createIntegrationAsync(integration);
       const success = await client.triggerToggleAsync(input.entityId);
 
-      if (!success) {
-        throw new TRPCError({
-          code: "INTERNAL_SERVER_ERROR",
-          message: "Home Assistant failed to toggle the entity",
-        });
-      }
-
       return success;
     }),
   executeAutomation: protectedProcedure
@@ -63,13 +55,6 @@ export const smartHomeRouter = createTRPCRouter({
     .input(z.object({ automationId: z.string() }))
     .mutation(async ({ ctx: { integration }, input }) => {
       const client = await createIntegrationAsync(integration);
-      const success = await client.triggerAutomationAsync(input.automationId);
-
-      if (!success) {
-        throw new TRPCError({
-          code: "INTERNAL_SERVER_ERROR",
-          message: "Home Assistant failed to trigger the automation",
-        });
-      }
+      await client.triggerAutomationAsync(input.automationId);
     }),
 });

packages/core/src/infrastructure/http/request.ts

@@ -14,10 +14,6 @@ import { UndiciHttpAgent } from "@homarr/core/infrastructure/http";
 import type { TrustedCertificateHostname } from "../certificates/hostnames";
 import { withTimeoutAsync } from "./timeout";
 
-import packageJson from "../../../../../package.json";
-
-export const getDefaultUserAgent = () => `Homarr/${packageJson.version} (+https://homarr.dev)`;
-
 export const createCustomCheckServerIdentity = (
   trustedHostnames: TrustedCertificateHostname[],
 ): typeof checkServerIdentity => {
@@ -83,10 +79,6 @@ export const fetchWithTrustedCertificatesAsync = async (
       async (signal) =>
         fetch(url, {
           ...fetchOptions,
-          headers: {
-            "User-Agent": getDefaultUserAgent(),
-            ...fetchOptions.headers,
-          },
           signal,
           dispatcher: agent,
         }),
@@ -97,10 +89,6 @@ export const fetchWithTrustedCertificatesAsync = async (
   const { bodyTimeout: _bodyTimeout, dispatcher: _dispatcher, ...fetchOptions } = options ?? {};
   return fetch(url, {
     ...fetchOptions,
-    headers: {
-      "User-Agent": getDefaultUserAgent(),
-      ...fetchOptions.headers,
-    },
     dispatcher: agent,
   });
 };

packages/integrations/src/homeassistant/homeassistant-integration.ts

@@ -134,10 +134,7 @@ export class HomeAssistantIntegration extends Integration implements ISmartHomeI
    */
   private async postAsync(path: `/api/${string}`, body: Record<string, string>) {
     return await fetchWithTrustedCertificatesAsync(this.url(path), {
-      headers: {
-        ...this.getAuthHeaders(),
-        "Content-Type": "application/json",
-      },
+      headers: this.getAuthHeaders(),
       body: JSON.stringify(body),
       method: "POST",
     });

packages/integrations/src/truenas/test/truenas-integration.spec.ts

@@ -148,14 +148,6 @@ const happyResponder = (method: string) => {
       ];
     case "pool.query":
       return [{ name: "tank", status: "ONLINE", healthy: true, free: 500, size: 1000, allocated: 500 }];
-    case "pool.dataset.query":
-      return [
-        {
-          id: "tank",
-          used: { parsed: 200 },
-          available: { parsed: 300 },
-        },
-      ];
     case "interface.query":
       return [{ id: "eth0", name: "eth0" }];
     case "reporting.netdata_get_data":
@@ -199,18 +191,6 @@ describe("TrueNasIntegration", () => {
     // JSON-RPC does not use the legacy "connect" session handshake.
     expect(ws.sentPayloads.some((payload) => payload.msg === "connect")).toBe(false);
 
-    const datasetPayload = ws.sentPayloads.find((payload) => payload.method === "pool.dataset.query");
-    expect(datasetPayload).toMatchObject({
-      params: [
-        [["id", "in", ["tank"]]],
-        {
-          extra: {
-            properties: ["used", "available"],
-          },
-        },
-      ],
-    });
-
     expect(result).toMatchObject({
       version: "TrueNAS-SCALE-24.10",
       cpuModelName: "Intel Xeon",
@@ -224,25 +204,12 @@ describe("TrueNasIntegration", () => {
       loadAverage: null,
       gpu: [],
       network: { up: 20_000, down: 10_000 },
-      // `available` and `used` come from the root dataset, not the physical pool.
-      fileSystem: [{ deviceName: "tank", available: "300", used: "200", percentage: 40 }],
+      // `available` is the free space left on the pool (free = 500), not its total size.
+      fileSystem: [{ deviceName: "tank", available: "500", used: "500", percentage: 50 }],
       smart: [{ deviceName: "tank", healthy: true, overallStatus: "ONLINE", temperature: null }],
     });
   });
 
-  test("reports zero usage for an empty root dataset", async () => {
-    ws.setResponder((method) =>
-      method === "pool.dataset.query"
-        ? [{ id: "tank", used: { parsed: 0 }, available: { parsed: 0 } }]
-        : happyResponder(method),
-    );
-    const integration = createIntegration(credentials);
-
-    const result = await integration.getSystemInfoAsync();
-
-    expect(result.fileSystem[0]?.percentage).toBe(0);
-  });
-
   test("authenticates with an API key when one is configured", async () => {
     const integration = createIntegration([{ kind: "apiKey", value: "api-key-123" }]);
 

packages/integrations/src/truenas/truenas-integration.ts

@@ -49,10 +49,9 @@ export class TrueNasIntegration extends Integration implements ISystemHealthMoni
       memUsedInBytes,
       fileSystem: datasets.map((dataset) => ({
         deviceName: dataset.name,
-        available: `${dataset.available}`,
-        used: `${dataset.used}`,
-        percentage:
-          dataset.used + dataset.available === 0 ? 0 : (dataset.used / (dataset.used + dataset.available)) * 100,
+        available: `${dataset.free}`, // free space left on the pool
+        used: `${dataset.allocated}`,
+        percentage: (dataset.allocated / dataset.size) * 100,
       })),
       availablePkgUpdates: 0,
       network: {
@@ -118,40 +117,12 @@ export class TrueNasIntegration extends Integration implements ISystemHealthMoni
         return null;
       })
       .filter((pool) => pool !== null);
-
-    if (activePools.length === 0) return [];
-
-    const datasets = await this.requestAsync("pool.dataset.query", [
-      [["id", "in", activePools.map((pool) => pool.name)]],
-      {
-        extra: {
-          properties: ["used", "available"],
-        },
-      },
-    ]);
-    const parsedDatasets = await poolDatasetSchema.parseAsync(datasets);
-
-    const poolsWithUsableSpace = activePools
-      .map((pool) => {
-        const dataset = parsedDatasets.find((candidate) => candidate.id === pool.name);
-        if (!dataset || dataset.used.parsed === null || dataset.available.parsed === null) return null;
-
-        return {
-          name: pool.name,
-          status: pool.status,
-          healthy: pool.healthy,
-          used: dataset.used.parsed,
-          available: dataset.available.parsed,
-        };
-      })
-      .filter((pool) => pool !== null);
-
     logger.debug("Retrieved pools", {
       url: this.integration.url,
       totalCount: result.length,
-      activeCount: poolsWithUsableSpace.length,
+      activeCount: activePools.length,
     });
-    return poolsWithUsableSpace;
+    return activePools;
   }
 
   /**
@@ -292,14 +263,6 @@ const poolSchema = z.array(
   }),
 );
 
-const poolDatasetSchema = z.array(
-  z.object({
-    id: z.string(),
-    used: z.object({ parsed: z.number().min(0).nullable() }),
-    available: z.object({ parsed: z.number().min(0).nullable() }),
-  }),
-);
-
 const reportingNetDataSchema = z.array(
   z.object({
     name: z.string(),

packages/integrations/test/home-assistant-unit.spec.ts

@@ -1,48 +0,0 @@
-// @vitest-environment node
-
-import { beforeEach, describe, expect, test, vi } from "vitest";
-
-import { fetchWithTrustedCertificatesAsync } from "@homarr/core/infrastructure/http";
-
-import { HomeAssistantIntegration } from "../src";
-
-vi.mock("@homarr/core/infrastructure/http", () => ({
-  fetchWithTrustedCertificatesAsync: vi.fn(),
-}));
-
-const mockFetch = vi.mocked(fetchWithTrustedCertificatesAsync);
-const integration = new HomeAssistantIntegration({
-  id: "home-assistant",
-  name: "Home Assistant",
-  url: "http://home-assistant.local:8123",
-  externalUrl: null,
-  decryptedSecrets: [{ kind: "apiKey", value: "secret" }],
-});
-
-describe("HomeAssistantIntegration actions", () => {
-  beforeEach(() => {
-    mockFetch.mockReset();
-    mockFetch.mockResolvedValue({ ok: true } as never);
-  });
-
-  test.each([
-    ["toggle", () => integration.triggerToggleAsync("light.desk"), "/api/services/homeassistant/toggle", "light.desk"],
-    [
-      "automation",
-      () => integration.triggerAutomationAsync("automation.turn_on_lights"),
-      "/api/services/automation/trigger",
-      "automation.turn_on_lights",
-    ],
-  ])("sends the %s service call as JSON", async (_action, trigger, path, entityId) => {
-    await expect(trigger()).resolves.toBe(true);
-
-    expect(mockFetch).toHaveBeenCalledWith(new URL(`http://home-assistant.local:8123${path}`), {
-      headers: {
-        Authorization: "Bearer secret",
-        "Content-Type": "application/json",
-      },
-      body: JSON.stringify({ entity_id: entityId }),
-      method: "POST",
-    });
-  });
-});

packages/request-handler/src/smart-home-entity-state.ts

@@ -18,6 +18,4 @@ export const smartHomeEntityStateRequestHandler = createIntegrationRequestHandle
 
     return result.data.state;
   },
-  // The widget already polls every 30 seconds and refetches after toggles.
-  cacheTtlMs: 0,
 });

paseo.json

@@ -1,26 +0,0 @@
-{
-  "worktree": {
-    "setup": "mise trust\nmise install\npnpm install\n\nif [ -n \"${PASEO_SOURCE_CHECKOUT_PATH:-}\" ] && [ -f \"$PASEO_SOURCE_CHECKOUT_PATH/.env\" ]; then\n  cp \"$PASEO_SOURCE_CHECKOUT_PATH/.env\" .env\nelse\n  cp .env.example .env\nfi\n\nDB_PATH=\"$PWD/homarr.sqlite\"\nZERO_KEY=\"0000000000000000000000000000000000000000000000000000000000000000\"\nsed -i.bak \\\n  -e \"s|^DB_DRIVER=.*|DB_DRIVER='better-sqlite3'|\" \\\n  -e \"s|^DB_URL=.*|DB_URL='$DB_PATH'|\" \\\n  -e \"s|^SECRET_ENCRYPTION_KEY=.*|SECRET_ENCRYPTION_KEY=$ZERO_KEY|\" \\\n  .env\nrm -f .env.bak\n\nrm -f homarr.sqlite\npnpm db:migration:sqlite:run",
-    "teardown": "rm -f homarr.sqlite",
-    "servicePorts": {
-      "range": "3000-4000"
-    }
-  },
-  "scripts": {
-    "dev": {
-      "type": "service",
-      "command": "PORT=$PASEO_PORT pnpm -F nextjs dev"
-    },
-    "docs": {
-      "type": "service",
-      "command": "pnpm -F @homarr/docs dev --port $PASEO_PORT"
-    },
-    "build": { "command": "pnpm build" },
-    "test": { "command": "pnpm test" },
-    "test:e2e": { "command": "pnpm test:e2e" },
-    "lint": { "command": "pnpm lint" },
-    "typecheck": { "command": "pnpm typecheck" },
-    "db:seed": { "command": "pnpm db:seed" },
-    "db:studio": { "command": "pnpm db:studio" }
-  }
-}

scripts/entrypoint.sh

@@ -7,14 +7,31 @@ export PGID=${PGID:-0}
 echo "Starting with UID='$PUID', GID='$PGID'"
 
 if [ "${PUID}" != "0" ] || [ "${PGID}" != "0" ]; then
-    # The below command will change the owner of all files in the /app directory (except node_modules) to the new UID and GID
-    echo "Changing owner to $PUID:$PGID, this will take about 10 seconds..."
-    find . -name 'node_modules' -prune -o -mindepth 1 -maxdepth 1 -exec chown -R $PUID:$PGID {} +
-    chown -R $PUID:$PGID /var/cache/nginx
-    chown -R $PUID:$PGID /var/log/nginx
-    chown -R $PUID:$PGID /var/lib/nginx
-    chown -R $PUID:$PGID /run/nginx/nginx.pid
-    chown -R $PUID:$PGID /etc/nginx
+    # Only chown the paths the non-root user must actually write to at runtime.
+    # Recursively chowning the whole /app tree is extremely slow on network- or
+    # HDD-backed storage (e.g. TrueNAS Apps), because the Next.js standalone
+    # bundle and its node_modules contain tens of thousands of tiny files. This
+    # turned a ~10s step into 15+ minutes for some users (#2190). Application
+    # code, migrations and native modules are only read/executed, so they stay
+    # owned by root and do not need chowning.
+    echo "Changing owner to $PUID:$PGID..."
+    # Application data volume (db, redis dumps, trusted certificates).
+    # Ensure the known subdirectories exist and migrate ownership of any
+    # existing content, so a persistent volume with stale or root-owned
+    # entries stays writable after a PUID/PGID change. These trees are small
+    # (a single sqlite db, a redis dump, a few certs), unlike the /app tree.
+    mkdir -p /appdata/db /appdata/redis /appdata/trusted-certificates
+    chown "${PUID}:${PGID}" /appdata
+    chown -R "${PUID}:${PGID}" /appdata/db /appdata/redis /appdata/trusted-certificates
+    # Next.js runtime cache (image optimization, fetch cache, ...)
+    mkdir -p /app/apps/nextjs/.next/cache
+    chown -R "${PUID}:${PGID}" /app/apps/nextjs/.next/cache
+    # nginx runtime directories and the rendered configuration
+    chown -R "${PUID}:${PGID}" /var/cache/nginx
+    chown -R "${PUID}:${PGID}" /var/log/nginx
+    chown -R "${PUID}:${PGID}" /var/lib/nginx
+    chown -R "${PUID}:${PGID}" /run/nginx/nginx.pid
+    chown -R "${PUID}:${PGID}" /etc/nginx
     echo "Changing owner to $PUID:$PGID, done."
 fi