diff --git a/docs/architecture/directadmin-migration-blueprint.md b/docs/architecture/directadmin-migration-blueprint.md new file mode 100644 index 0000000..ae623b5 --- /dev/null +++ b/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. + diff --git a/docs/docs-index.md b/docs/docs-index.md index 5748b79..e8cfd26 100644 --- a/docs/docs-index.md +++ b/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). diff --git a/docs/docs-summary.md b/docs/docs-summary.md index ddcbbc4..105a6e3 100644 --- a/docs/docs-summary.md +++ b/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.