docs: simplify v2 backup guidance

.env.example

@@ -58,8 +58,8 @@ TURBO_TELEMETRY_DISABLED=1
 # Enable kubernetes tool
 # ENABLE_KUBERNETES=true
 
-# Enable the development-only mock integration. Never enable this in production.
-# UNSAFE_ENABLE_MOCK_INTEGRATION=true
+# Enable mock integration
+UNSAFE_ENABLE_MOCK_INTEGRATION=true
 
 # Public URL contract. Values must be absolute HTTP(S) URLs without credentials,
 # query strings, or fragments. Trailing slashes are normalized at startup.

apps/docs/docs/advanced/environment-variables/index.mdx

@@ -133,10 +133,9 @@ External redis is currently not supported with Proxmox Community Scripts
 The advanced deployments environment variables should only be used if you know what you are doing.
 :::
 
-| Environment Variable             | Description                                                                                                    | Default |
-| -------------------------------- | -------------------------------------------------------------------------------------------------------------- | ------- |
-| `DB_MIGRATIONS_DISABLED`         | Disable database migrations. For example, when migrations are managed separately in Helm deployments.          | `false` |
-| `UNSAFE_ENABLE_MOCK_INTEGRATION` | Enable the development-only Mock integration. This exposes fabricated data and must not be used in production. | `false` |
+| Environment Variable     | Description                                         |
+| ------------------------ | --------------------------------------------------- |
+| `DB_MIGRATIONS_DISABLED` | Disable db migrations. For example for helm charts. |
 
 All public URL variables reject non-HTTP protocols, embedded credentials, query strings, and fragments, and normalize
 trailing slashes when Homarr or Docusaurus starts.

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.

apps/nextjs/src/app/[locale]/manage/integrations/new/page.tsx

@@ -47,9 +47,6 @@ export default async function IntegrationsNewPage(props: NewIntegrationPageProps
   const tCreate = await getI18n("integration.page.create");
 
   const currentKind = result.data;
-  if (currentKind === "mock" && !env.UNSAFE_ENABLE_MOCK_INTEGRATION) {
-    notFound();
-  }
 
   return (
     <>

packages/api/src/env.ts

@@ -19,7 +19,6 @@ const publicHttpUrl = (variableName: string) =>
 export const env = createEnv({
   server: {
     KUBERNETES_SERVICE_ACCOUNT_NAME: z.string().optional(),
-    UNSAFE_ENABLE_MOCK_INTEGRATION: createBooleanSchema(false),
     DEMO_MODE: createBooleanSchema(false),
     DEMO_READ_ONLY: createBooleanSchema(true),
     HOMARR_WEBSITE_URL: publicHttpUrl("HOMARR_WEBSITE_URL").default("https://homarr.dev"),
@@ -28,7 +27,6 @@ export const env = createEnv({
   },
   runtimeEnv: {
     KUBERNETES_SERVICE_ACCOUNT_NAME: process.env.KUBERNETES_SERVICE_ACCOUNT_NAME,
-    UNSAFE_ENABLE_MOCK_INTEGRATION: process.env.UNSAFE_ENABLE_MOCK_INTEGRATION,
     DEMO_MODE: process.env.DEMO_MODE,
     DEMO_READ_ONLY: process.env.DEMO_READ_ONLY,
     HOMARR_WEBSITE_URL: process.env.HOMARR_WEBSITE_URL,

packages/api/src/router/integration/integration-router.ts

@@ -18,12 +18,7 @@ import {
   integrationSecrets,
   integrationUserPermissions,
 } from "@homarr/db/schema";
-import type {
-  GroupPermissionKey,
-  IntegrationKind,
-  IntegrationPermission,
-  IntegrationSecretKind,
-} from "@homarr/definitions";
+import type { GroupPermissionKey, IntegrationPermission, IntegrationSecretKind } from "@homarr/definitions";
 import {
   getIntegrationKindsByCategory,
   getPermissionsWithParents,
@@ -44,7 +39,6 @@ import {
 } from "@homarr/validation/integration";
 import { mediaRequestOptionsSchema, mediaRequestRequestSchema } from "@homarr/validation/widgets/media-request";
 
-import { env } from "../../env";
 import { createOneIntegrationMiddleware } from "../../middlewares/integration";
 import { createTRPCRouter, permissionRequiredProcedure, protectedProcedure, publicProcedure } from "../../trpc";
 import { throwIfActionForbiddenAsync } from "./integration-access";
@@ -54,15 +48,6 @@ import { mapTestConnectionError } from "./map-test-connection-error";
 const logger = createLogger({ module: "integrationRouter" });
 const mediaRequestSearchKinds = getIntegrationKindsByCategory("mediaSearch");
 
-const throwIfMockIntegrationIsDisabled = (kind: IntegrationKind) => {
-  if (kind !== "mock" || env.UNSAFE_ENABLE_MOCK_INTEGRATION) return;
-
-  throw new TRPCError({
-    code: "FORBIDDEN",
-    message: "Mock integrations are disabled",
-  });
-};
-
 export const integrationRouter = createTRPCRouter({
   getKinds: publicProcedure
     .meta({
@@ -73,14 +58,12 @@ export const integrationRouter = createTRPCRouter({
       },
     })
     .query(() => {
-      return objectEntries(integrationDefs)
-        .filter(([kind]) => kind !== "mock" || env.UNSAFE_ENABLE_MOCK_INTEGRATION)
-        .map(([kind, def]) => ({
-          kind,
-          name: def.name,
-          category: def.category,
-          requiredSecrets: def.secretKinds,
-        }));
+      return objectEntries(integrationDefs).map(([kind, def]) => ({
+        kind,
+        name: def.name,
+        category: def.category,
+        requiredSecrets: def.secretKinds,
+      }));
     }),
   all: protectedProcedure
     .meta({
@@ -246,8 +229,6 @@ export const integrationRouter = createTRPCRouter({
     })
     .input(integrationCreateSchema)
     .mutation(async ({ ctx, input }) => {
-      throwIfMockIntegrationIsDisabled(input.kind);
-
       logger.info("Creating integration", {
         name: input.name,
         kind: input.kind,

packages/api/src/router/onboard/onboard-router.ts

@@ -321,13 +321,6 @@ export const onboardRouter = createTRPCRouter({
     .requiresStep("setup")
     .input(onboardingCompleteSetupSchema)
     .mutation(async ({ ctx, input }) => {
-      if (
-        !env.UNSAFE_ENABLE_MOCK_INTEGRATION &&
-        input.integrations.some((integration) => integration.kind === "mock")
-      ) {
-        throw new TRPCError({ code: "FORBIDDEN", message: "Mock integrations are disabled" });
-      }
-
       const boardList = await ctx.db.query.boards.findMany({
         with: {
           sections: { with: { layouts: true } },