Repair System¶

The Repair System is a central admin tool that re-renders every panel config domain from the database truth-source, detects drift and fixes it in one click. The unified UI replaces the previous separate "Repair" and "Orphaned Resources" pages.

Available under Settings → Repair.

What does the Repair System do?¶

Every module has one truth source (a DB table) and re-renders the full on-disk target state from it. Writes run in a transaction with automatic rollback on validation failure. Each run produces a structured report: planned, written, unchanged, errors — plus diffs where action is needed.

Available modules¶

Module	Purpose
TLS configuration	Pushes the `cert_registry` to every mail-capable agent — Postfix + Dovecot SNI maps update idempotently
Ghost site records	Finds `sites` rows whose linux user / home dir no longer exist on the server (half-deleted accounts). Each finding exposes a delete button
Web server configurations	Re-renders every active site vhost from the DB using the single-source vhost builder — catches template updates that an `apt upgrade` never applied to existing vhosts
Backup snapshots	Reconciles the `backup_jobs` table with the snapshots actually present in the storage backend (local / FTP / S3). Orphaned DB rows get `pruned_at` marked
Orphaned resources	Finds on-disk resources (home dirs, linux users, PHP-FPM pools) that no active site owns. Each finding exposes a cleanup button including linux-user delete

Running modules¶

Every module has its own "Run" button. The "Run all" button runs the chain in a defined order:

TLS configuration (cert-registry push first so vhost builder resolves SSL paths correctly)
Ghost site records (ghost cleanup before vhost render)
Web server configurations
Backup snapshots
Orphaned resources

An infrastructure failure (agent unreachable) aborts the chain and shows how far it got. Individual entity failures within a module do not stop the chain.

Bulk cleanup¶

Scan-type modules (Ghost site records, Orphaned resources) show a "Clean up all" button above the diffs table when ≥2 entries are present. It runs every repair action sequentially (not in parallel — parallel agent reloads would stampede), tracks per-action success/failure and re-runs the module afterwards.

Inline actions¶

Diffs may carry a repair action — e.g. "Clean up" for an orphan or "Delete" for a ghost site row. The button appears directly in the diff row with a confirmation prompt for destructive operations.

When to run Repair¶

After updates (apt upgrade enconf-*) when templates changed — Web server configurations picks up the new templates
After panel errors that may have left inconsistent on-disk state (network timeout mid-provisioning, agent crash)
Periodically for drift control — once a week as a safety net
For concrete troubleshooting — when a customer reports their site isn't loading, "Web server configurations" surfaces which sites are config-wise suspicious

Contract of every Repair module¶

Every module honours four guarantees:

Total — the full target state is re-rendered from DB, never an incremental patch
Idempotent — a second call immediately after a successful first is a no-op
Transactional — mutations run in a snapshot+validate+rollback transaction: the service is either in the new state and validated, or in the old state and running — no broken-in-between window
Verified — post-write service test (nginx -t, postfix check, doveconf -n) plus live probe where applicable

Full architectural docs for developers live in the repository under docs/repair-architecture.md.

Safety¶

All actions require the Admin role
Destructive actions carry a confirmation popup stating what will be removed
Orphan cleanup double-checks the username is not still bound to an active site before delete; returns 409 still_in_use on race — protects against concurrent customer creation
Ghost site delete reuses the standard site-delete endpoint's ?force=true escape hatch — the normal path would correctly abort with an agent error for ghost sites