MAID Deployment Guide

Audience: operators standing up a new MAID instance on bare metal. This is the top-level index — each section links to the authoritative detailed guide or runbook.

Validation: scripts/check_deployment_guide.py enforces the required section headings below and verifies every internal link target exists.

---

Prerequisites

Before starting installation, confirm the host and operator environment meet the baseline:

• Host: Debian 12 (bookworm) or Ubuntu 22.04 LTS (jammy).
• Resources: 4 vCPU / 8 GB RAM / 100 GB SSD (minimum).
• DNS: A record pointing at the host's public IP.
• Operator: non-root login with sudo access.

See the bare-metal deployment guide → Prerequisites for the exact substitution variables to export before running any subsequent command, and the security checklist for hardening expectations.

Install

Run the 14-step bootstrap from a clean release tarball:

• Bare-metal deployment — 14-step procedure
• Install/rollback test harness

Each step has a one-line rollback and a pointer to its owning runbook.

Configure

Configuration lives in /etc/maid/<instance>.env plus the runtime config/ overlay. The authoritative reference:

• Operator handbook → First-time setup
• SSL configuration
• Bridges configuration

First-Run

After install completes, exercise the engine and capture a baseline:

• Bare-metal deployment → Step 13 (start) + Step 14 (verify)
• Operator handbook → Common tasks
• Doctor health-check tool

The post-install doctor pass (maid-doctor.sh --phase install) is the gate for declaring a host "in service."

Operate

Day-2 operational reference:

• Operator handbook
• Metrics catalog
• SLO / RPO / RTO targets
• Runbook index
• Maintenance window runbook

Backup & Restore

The backup driver is deploy/scripts/backup.sh. A systemd timer (maid-backup@<inst>.timer → maid-backup@<inst>.service) is staged by the installer, but it is not yet functional: its ExecStart is /opt/maid/current/bin/backup.sh, which the current release tarball does not install (the tarball populates bin/lib/packages but not deploy/scripts/), so the unit fails 203/EXEC. Until the M1.4 packaging lands, do not rely on the timer or on automated restore drills — take backups manually from a source checkout with deploy/scripts/backup.sh full and run restore drills manually with deploy/scripts/restore.sh staging. See the manual procedures below.

• Backup runbook (manual interim procedure)
• Backup/restore scripts README
• Restore runbook
• Backup failure runbook
• Durability matrix

Upgrade

Three upgrade paths, ranked by least-disruptive:

• Upgrade procedure (hot reload / restart / migration)
• Failed migration runbook

Rollback

When an upgrade misbehaves, fall back to the previous release tarball:

• Rollback runbook
• Upgrade → Rollback matrix

Troubleshoot

Symptom-indexed runbooks for the failure classes that have ever paged us:

• Runbook index (symptom → runbook)
• AI provider outage
• DB down
• Disk full
• OOM loop
• Save queue growing
• Redis down
• Two instances detected
• Resource exhaustion (RB19)
• Firewall fallback (RB17)
• Host loss / DR (RB18)
• Python/uv issues (RB22)

For chaos-test-driven verification of these recovery paths, see the chaos test catalogue (docs/chaos/catalogue.md) and the chaos test operational runbook (docs/runbooks/chaos-test.md), both added in sibling commits.