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.

pnpm-lock.yaml

@@ -25,11 +25,11 @@ catalogs:
       specifier: 0.14.9
       version: 0.14.9
     '@auth/core':
-      specifier: ^0.41.3
+      specifier: ^0.41.2
-      version: 0.41.3
+      version: 0.41.2
     '@auth/drizzle-adapter':
-      specifier: ^1.11.3
+      specifier: ^1.11.2
-      version: 1.11.3
+      version: 1.11.2
     '@babel/parser':
       specifier: ^7.29.7
       version: 7.29.7
@@ -520,8 +520,8 @@ catalogs:
       specifier: 16.3.1
       version: 16.3.1
     next-auth:
-      specifier: 5.0.0-beta.32
+      specifier: 5.0.0-beta.31
-      version: 5.0.0-beta.32
+      version: 5.0.0-beta.31
     next-intl:
       specifier: 4.13.1
       version: 4.13.1
@@ -1587,10 +1587,10 @@ importers:
     dependencies:
       '@auth/core':
         specifier: 'catalog:'
-        version: 0.41.3
+        version: 0.41.2
       '@auth/drizzle-adapter':
         specifier: 'catalog:'
-        version: 1.11.3
+        version: 1.11.2
       '@homarr/common':
         specifier: workspace:^0.1.0
         version: link:../common
@@ -1620,7 +1620,7 @@ importers:
         version: 16.3.1(@babel/core@7.29.0(supports-color@10.2.2))(@opentelemetry/api@1.9.0)(@playwright/test@1.61.1)(@types/node@24.13.3)(babel-plugin-react-compiler@1.0.0)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)(sass@1.101.0)
       next-auth:
         specifier: 'catalog:'
-        version: 5.0.0-beta.32(next@16.3.1(@babel/core@7.29.0(supports-color@10.2.2))(@opentelemetry/api@1.9.0)(@playwright/test@1.61.1)(@types/node@24.13.3)(babel-plugin-react-compiler@1.0.0)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)(sass@1.101.0))(react@19.2.7)
+        version: 5.0.0-beta.31(next@16.3.1(@babel/core@7.29.0(supports-color@10.2.2))(@opentelemetry/api@1.9.0)(@playwright/test@1.61.1)(@types/node@24.13.3)(babel-plugin-react-compiler@1.0.0)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)(sass@1.101.0))(react@19.2.7)
       react:
         specifier: 'catalog:'
         version: 19.2.7
@@ -1989,7 +1989,7 @@ importers:
     dependencies:
       '@auth/core':
         specifier: 'catalog:'
-        version: 0.41.3
+        version: 0.41.2
       '@homarr/common':
         specifier: workspace:^0.1.0
         version: link:../common
@@ -3346,12 +3346,12 @@ packages:
       react:
         optional: true
 
-  '@auth/core@0.41.3':
+  '@auth/core@0.41.2':
-    resolution: {integrity: sha512-sJ3JMHHkXMD3aOjopv7mOBTO1Ocw4b0fAEXJBz6k7YHLpYQI6C40jCUPc5fNvUKxXRXNE1/sRISA15UrwWJBTw==}
+    resolution: {integrity: sha512-Hx5MNBxN2fJTbJKGUKAA0wca43D0Akl3TvufY54Gn8lop7F+34vU1zA1pn0vQfIoVuLIrpfc2nkyjwIaPJMW7w==}
     peerDependencies:
       '@simplewebauthn/browser': ^9.0.1
       '@simplewebauthn/server': ^9.0.2
-      nodemailer: ^7.0.7 || ^8.0.5
+      nodemailer: ^7.0.7
     peerDependenciesMeta:
       '@simplewebauthn/browser':
         optional: true
@@ -3360,8 +3360,8 @@ packages:
       nodemailer:
         optional: true
 
-  '@auth/drizzle-adapter@1.11.3':
+  '@auth/drizzle-adapter@1.11.2':
-    resolution: {integrity: sha512-TxqVasPVuf7LDAT1Yuu6bftpuet8o0tjdXW+mXpnXWdSRPQsomdzMoz9RsXkFN/JfdK+/DwdgOEmOTv1gbiFNw==}
+    resolution: {integrity: sha512-VOuj7REI8jfJjpSbsYwDM/Zrn55T6lS9Yc+29V+EXMcel8eqG7x+7LodNfd1WHjakfkLYi+qsbYUHB3E6aDA4w==}
 
   '@babel/code-frame@7.29.0':
     resolution: {integrity: sha512-9NhCeYjq9+3uxgdtp20LSiJXJvN0FeCtNGpJxuMFZ1Kv3cWUNb6DOhJwUvcVCzKGR66cw4njwM6hrJLqgOwbcw==}
@@ -13685,13 +13685,13 @@ packages:
   neverpanic@0.0.8:
     resolution: {integrity: sha512-vVdkelrLxaow/fdWDumzNBO+jwm6X8bxeLJc34THtpj70u0C5QBkcV6CRCu2X726km7XD45N0A3QtYCla4RvKw==}
 
-  next-auth@5.0.0-beta.32:
+  next-auth@5.0.0-beta.31:
-    resolution: {integrity: sha512-CGlChIEWZ6LltNVxrE5yiySMID+Idpmry47JYA5lLwgD8Sx02a8M65VL0TWVz9nbnOioS/tCW/rP/0+mE7Qp4Q==}
+    resolution: {integrity: sha512-1OBgCKPzo+S7UWWMp3xgvGvIJ0OpV7B3vR4ZDRqD9a4Ch+OT6dakLXG9ivhtmIWVa71nTSXattOHyCg8sNi8/Q==}
     peerDependencies:
       '@simplewebauthn/browser': ^9.0.1
       '@simplewebauthn/server': ^9.0.2
       next: ^14.0.0-0 || ^15.0.0 || ^16.0.0
-      nodemailer: ^7.0.7 || ^8.0.5
+      nodemailer: ^7.0.7
       react: ^18.2.0 || ^19.0.0
     peerDependenciesMeta:
       '@simplewebauthn/browser':
@@ -17439,7 +17439,7 @@ snapshots:
       '@types/react': 19.2.17
       react: 19.2.7
 
-  '@auth/core@0.41.3':
+  '@auth/core@0.41.2':
     dependencies:
       '@panva/hkdf': 1.2.1
       jose: 6.2.3
@@ -17447,9 +17447,9 @@ snapshots:
       preact: 10.24.3
       preact-render-to-string: 6.5.11(preact@10.24.3)
 
-  '@auth/drizzle-adapter@1.11.3':
+  '@auth/drizzle-adapter@1.11.2':
     dependencies:
-      '@auth/core': 0.41.3
+      '@auth/core': 0.41.2
     transitivePeerDependencies:
       - '@simplewebauthn/browser'
       - '@simplewebauthn/server'
@@ -30001,9 +30001,9 @@ snapshots:
 
   neverpanic@0.0.8: {}
 
-  next-auth@5.0.0-beta.32(next@16.3.1(@babel/core@7.29.0(supports-color@10.2.2))(@opentelemetry/api@1.9.0)(@playwright/test@1.61.1)(@types/node@24.13.3)(babel-plugin-react-compiler@1.0.0)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)(sass@1.101.0))(react@19.2.7):
+  next-auth@5.0.0-beta.31(next@16.3.1(@babel/core@7.29.0(supports-color@10.2.2))(@opentelemetry/api@1.9.0)(@playwright/test@1.61.1)(@types/node@24.13.3)(babel-plugin-react-compiler@1.0.0)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)(sass@1.101.0))(react@19.2.7):
     dependencies:
-      '@auth/core': 0.41.3
+      '@auth/core': 0.41.2
       next: 16.3.1(@babel/core@7.29.0(supports-color@10.2.2))(@opentelemetry/api@1.9.0)(@playwright/test@1.61.1)(@types/node@24.13.3)(babel-plugin-react-compiler@1.0.0)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)(sass@1.101.0)
       react: 19.2.7
 

pnpm-workspace.yaml

@@ -14,8 +14,8 @@ catalog:
   "@codemirror/state": ^6.6.0
   "@codemirror/theme-one-dark": ^6.1.3
   "@codemirror/view": ^6.43.0
-  "@auth/core": ^0.41.3
+  "@auth/core": ^0.41.2
-  "@auth/drizzle-adapter": ^1.11.3
+  "@auth/drizzle-adapter": ^1.11.2
   "@ctrl/deluge": ^8.0.0
   "@ctrl/qbittorrent": ^9.14.0
   "@ctrl/transmission": ^7.4.0
@@ -174,7 +174,7 @@ catalog:
   maria2: ^0.4.1
   mysql2: 3.22.6
   next: 16.3.1
-  next-auth: 5.0.0-beta.32
+  next-auth: 5.0.0-beta.31
   next-intl: 4.13.1
   next-themes: ^0.4.6
   node-loader: ^2.1.0