Keep existing Nextcloud DAV endpoints intact

.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.
+# The below secret is not used anywhere but required for Auth.js (Would encrypt JWTs and Mail hashes, both not used)
-# Never reuse these values or commit the populated `.env` file.
+AUTH_SECRET="supersecret"
-AUTH_SECRET=
 
 # 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.
+# It should be a 32-byte string, generated by running `openssl rand -hex 32` on Unix
-SECRET_ENCRYPTION_KEY=
+# 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.
+DB_URL='FULL_PATH_TO_YOUR_SQLITE_DB_FILE'
-# 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,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_ID=identificationid #OIDC client ID
-        OIDC_CLIENT_SECRET=<REPLACE_WITH_OIDC_CLIENT_SECRET>
+        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_ID=identificationid #Google Client-ID
-        OIDC_CLIENT_SECRET=<REPLACE_WITH_GOOGLE_CLIENT_SECRET>
+        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
+    Copy the `.env.example` file to `.env` and replace `DB_URL` with the full path you want to use for the sqlite
-    database in the cloned repository. Replace it with an absolute writable path such as
+    database file. For example `DB_URL='/home/username/homarr/db.sqlite`
-    `DB_URL='/home/username/homarr/db.sqlite'` if you want to store the database elsewhere.
   </li>
   <li>
-    Run `openssl rand -hex 32` twice and set `AUTH_SECRET` and `SECRET_ENCRYPTION_KEY` to the two different generated
+    Replace `AUTH_SECRET` and `SECRET_ENCRYPTION_KEY` both with a secure random string by using `openssl rand -hex 32`
-    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>

packages/integrations/src/nextcloud/nextcloud-url.ts

@@ -0,0 +1,13 @@
+export const createNextcloudCalendarServerUrl = (integrationUrl: string) => {
+  const calendarServerUrl = new URL(integrationUrl);
+  const integrationPath = calendarServerUrl.pathname.replace(/\/+$/, "");
+  const davPath = "/remote.php/dav";
+
+  calendarServerUrl.pathname = integrationPath.endsWith(davPath)
+    ? `${integrationPath}/`
+    : `${integrationPath}${davPath}/`;
+  calendarServerUrl.search = "";
+  calendarServerUrl.hash = "";
+
+  return calendarServerUrl.toString();
+};

packages/integrations/src/nextcloud/nextcloud.integration.ts

@@ -21,6 +21,7 @@ import type { ICalendarIntegration } from "../interfaces/calendar/calendar-integ
 import type { CalendarEvent } from "../interfaces/calendar/calendar-types";
 import type { Notification } from "../interfaces/notifications/notification-types";
 import type { INotificationsIntegration } from "../interfaces/notifications/notifications-integration";
+import { createNextcloudCalendarServerUrl } from "./nextcloud-url";
 
 // Register all existing timezones
 if (ICAL.TimezoneService.count === 0) {
@@ -189,7 +190,7 @@ export class NextcloudIntegration extends Integration implements ICalendarIntegr
 
   private async createCalendarClientAsync(agent?: Agent) {
     return new DAVClient({
-      serverUrl: this.integration.url,
+      serverUrl: createNextcloudCalendarServerUrl(this.integration.url),
       credentials: {
         username: this.getSecretValue("username"),
         password: this.getSecretValue("password"),

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

@@ -0,0 +1,38 @@
+import type { Agent } from "node:https";
+import { DAVClient } from "tsdav";
+import { beforeEach, describe, expect, test, vi } from "vitest";
+
+import { NextcloudIntegration } from "../nextcloud.integration";
+
+vi.mock("tsdav", () => ({ DAVClient: vi.fn() }));
+
+interface NextcloudCalendarClientFactory {
+  createCalendarClientAsync(agent: Agent): Promise<unknown>;
+}
+
+describe("NextcloudIntegration", () => {
+  beforeEach(() => {
+    vi.mocked(DAVClient).mockClear();
+  });
+
+  test("uses a calendar server URL that preserves the integration subpath", async () => {
+    const integration = new NextcloudIntegration({
+      id: "integration-id",
+      name: "Nextcloud",
+      url: "https://example.com/nextcloud",
+      externalUrl: null,
+      decryptedSecrets: [
+        { kind: "username", value: "admin" },
+        { kind: "password", value: "password" },
+      ],
+    });
+
+    await (integration as unknown as NextcloudCalendarClientFactory).createCalendarClientAsync({} as Agent);
+
+    expect(DAVClient).toHaveBeenCalledWith(
+      expect.objectContaining({
+        serverUrl: "https://example.com/nextcloud/remote.php/dav/",
+      }),
+    );
+  });
+});

packages/integrations/src/nextcloud/test/nextcloud-url.spec.ts

@@ -0,0 +1,29 @@
+import { describe, expect, test } from "vitest";
+
+import { createNextcloudCalendarServerUrl } from "../nextcloud-url";
+
+describe("createNextcloudCalendarServerUrl", () => {
+  test("uses the DAV endpoint for a root installation", () => {
+    expect(createNextcloudCalendarServerUrl("https://cloud.example.com")).toBe(
+      "https://cloud.example.com/remote.php/dav/",
+    );
+  });
+
+  test("preserves the base path for a subpath installation", () => {
+    expect(createNextcloudCalendarServerUrl("https://example.com/nextcloud")).toBe(
+      "https://example.com/nextcloud/remote.php/dav/",
+    );
+  });
+
+  test("does not duplicate a trailing slash", () => {
+    expect(createNextcloudCalendarServerUrl("https://example.com/nextcloud/")).toBe(
+      "https://example.com/nextcloud/remote.php/dav/",
+    );
+  });
+
+  test("does not duplicate an existing DAV endpoint", () => {
+    expect(createNextcloudCalendarServerUrl("https://example.com/nextcloud/remote.php/dav")).toBe(
+      "https://example.com/nextcloud/remote.php/dav/",
+    );
+  });
+});