docs: simplify v2 backup guidance

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

@@ -0,0 +1,74 @@
+---
+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/integrations/src/nextcloud/nextcloud-url.ts

@@ -1,13 +0,0 @@
-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,7 +21,6 @@ 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) {
@@ -190,7 +189,7 @@ export class NextcloudIntegration extends Integration implements ICalendarIntegr
 
   private async createCalendarClientAsync(agent?: Agent) {
     return new DAVClient({
-      serverUrl: createNextcloudCalendarServerUrl(this.integration.url),
+      serverUrl: this.integration.url,
       credentials: {
         username: this.getSecretValue("username"),
         password: this.getSecretValue("password"),

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

@@ -1,38 +0,0 @@
-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

@@ -1,29 +0,0 @@
-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/",
-    );
-  });
-});