docs(auth): clarify OIDC credential placeholders

.env.example

@@ -1,22 +1,24 @@
 # Since .env is gitignored, you can use .env.example to build a new `.env` file when you clone the repo.
-# Keep this file up-to-date when you add new variables to \`.env\`.
+# Keep this file up-to-date when you add new variables to `.env`.
 
 # This file will be committed to version control, so make sure not to have any secrets in it.
 # If you are cloning this repo, create a copy of this file named `.env` and populate it with your secrets.
 
-# The below secret is not used anywhere but required for Auth.js (Would encrypt JWTs and Mail hashes, both not used)
-AUTH_SECRET="supersecret"
+# Generate two different 64-character hex values with `openssl rand -hex 32` before starting Homarr.
+# Never reuse these values or commit the populated `.env` file.
+AUTH_SECRET=
 
 # The below secret is used to encrypt integration secrets in the database.
-# It should be a 32-byte string, generated by running `openssl rand -hex 32` on Unix
-# or starting the project without any (which will show a randomly generated one).
-SECRET_ENCRYPTION_KEY=0000000000000000000000000000000000000000000000000000000000000000
+# Homarr will reject an empty or invalid value and print a randomly generated candidate.
+SECRET_ENCRYPTION_KEY=
 
 LOG_LEVEL='info'
 
 # This is how you can use the sqlite driver:
 DB_DRIVER='better-sqlite3'
-DB_URL='FULL_PATH_TO_YOUR_SQLITE_DB_FILE'
+# Safe local source-development path. SQLite files are ignored by Git.
+# Container images use /appdata/db/db.sqlite by default instead.
+DB_URL='./db.sqlite'
 
 # Those are the two ways to use the mysql2 driver:
 # 1. Using the URL format:

apps/docs/docs/advanced/single-sign-on/index.mdx

@@ -244,18 +244,21 @@ Homarr supports multiple authentication options, from internal userbase (credent
         - Create a group (e.g., `homarr-admins`) and assign users who require admin access.
 
         **2. Example .env file:**
+
+        Generate `SECRET_ENCRYPTION_KEY` with `openssl rand -hex 32`; do not copy an example key between installs.
+
         ```env
-        OIDC_CLIENT_ID=identificationid #OIDC client ID
-        OIDC_CLIENT_SECRET=secretsecretsecret #OIDC client secret
+        OIDC_CLIENT_ID=<REPLACE_WITH_OIDC_CLIENT_ID>
+        OIDC_CLIENT_SECRET=<REPLACE_WITH_OIDC_CLIENT_SECRET>
         OIDC_SLUG=homarr #Application slug in Authentik
         AUTH_DOMAIN=auth.example.com #Authentik FQDN
         ADMIN_GROUP=homarr-admins #Authentik group for Homarr admins
         HOMARR_FQDN=homarr.example.com #Homarr FQDN
-        SECRET_ENCRYPTION_KEY=encryptencryptencrypt #Homarr encryption key
+        SECRET_ENCRYPTION_KEY=<REPLACE_WITH_64_HEX_CHARACTERS>
         ```
 
         **3. Example Docker Compose configuration:**
-        ```yaml {14-26}
+        ```yaml {14-24}
         services:
           homarr:
             image: ghcr.io/homarr-labs/homarr:latest
@@ -269,8 +272,6 @@ Homarr supports multiple authentication options, from internal userbase (credent
             environment:
               - TZ=America/Los_Angeles
               - SECRET_ENCRYPTION_KEY=${SECRET_ENCRYPTION_KEY}
-              - BASE_URL=https://${HOMARR_FQDN}
-              - NEXTAUTH_URL=https://${HOMARR_FQDN}
               - AUTH_PROVIDERS=oidc #(optional: include ',credentials' to keep local accounts as fallback)
               - AUTH_OIDC_CLIENT_ID=${OIDC_CLIENT_ID}
               - AUTH_OIDC_CLIENT_SECRET=${OIDC_CLIENT_SECRET}
@@ -322,15 +323,18 @@ Homarr supports multiple authentication options, from internal userbase (credent
         - Record the `Client-ID` and `Client Key` (secret).
 
         **2. Example .env file (Homarr):**
+
+        Generate `SECRET_ENCRYPTION_KEY` with `openssl rand -hex 32`; do not copy an example key between installs.
+
         ```env
-        OIDC_CLIENT_ID=identificationid #Google Client-ID
-        OIDC_CLIENT_SECRET=secretsecretsecret #Google Client Key (secret)
+        OIDC_CLIENT_ID=<REPLACE_WITH_GOOGLE_CLIENT_ID>
+        OIDC_CLIENT_SECRET=<REPLACE_WITH_GOOGLE_CLIENT_SECRET>
         HOMARR_FQDN=homarr.example.com #Homarr FQDN
-        SECRET_ENCRYPTION_KEY=encryptencryptencrypt #Homarr encryption key
+        SECRET_ENCRYPTION_KEY=<REPLACE_WITH_64_HEX_CHARACTERS>
         ```
 
         **3. Example Docker Compose configuration (Homarr):**
-        ```yaml {16-22}
+        ```yaml {14-20}
         services:
           homarr:
             image: ghcr.io/homarr-labs/homarr:latest
@@ -344,8 +348,6 @@ Homarr supports multiple authentication options, from internal userbase (credent
             environment:
               - TZ=Europe/Berlin
               - SECRET_ENCRYPTION_KEY=${SECRET_ENCRYPTION_KEY}
-              - BASE_URL=https://${HOMARR_FQDN}
-              - NEXTAUTH_URL=https://${HOMARR_FQDN}
               - AUTH_PROVIDERS=oidc #(optional: include ',credentials' to keep local accounts as fallback)
               - AUTH_OIDC_CLIENT_ID=${OIDC_CLIENT_ID}
               - AUTH_OIDC_CLIENT_SECRET=${OIDC_CLIENT_SECRET}

apps/docs/docs/getting-started/installation/source.mdx

@@ -38,13 +38,14 @@ This method is only useful, when you want to develop on Homarr or extend it with
     Install all dependencies using <code>pnpm install</code>
   </li>
   <li>
-    Copy the `.env.example` file to `.env` and replace `DB_URL` with the full path you want to use for the sqlite
-    database file. For example `DB_URL='/home/username/homarr/db.sqlite`
+    Copy the `.env.example` file to `.env`. Its `DB_URL='./db.sqlite'` value is ready for local use and stores the
+    database in the cloned repository. Replace it with an absolute writable path such as
+    `DB_URL='/home/username/homarr/db.sqlite'` if you want to store the database elsewhere.
   </li>
   <li>
-    Replace `AUTH_SECRET` and `SECRET_ENCRYPTION_KEY` both with a secure random string by using `openssl rand -hex 32`
+    Run `openssl rand -hex 32` twice and set `AUTH_SECRET` and `SECRET_ENCRYPTION_KEY` to the two different generated
+    values. Keep both values secret and preserve `SECRET_ENCRYPTION_KEY` with your backups.
   </li>
-  <li>Replace `CRON_JOB_API_KEY` with a secure random string by using `openssl rand -base64 32`</li>
   <li>Run `pnpm run db:migration:sqlite:run` and wait that it completes</li>
   <li>Build the source using `pnpm build`</li>
   <li>

apps/docs/docs/integrations/unifi-controller/index.mdx

@@ -16,7 +16,7 @@ import { networkControllerStatusWidget } from "@site/docs/widgets/network-contro
 <IntegrationHeader integration={unifiControllerIntegration} categories={["Network controller"]} />
 
 This integration is using the [node-unifi](https://www.npmjs.com/package/node-unifi) library under the hood to connect to the Unifi Controller.
-Therefore it should support CloudKey Gen1, CloudKey Gen2, UnifiOS-based UDM-Pro controllers as well as self-hosted UniFi controllers.
+Therfore it should support CloudKey Gen1, CloudKey Gen2, UnifiOS-based UDM-Pro controllers as well as self-hosted UniFi controllers.
 
 ### Widgets & Capabilities
 
@@ -28,14 +28,6 @@ Therefore it should support CloudKey Gen1, CloudKey Gen2, UnifiOS-based UDM-Pro
 
 <AddingIntegration />
 
-Use the local HTTPS address of your controller:
-
-- UniFi OS consoles such as Dream Router, Dream Machine, Cloud Gateway, and CloudKey use `https://<host>` (port 443).
-- Self-hosted UniFi Network Servers normally use `https://<host>:8443`.
-- If you omit the port, Homarr tries port 443 first and then port 8443 when the first port cannot be reached.
-
-Use a local administrator account. Cloud-only accounts and accounts with multi-factor authentication are not supported by the underlying client.
-
 ### Secrets
 
 <IntegrationSecrets

packages/integrations/src/unifi-controller/test/unifi-controller-integration.spec.ts

@@ -1,141 +0,0 @@
-import { describe, expect, test, vi } from "vitest";
-
-vi.hoisted(() => {
-  process.env.SKIP_ENV_VALIDATION = "true";
-  process.env.SECRET_ENCRYPTION_KEY = "ff3f4f7ce30e870c9630de9e5d244ffa81101a24ed0dfe5f064beb53a7e684f1";
-  process.env.ENABLE_DNS_CACHING = "false";
-});
-
-const controllerCtor = vi.fn();
-const controllerLogin = vi.fn().mockResolvedValue(true);
-
-vi.mock("@homarr/redis", () => ({
-  createGetSetChannel: () => ({
-    getAsync: vi.fn().mockResolvedValue(null),
-    setAsync: vi.fn().mockResolvedValue(undefined),
-    removeAsync: vi.fn().mockResolvedValue(undefined),
-  }),
-}));
-
-vi.mock("@homarr/core/infrastructure/logs", () => ({
-  createLogger: () => ({ debug: vi.fn(), info: vi.fn(), warn: vi.fn(), error: vi.fn() }),
-  ErrorWithMetadata: class extends Error {},
-}));
-
-vi.mock("@homarr/core/infrastructure/http", () => ({
-  createCustomCheckServerIdentity: () => (() => undefined) as never,
-  fetchWithTrustedCertificatesAsync: vi.fn(),
-  createAxiosCertificateInstanceAsync: vi.fn().mockResolvedValue({}),
-  createCertificateAgentAsync: vi.fn().mockResolvedValue(undefined),
-}));
-
-vi.mock("@homarr/core/infrastructure/certificates", () => ({
-  getTrustedCertificateHostnamesAsync: vi.fn().mockResolvedValue([]),
-  getAllTrustedCertificatesAsync: vi.fn().mockResolvedValue([]),
-}));
-
-vi.mock("axios", () => ({
-  AxiosError: Error,
-  default: {
-    create: vi.fn().mockReturnValue({}),
-  },
-}));
-
-vi.mock("http-cookie-agent/http", () => ({
-  HttpCookieAgent: class {},
-  HttpsCookieAgent: class {},
-}));
-
-vi.mock("@homarr/node-unifi", () => {
-  class FakeController {
-    public options: Record<string, unknown>;
-    constructor(options: Record<string, unknown>) {
-      this.options = options;
-      controllerCtor(options);
-    }
-    public async login(): Promise<true> {
-      return await controllerLogin(this.options.port);
-    }
-    public async getSitesStats(): Promise<unknown[]> {
-      return [];
-    }
-  }
-  return { default: { Controller: FakeController } };
-});
-
-import { UnifiControllerIntegration } from "../unifi-controller-integration";
-
-const createIntegration = (url: string) =>
-  new UnifiControllerIntegration({
-    id: "test-unifi",
-    name: "Test Unifi",
-    url,
-    externalUrl: null,
-    decryptedSecrets: [
-      { kind: "username", value: "admin" },
-      { kind: "password", value: "secret" },
-    ],
-  });
-
-describe("UnifiControllerIntegration port resolution", () => {
-  test("a URL without a port uses the UniFi OS port 443", async () => {
-    controllerCtor.mockClear();
-    controllerLogin.mockClear().mockResolvedValue(true);
-    await createIntegration("http://192.168.1.1").getNetworkSummaryAsync();
-
-    expect(controllerCtor).toHaveBeenCalledTimes(1);
-    expect(controllerCtor).toHaveBeenCalledWith(expect.objectContaining({ host: "192.168.1.1", port: 443 }));
-  });
-
-  test("a connection failure on port 443 falls back to the self-hosted controller port 8443", async () => {
-    controllerCtor.mockClear();
-    controllerLogin
-      .mockClear()
-      .mockRejectedValueOnce(Object.assign(new Error("connect ECONNREFUSED"), { isAxiosError: true }))
-      .mockResolvedValueOnce(true);
-
-    await createIntegration("http://controller.lan").getNetworkSummaryAsync();
-
-    expect(controllerCtor).toHaveBeenNthCalledWith(1, expect.objectContaining({ port: 443 }));
-    expect(controllerCtor).toHaveBeenNthCalledWith(2, expect.objectContaining({ port: 8443 }));
-  });
-
-  test("https://controller.lan:8443 keeps the user-specified port", async () => {
-    controllerCtor.mockClear();
-    controllerLogin.mockClear().mockResolvedValue(true);
-    await createIntegration("https://controller.lan:8443").getNetworkSummaryAsync();
-
-    expect(controllerCtor).toHaveBeenCalledWith(expect.objectContaining({ host: "controller.lan", port: 8443 }));
-  });
-
-  test("https://192.168.1.1:8443 keeps the user-specified port", async () => {
-    controllerCtor.mockClear();
-    controllerLogin.mockClear().mockResolvedValue(true);
-    await createIntegration("https://192.168.1.1:8443").getNetworkSummaryAsync();
-
-    expect(controllerCtor).toHaveBeenCalledWith(expect.objectContaining({ host: "192.168.1.1", port: 8443 }));
-  });
-
-  test("an unusual port like 10443 is honored verbatim", async () => {
-    controllerCtor.mockClear();
-    controllerLogin.mockClear().mockResolvedValue(true);
-    await createIntegration("https://192.168.1.1:10443").getNetworkSummaryAsync();
-
-    expect(controllerCtor).toHaveBeenCalledWith(expect.objectContaining({ host: "192.168.1.1", port: 10443 }));
-  });
-
-  test("an authentication failure on port 443 does not try another port", async () => {
-    controllerCtor.mockClear();
-    controllerLogin.mockClear().mockRejectedValueOnce(
-      Object.assign(new Error("Request failed with status code 401"), {
-        isAxiosError: true,
-        response: { status: 401 },
-      }),
-    );
-
-    await expect(createIntegration("https://controller.lan").getNetworkSummaryAsync()).rejects.toThrow();
-
-    expect(controllerCtor).toHaveBeenCalledTimes(1);
-    expect(controllerCtor).toHaveBeenCalledWith(expect.objectContaining({ port: 443 }));
-  });
-});

packages/integrations/src/unifi-controller/unifi-controller-integration.ts

@@ -2,6 +2,7 @@ import type tls from "node:tls";
 import axios from "axios";
 import { HttpCookieAgent, HttpsCookieAgent } from "http-cookie-agent/http";
 
+import { getPortFromUrl } from "@homarr/common";
 import {
   getAllTrustedCertificatesAsync,
   getTrustedCertificateHostnamesAsync,
@@ -66,53 +67,26 @@ export class UnifiControllerIntegration extends Integration implements NetworkCo
       checkServerIdentity: createCustomCheckServerIdentity(await getTrustedCertificateHostnamesAsync()),
     };
 
-    // node-unifi always connects over HTTPS, regardless of the protocol in the
-    // integration URL. UniFi OS consoles use port 443 while self-hosted controllers normally
-    // use 8443. If no port was provided, try both without hiding authentication errors.
-    const ports = url.port ? [Number(url.port)] : [443, 8443];
-    const createClientForPortAsync = async (port: number) => {
-      const client = new Unifi.Controller({
-        host: url.hostname,
-        port,
-        username: this.getSecretValue("username"),
-        password: this.getSecretValue("password"),
-        createAxiosInstance({ cookies }) {
-          return axios.create({
-            adapter: "http",
-            httpAgent: new HttpCookieAgent({ cookies }),
-            httpsAgent: new HttpsCookieAgent({
-              cookies,
-              requestCert: true,
-              ...certificateOptions,
-            }),
-          });
-        },
-      });
+    const client = new Unifi.Controller({
+      host: url.hostname,
+      port: getPortFromUrl(url),
+      username: this.getSecretValue("username"),
+      password: this.getSecretValue("password"),
+      createAxiosInstance({ cookies }) {
+        return axios.create({
+          adapter: "http",
+          httpAgent: new HttpCookieAgent({ cookies }),
+          httpsAgent: new HttpsCookieAgent({
+            cookies,
+            requestCert: true,
+            ...certificateOptions,
+          }),
+        });
+      },
+    });
 
-      await client.login(this.getSecretValue("username"), this.getSecretValue("password"), null);
-      return client;
-    };
-
-    for (const [index, port] of ports.entries()) {
-      try {
-        return await createClientForPortAsync(port);
-      } catch (error) {
-        const isLastPort = index === ports.length - 1;
-        if (isLastPort || !this.isPortFallbackError(error)) {
-          throw error;
-        }
-      }
-    }
-
-    throw new Error("Unable to connect to the UniFi controller");
-  }
-
-  private isPortFallbackError(error: unknown) {
-    if (typeof error === "object" && error !== null && "isAxiosError" in error && error.isAxiosError === true) {
-      return !("response" in error) || error.response === undefined;
-    }
-
-    return error instanceof Error && error.message === "failed to detect UniFiOS status";
+    await client.login(this.getSecretValue("username"), this.getSecretValue("password"), null);
+    return client;
   }
 
   private getStatusValueOverAllSites<S extends HealthSubsystem>(