docs(unifi): resolve review leftovers

The node-unifi library hardcodes https:// in its base URL and the
Unifi controller API only speaks HTTPS. When a user adds the
integration with a bare http:// or https:// URL, getPortFromUrl
returned 80 or 443, and the library attempted a TLS handshake on
the wrong port. The server's plain HTTP response caused
'EPROTO ... wrong version number'.

Derive the port from the user's explicit port, or fall back to 8443
(the integration's defaultPort). Closes #6207.

.env.example

@@ -1,24 +1,22 @@
 # 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.
 
-# 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 not used anywhere but required for Auth.js (Would encrypt JWTs and Mail hashes, both not used)
+AUTH_SECRET="supersecret"
 
 # The below secret is used to encrypt integration secrets in the database.
-# Homarr will reject an empty or invalid value and print a randomly generated candidate.
-SECRET_ENCRYPTION_KEY=
+# 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
 
 LOG_LEVEL='info'
 
 # This is how you can use the sqlite driver:
 DB_DRIVER='better-sqlite3'
-# 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'
+DB_URL='FULL_PATH_TO_YOUR_SQLITE_DB_FILE'
 
 # 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,21 +244,18 @@ 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=<REPLACE_WITH_OIDC_CLIENT_ID>
-        OIDC_CLIENT_SECRET=<REPLACE_WITH_OIDC_CLIENT_SECRET>
+        OIDC_CLIENT_ID=identificationid #OIDC client ID
+        OIDC_CLIENT_SECRET=secretsecretsecret #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=<REPLACE_WITH_64_HEX_CHARACTERS>
+        SECRET_ENCRYPTION_KEY=encryptencryptencrypt #Homarr encryption key
         ```
 
         **3. Example Docker Compose configuration:**
-        ```yaml {14-24}
+        ```yaml {14-26}
         services:
           homarr:
             image: ghcr.io/homarr-labs/homarr:latest
@@ -272,6 +269,8 @@ 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}
@@ -323,18 +322,15 @@ 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=<REPLACE_WITH_GOOGLE_CLIENT_ID>
-        OIDC_CLIENT_SECRET=<REPLACE_WITH_GOOGLE_CLIENT_SECRET>
+        OIDC_CLIENT_ID=identificationid #Google Client-ID
+        OIDC_CLIENT_SECRET=secretsecretsecret #Google Client Key (secret)
         HOMARR_FQDN=homarr.example.com #Homarr FQDN
-        SECRET_ENCRYPTION_KEY=<REPLACE_WITH_64_HEX_CHARACTERS>
+        SECRET_ENCRYPTION_KEY=encryptencryptencrypt #Homarr encryption key
         ```
 
         **3. Example Docker Compose configuration (Homarr):**
-        ```yaml {14-20}
+        ```yaml {16-22}
         services:
           homarr:
             image: ghcr.io/homarr-labs/homarr:latest
@@ -348,6 +344,8 @@ 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,14 +38,13 @@ 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`. 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.
+    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`
   </li>
   <li>
-    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.
+    Replace `AUTH_SECRET` and `SECRET_ENCRYPTION_KEY` both with a secure random string by using `openssl rand -hex 32`
   </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.
-Therfore it should support CloudKey Gen1, CloudKey Gen2, UnifiOS-based UDM-Pro controllers as well as self-hosted UniFi controllers.
+Therefore it should support CloudKey Gen1, CloudKey Gen2, UnifiOS-based UDM-Pro controllers as well as self-hosted UniFi controllers.
 
 ### Widgets & Capabilities
 
@@ -28,6 +28,14 @@ Therfore it should support CloudKey Gen1, CloudKey Gen2, UnifiOS-based UDM-Pro c
 
 <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

@@ -0,0 +1,141 @@
+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,7 +2,6 @@ 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,
@@ -67,26 +66,53 @@ export class UnifiControllerIntegration extends Integration implements NetworkCo
       checkServerIdentity: createCustomCheckServerIdentity(await getTrustedCertificateHostnamesAsync()),
     };
 
-    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,
-          }),
-        });
-      },
-    });
+    // 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,
+            }),
+          });
+        },
+      });
 
-    await client.login(this.getSecretValue("username"), this.getSecretValue("password"), null);
-    return client;
+      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";
   }
 
   private getStatusValueOverAllSites<S extends HealthSubsystem>(