Takeover Process

The takeover process atomically migrates traffic from nginx to bext. It stops nginx, binds bext to ports 80/443, and provides automatic rollback if anything fails.

State Machine#

The takeover follows a strict state machine:

Preflight ──→ TakingOver ──→ Active
                  │              │
                  ▼              ▼
               Failed ←── RollingBack ──→ RolledBack

Takeover Sequence#

When you click "Take Over" (or POST to /api/takeover):

1. Verify preconditions — phase must be Preflight, no critical check failures
2. Set phase = TakingOver — UI shows loading overlay
3. Record nginx state — whether nginx was enabled for boot start
4. Stop nginx — systemctl stop nginx
5. Wait for ports — poll ports 80/443 for up to 3 seconds
   • If ports are still busy → auto-rollback, phase = Failed
6. Disable nginx — systemctl disable nginx (non-fatal if it fails)
7. Bind bext — start serving on ports 80/443 with nginx config
8. Set phase = Active

Rollback Sequence#

When you click "Rollback" (or POST to /api/rollback):

1. Verify phase — must be Active or Failed
2. Set phase = RollingBack
3. Re-enable nginx — systemctl enable nginx (if it was enabled before)
4. Start nginx — systemctl start nginx
5. Verify — wait 500ms and check nginx is running
   • If nginx fails to start → phase = Failed with error message
6. Set phase = RolledBack

Automatic Rollback#

If the takeover fails after nginx has been stopped (e.g., ports still occupied by another process), bext immediately runs:

systemctl start nginx

This ensures traffic is never left without a server. The phase is set to Failed, and the error is displayed in the dashboard.

Prerequisites#

• Root access — needed to stop/start services and bind to ports < 1024
• systemd — the takeover uses systemctl for all service management
• nginx.service — the nginx systemd unit must be named "nginx"

Safety Guarantees#

1. Read-only during preflight — no system changes until you explicitly trigger takeover
2. Confirmation required — both takeover and rollback require user confirmation
3. Atomic transitions — if any step fails, auto-rollback restores nginx immediately
4. Boot-start preserved — nginx's enabled/disabled state is recorded and restored on rollback
5. Dashboard stays up — the preflight server remains accessible on its port for rollback access even after takeover
6. No data loss — the takeover only manages process lifecycle, not configuration files

Usage via CLI#

# Launch with auto-detected config
sudo bext nginx-takeover

# Specify config and port
sudo bext nginx-takeover --nginx-config /etc/nginx/nginx.conf --port 9999

Preflight Checks Reference#

All critical checks must pass before takeover is allowed. Non-critical warnings are informational — they highlight potential issues but don't block the migration.

Related#

• Preflight Dashboard — the UI that drives the Take Over and Rollback buttons
• Masquerade Mode — the alternative path that avoids stopping nginx at all
• Migration Guide — full migration walkthrough; takeover is Option B
• nginx Compatibility Overview — what bext parses before the takeover runs
• Operations: Invalidation and Restarts — service lifecycle after cutover