Deployment and Operations

Runtime Components

• FastAPI app (HTTP)
• SMTP inbound listener (port 25)
• Outbox worker for direct SMTP send
• SQLite database on persistent volume (/data/zmail.db)

Fly.io Deployment

fly deploy --now
fly status --app zmail-zergai
fly checks list --app zmail-zergai
fly logs --app zmail-zergai

Required Secrets and Config

• ZMAIL_API_KEY
• Mail domain and SMTP-related environment from config.py

DNS Requirements

At minimum for domain mail flow:

• A record for mail host to Fly IPv4
• MX record pointing to mail host
• TXT SPF record allowing mail host
• DKIM/DMARC records when enabled

See also: DNS_DELIVERABILITY.md.

Health Verification

• API check: GET /health
• SMTP check: Fly service check on TCP 25
• App surface check: GET /, GET /login, GET /admin/login

Post-Deploy Smoke Checklist

1. Open / and /login in browser.
2. Login with test user and verify /app loads.
3. GET /app/api/session with session token succeeds.
4. Create webhook and send test event.
5. Confirm webhook delivery record is written.
6. Send test email and confirm message arrives in inbox.

Incident Triage

Site unreachable

1. fly status --app zmail-zergai
2. fly checks list --app zmail-zergai
3. fly logs --app zmail-zergai --no-tail

Domain resolves to parked page

1. Verify DNS A/CNAME records in registrar.
2. Remove parked/forwarding records.
3. Confirm cert and app mapping in Fly.

SMTP send failures

1. Inspect outbox errors in logs.
2. Verify outbound DNS and recipient MX reachability.
3. Validate SPF/DKIM/DMARC alignment.

Webhook failures

1. Check /app/api/webhooks/{id}/deliveries.
2. Validate endpoint TLS and 2xx responses.
3. Verify secret/signature handling in receiver.