feat: config portability with generic entity resolver framework

Full configuration export/import system for Homarr with excellent DX:
- Export/import boards, apps, integrations (with re-encrypted secrets),
  users (with bcrypt hashes), groups (with permissions and memberships),
  search engines, and server settings
- Homepage services.yaml import with widget-type mapping
- Generic resolveEntities() utility eliminates per-entity boilerplate
- Declarative entity-fields.ts: adding a new user preference requires
  only one line change (no export/import/schema edits needed)
- User schema uses .catchall(z.unknown()) for forward-compatible prefs
- groupByKey() utility replaces manual Map-building
- CONFIG_ENTITY_KEYS as single source of truth for entity metadata
- Reuse existing entities (apps by name+icon+href, integrations by
  kind+name+url, users by email, groups by name, boards by name)
- Skip duplicates with warnings rather than failing
- Onboarding flow skips user creation step when config includes users
- Reuse existing admin group during onboarding after config import
This commit is contained in:
Thomas Camlong committed 2026-06-06 16:22:59 +02:00
1 parent 1f7b7f0516
commit f6a598b774
48 files changed
+1869 -1435

No files matched your search

+7 -25
View File
@@ -2,9 +2,9 @@ import { TRPCError } from "@trpc/server";
import { z } from "zod/v4";
import {
assessBundleCompatibility,
exportFullConfigAsync,
importFullConfigAsync,
parseAndValidateBundle,
previewExportFullConfigAsync,
previewImportFullConfigAsync,
} from "@homarr/board-portability";
@@ -19,11 +19,7 @@ export const configRouter = createTRPCRouter({
previewImport: permissionRequiredProcedure
.requiresPermission("admin")
.input(
z.object({
content: z.string().min(1),
}),
)
.input(z.object({ content: z.string().min(1) }))
.mutation(async ({ ctx, input }) => {
return await previewImportFullConfigAsync(ctx.db, input.content, packageJson.version);
}),
@@ -34,27 +30,13 @@ export const configRouter = createTRPCRouter({
importFull: permissionRequiredProcedure
.requiresPermission("admin")
.input(
z.object({
content: z.string().min(1),
}),
)
.input(z.object({ content: z.string().min(1) }))
.mutation(async ({ ctx, input }) => {
let parsed: unknown;
try {
parsed = JSON.parse(input.content);
} catch {
throw new TRPCError({ code: "BAD_REQUEST", message: "Invalid JSON" });
const bundle = parseAndValidateBundle(input.content, packageJson.version);
return await importFullConfigAsync(ctx.db, bundle, ctx.session.user.id);
} catch (error) {
throw new TRPCError({ code: "BAD_REQUEST", message: error instanceof Error ? error.message : "Invalid config" });
}
const { bundle, compatibility } = assessBundleCompatibility(parsed, packageJson.version);
if (!bundle || compatibility.status !== "compatible") {
throw new TRPCError({
code: "BAD_REQUEST",
message: compatibility.issues.join(" "),
});
}
return await importFullConfigAsync(ctx.db, bundle, ctx.session.user.id);
}),
});