Add DirectAdmin migration blueprint

docs/architecture/directadmin-migration-blueprint.md

@@ -0,0 +1,277 @@
+# DirectAdmin Migration Blueprint
+
+This blueprint describes how Jabali Panel should migrate accounts from a remote
+DirectAdmin server into Jabali.
+
+It is written to match Jabali's current architecture:
+- Laravel 12 + Filament v5 + Livewire v4 UI.
+- Privileged agent (`bin/jabali-agent`) for root-level operations.
+- Long-running work via jobs/queue with resumable logs.
+
+## Goals
+
+- Support connecting to a remote DirectAdmin server (host, port, credentials).
+- Support multi-account migrations (admin-initiated).
+- Support user self-migration (user-initiated, scoped to their Jabali account).
+- Migrate websites, databases, email, and SSL.
+- Provide clear progress, per-account logs, and safe retries.
+
+## Non-Goals (Initial Scope)
+
+- Reseller plans and quota mapping (can be added later).
+- DNS zone migrations from DirectAdmin (optional later).
+- Password migration for website logins and mailboxes (not possible in general).
+
+## UX Overview
+
+Jabali already has:
+- Admin migration entry: `jabali-admin/migration` (tabs page).
+- User migration entry: `jabali-panel/cpanel-migration` (cPanel only today).
+
+DirectAdmin migration should be added to both panels:
+- Admin: new migration tab alongside cPanel and WHM.
+- User: new self-migration page similar to user cPanel migration.
+
+The UI should use Filament native components (Wizard, Sections, Tables), and
+should not embed custom HTML/CSS.
+
+## Admin Flow (Multi-Account)
+
+### Step 1: Connect
+
+Inputs:
+- Hostname or IP
+- Port (default DirectAdmin: 2222)
+- Auth:
+  - Username + password (initial)
+  - Optional future: API token
+- SSL verify toggle (default on, allow off for lab servers)
+
+Actions:
+- Test connection
+- Discover users/accounts
+
+Output:
+- Server metadata (DirectAdmin version if available)
+- Discovered accounts summary
+
+### Step 2: Select Accounts
+
+Show a table of discovered accounts:
+- Source username
+- Main domain
+- Email contact
+- Disk usage (if provided)
+
+Selection:
+- Multi-select accounts for import.
+
+Per-account mapping:
+- Target Jabali username (editable, default = source username)
+- Target user email (editable)
+- Conflict indicators (existing Jabali user, existing domains)
+
+### Step 3: Choose What To Import
+
+Toggles:
+- Files
+- Databases
+- Email
+- SSL
+
+Optional safety toggles:
+- Skip existing domains
+- Skip existing databases
+- Re-issue SSL via Let's Encrypt when custom SSL is missing or invalid
+
+### Step 4: Run Migration
+
+Execution runs as a background job batch:
+- Per-account status: pending, running, completed, failed, skipped.
+- Per-account logs (timestamps + messages).
+- Global log for the import job.
+
+Controls:
+- Cancel import (best-effort stop at safe boundaries).
+- Retry failed accounts.
+
+## User Flow (Self-Migration)
+
+User self-migration is a guided flow to import a single DirectAdmin account into
+the currently authenticated Jabali user.
+
+### Step 1: Connect
+
+Inputs:
+- DirectAdmin hostname/IP and port
+- DirectAdmin username + password
+
+Actions:
+- Test connection
+- Verify the DirectAdmin user is accessible
+
+### Step 2: Choose What To Import
+
+Toggles:
+- Files
+- Databases
+- Email
+- SSL
+
+### Step 3: Run Migration
+
+Show:
+- Live progress
+- Logs
+- Final summary
+
+Scope and enforcement:
+- Target Jabali user is fixed to the authenticated user.
+- Import must refuse to touch domains that do not belong to the user.
+
+## Data Model (Proposed)
+
+Jabali already has:
+- `server_imports` and `server_import_accounts`.
+
+To support DirectAdmin remote migration properly, add:
+- `server_imports.created_by_user_id` (nullable, for admin-created vs user-created).
+- `server_imports.target_user_id` (nullable, for admin selecting a target user, optional).
+- `server_import_accounts.backup_path` (nullable, per-account backup archive path when remote).
+- `server_import_accounts.ssl_items` (json, optional, discovered SSL material per domain).
+- `server_import_accounts.mail_items` (json, optional, discovered mailboxes and domains).
+
+Also update `server_imports.import_options` to include:
+- `files`, `databases`, `emails`, `ssl`.
+
+## Import Pipeline (High-Level)
+
+### Phase A: Discovery
+
+Purpose:
+- Validate credentials and enumerate accounts to import.
+
+Implementation notes:
+- Jabali agent already supports discovery for DirectAdmin remote via:
+  - `CMD_API_SHOW_ALL_USERS`
+  - `CMD_API_SHOW_USER_CONFIG`
+
+### Phase B: Backup Creation and Download (Remote Method)
+
+Problem:
+- The current import processor only imports from local backup archives.
+
+Solution:
+- For `import_method=remote_server`, create and download a DirectAdmin backup
+  per selected account to `storage/app/private/imports/...`.
+
+Implementation choices:
+- Run this phase in a queued job to avoid request timeouts.
+- Download must stream to disk, not to memory.
+- Store paths per account (`server_import_accounts.backup_path`).
+
+### Phase C: Analyze Backup (Optional But Recommended)
+
+Purpose:
+- Extract account metadata (domains, DB dumps, email list, SSL presence).
+- Show a preview before the destructive restore phase.
+
+Implementation notes:
+- Reuse the existing agent discovery for backup files (`import.discover`).
+- Extend discovery to detect:
+  - Mailbox domains and mailbox names
+  - SSL certificate files per domain (if present)
+
+### Phase D: Restore Into Jabali
+
+For each account:
+1. Create or map Jabali user.
+2. Create domains.
+3. Restore website files into the correct document roots.
+4. Restore databases and import dumps.
+5. Restore email domains and mailboxes, then copy Maildir data.
+6. Restore SSL certificates (or issue Let's Encrypt if configured).
+
+All steps must write logs to both:
+- `server_imports.import_log`
+- `server_import_accounts.import_log`
+
+## Email Migration (Requirements)
+
+Minimum requirements:
+- Create mail domains in Jabali for the migrated domains.
+- Create mailboxes for the discovered mailbox usernames.
+- Import Maildir content (messages, folders) into the new mailboxes.
+
+Recommended approach:
+- Use Jabali agent functions:
+  - `email.enable_domain`
+  - `email.mailbox_create`
+  - `email.sync_maps` and `email.reload_services` when needed
+
+Notes:
+- DirectAdmin backups can include hashed mailbox passwords, which are not
+  directly reusable for Dovecot. Use new random passwords and provide a
+  "reset passwords" output list to the admin or user.
+
+## SSL Migration (Requirements)
+
+Minimum requirements:
+- If custom SSL material is present in the DirectAdmin backup, install it for
+  each domain in Jabali.
+
+Recommended approach:
+- Extract PEM certificate, private key, and optional chain from the backup.
+- Use Jabali agent function `ssl.install` per domain.
+
+Fallback:
+- If SSL material is missing or invalid, allow issuing Let's Encrypt via
+  `ssl.issue` after DNS and vhost are ready.
+
+## Multi-Account Support
+
+Admin migration must allow selecting multiple DirectAdmin users and migrating
+them in one batch.
+
+Execution model:
+- One `server_imports` record per batch.
+- One `server_import_accounts` record per DirectAdmin user.
+- Independent status and retry per account.
+
+## Security and Compliance
+
+- Store remote passwords and tokens encrypted at rest (already supported for
+  `server_imports.remote_password` and `server_imports.remote_api_token`).
+- Never write raw credentials into logs.
+- Provide a "forget credentials" action after the migration completes.
+- Rate-limit connection tests and discovery to reduce abuse.
+
+## Observability
+
+- Show per-account progress and current step in the UI.
+- Write a compact global log and a detailed per-account log.
+- On failures, capture enough context to troubleshoot:
+  - Which step failed
+  - The relevant domain or database name
+  - A short error string without secrets
+
+## Implementation Phases (Suggested)
+
+Phase 1:
+- Admin: add DirectAdmin migration tab (UI skeleton).
+- User: add DirectAdmin self-migration page (UI skeleton).
+- Wire UI to the existing `server_imports` discovery (remote and backup-file).
+
+Phase 2:
+- Implement remote backup creation and download.
+- Store per-account backup paths.
+- Make `import:process` support `remote_server` by using downloaded archives.
+
+Phase 3:
+- Implement email restore (mail domains, mailboxes, Maildir copy).
+- Implement SSL restore (custom cert install, LE fallback).
+
+Phase 4:
+- Add tests (discovery, permissions, per-account import state).
+- Add docs and screenshots for the new pages/tabs.
+

docs/docs-index.md

@@ -1,6 +1,6 @@
 # Jabali Documentation Index
 
-Last updated: 2026-02-09
+Last updated: 2026-02-10
 
 ## Top-Level Docs
 - /var/www/jabali/README.md - Product overview, features, install, upgrade, and architecture summary.
@@ -13,6 +13,7 @@ Last updated: 2026-02-09
 ## Docs Folder
 - /var/www/jabali/docs/installation.md - Debian package install path, Filament notifications patch, and deploy script usage.
 - /var/www/jabali/docs/architecture/control-panel-blueprint.md - High-level blueprint for a hosting panel.
+- /var/www/jabali/docs/architecture/directadmin-migration-blueprint.md - Blueprint for migrating DirectAdmin accounts into Jabali.
 - /var/www/jabali/docs/archive-notes.md - Archived files and restore notes.
 - /var/www/jabali/docs/screenshots/README.md - Screenshot generation instructions.
 - /var/www/jabali/docs/docs-summary.md - Project documentation summary (generated).

docs/docs-summary.md

@@ -1,6 +1,6 @@
 # Documentation Summary (Jabali Panel)
 
-Last updated: 2026-02-09
+Last updated: 2026-02-10
 
 ## Product Overview
 Jabali Panel is a modern web hosting control panel for WordPress and general PHP hosting. It provides an admin panel for server-wide operations and a user panel for per-tenant management. The core goals are safe automation, clean multi-tenant isolation, and operational clarity.
@@ -53,5 +53,6 @@ mcp-docs-server exposes README, AGENT docs, and changelog through MCP tools for
 
 ## Miscellaneous Docs
 - Screenshot regeneration script: tests/take-screenshots.cjs.
+- DirectAdmin migration blueprint: docs/architecture/directadmin-migration-blueprint.md.
 - Policies: resources/markdown/policy.md and resources/markdown/terms.md are placeholders.
 - WordPress plugin: resources/wordpress/jabali-cache/readme.txt documents the Jabali Cache plugin.