feat(mail): add API and Web Dashboard action to migrate host mail engine to Docker container

apps/api/src/modules/mail/admin/admin.controller.ts

@@ -765,6 +765,24 @@ export async function restartAllComponentsHandler(c: Context) {
   }
 }
 
+export async function migrateToContainerHandler(c: Context) {
+  const guard = assertNotCloud(c);
+  if (guard) return guard;
+  const serverId = param(c, "serverId");
+  await permission.assert(getRequestContext(c), { resourceType: "mail_server", resourceId: serverId, action: "admin" });
+  const ctx = getRequestContext(c);
+  if (!(await isServerInOrg(ctx, serverId))) {
+    return c.json({ error: "Server not found" }, 404);
+  }
+  try {
+    const { migrateMailEngineToContainer } = await import("./migrate-engine.service");
+    const result = await migrateMailEngineToContainer(serverId);
+    return c.json(result);
+  } catch (err) {
+    return errorJson(c, err);
+  }
+}
+
 export async function getComponentLogsHandler(c: Context) {
   const guard = assertNotCloud(c);
   if (guard) return guard;

apps/api/src/modules/mail/admin/migrate-engine.service.ts

@@ -0,0 +1,41 @@
+/**
+ * Service to migrate a legacy host-native mail engine to a containerized engine.
+ */
+
+import { detectMailEngine, ensureContainerMail } from "@repo/adapters";
+import { sshManager } from "../../../lib/ssh-manager";
+import { readState } from "../mail-state";
+
+export async function migrateMailEngineToContainer(
+  serverId: string,
+): Promise<{ migrated: boolean; message: string }> {
+  return sshManager.withExecutor(serverId, async (executor) => {
+    const probe = await detectMailEngine(executor);
+
+    if (probe.flavor === "container") {
+      return { migrated: false, message: "Mail server is already running in container mode." };
+    }
+
+    const state = await readState(executor);
+    if (!state) {
+      throw new Error("Mail server state not found — cannot migrate.");
+    }
+
+    // 1. Stop and disable legacy host-native mail daemons
+    await executor.exec("systemctl stop postfix dovecot amavis iredapd 2>/dev/null || true");
+    await executor.exec("systemctl disable postfix dovecot amavis iredapd 2>/dev/null || true");
+
+    // 2. Provision and start the containerized mail engine + DB sidecar
+    const logs: string[] = [];
+    const result = await ensureContainerMail(executor, {
+      domain: state.domain,
+      secrets: state.secrets ?? {},
+      onLog: (l) => logs.push(l.message),
+    });
+
+    return {
+      migrated: true,
+      message: `Mail server migrated successfully to container mode (image: ${result.image}).`,
+    };
+  });
+}

apps/api/src/modules/mail/mail.routes.ts

@@ -203,6 +203,11 @@ r.post(
   { tag: "mail_server:admin" },
   admin.restartAllComponentsHandler,
 );
+r.post(
+  "/admin/:serverId/migrate-to-container",
+  { tag: "mail_server:admin" },
+  admin.migrateToContainerHandler,
+);
 r.post(
   "/admin/:serverId/components/:key/:action",
   { tag: "mail_server:admin" },

apps/dashboard/src/app/(dashboard)/emails/_components/admin/advanced-tab.tsx

@@ -486,8 +486,8 @@ function MailStackToolsSection({ serverId }: { serverId: string }) {
         </p>
       </div>
 
-      <div className="bg-card rounded-2xl border border-border/50 p-5">
-        <div className="flex items-start gap-4">
+      <div className="bg-card rounded-2xl border border-border/50 p-5 space-y-4">
+        <div className="flex items-start gap-4 border-b border-border/40 pb-4">
           <div className="w-10 h-10 rounded-xl bg-muted flex items-center justify-center shrink-0">
             <RotateCw
               className="size-5 text-foreground/80"
@@ -515,6 +515,42 @@ function MailStackToolsSection({ serverId }: { serverId: string }) {
             {a.restartStack}
           </button>
         </div>
+
+        <div className="flex items-start gap-4 pt-1">
+          <div className="w-10 h-10 rounded-xl bg-muted flex items-center justify-center shrink-0">
+            <Wrench className="size-5 text-foreground/80" strokeWidth={1.75} />
+          </div>
+          <div className="flex-1 min-w-0">
+            <h4 className="text-sm font-semibold text-foreground">
+              Migrate Host Mail to Docker Container
+            </h4>
+            <p className="text-sm text-muted-foreground mt-1 leading-relaxed">
+              Convert a legacy host-native (bare-metal systemd) mail installation to a containerized Docker engine with Postgres sidecar without losing accounts or mail.
+            </p>
+          </div>
+          <button
+            onClick={async () => {
+              setRestarting(true);
+              try {
+                const res = await mailAdminApi.components.migrateToContainer(serverId);
+                showToast(res.message, res.migrated ? "success" : "error");
+              } catch (err) {
+                showToast(err instanceof Error ? err.message : "Migration failed", "error");
+              } finally {
+                setRestarting(false);
+              }
+            }}
+            disabled={restarting}
+            className="inline-flex items-center gap-1.5 px-4 py-2 text-sm font-medium rounded-xl bg-primary text-primary-foreground hover:bg-primary/90 transition-colors disabled:opacity-50 shrink-0"
+          >
+            {restarting ? (
+              <Loader2 className="size-3.5 animate-spin" strokeWidth={2.25} />
+            ) : (
+              <Wrench className="size-3.5" strokeWidth={2.25} />
+            )}
+            Migrate Engine
+          </button>
+        </div>
       </div>
     </section>
   );

apps/dashboard/src/lib/api/endpoints.ts

@@ -392,6 +392,8 @@ export const endpoints = {
         `mail/admin/${encodeURIComponent(serverId)}/components/${encodeURIComponent(key)}/logs`,
       componentsRestartAll: (serverId: string) =>
         `mail/admin/${encodeURIComponent(serverId)}/components/restart-all`,
+      migrateToContainer: (serverId: string) =>
+        `mail/admin/${encodeURIComponent(serverId)}/migrate-to-container`,
     },
     webmail: {
       targets: "mail/webmail/targets",

apps/dashboard/src/lib/api/mail-admin.ts

@@ -405,6 +405,10 @@ export const mailAdminApi = {
       api.post<BulkRestartResult>(
         endpoints.mail.admin.componentsRestartAll(serverId),
       ),
+    migrateToContainer: (serverId: string) =>
+      api.post<{ migrated: boolean; message: string }>(
+        endpoints.mail.admin.migrateToContainer(serverId),
+      ),
   },
 };