services:
  image: swiftdeploy-keeds-api:v1.0.0
  port: 5000
  name: api-service
  mode: stable

nginx:
  image: nginx:alpine
  port: 8080
  proxy_timeout: 30s

network:
  name: swiftdeploy-net
  driver_type: bridge

containers, waits for health checks, and gates via OPA | | promote canary/stable | Switches deployment mode after policy validation | | status | Renders live dashboard with metrics and compliance state | | audit | Compiles history.jsonl into audit_report.md | | teardown | Gracefully stops and removes all containers |

3. OPA Policy Enforcement

OPA acts as an externalized policy guard. The CLI never makes allow/deny decisions; it queries OPA with host metrics and application state.

Data-Driven Thresholds (thresholds.json):

{
  "infrastructure": {
    "min_disk_gb": 10,
    "max_cpu_load": 2.0
  },
  "canary": {
    "max_error_rate": 0.01,
    "max_p99_latency_ms": 500
  }
}

Policy Separation:

• infrastructure.rego: Validates disk space and CPU load before deployment.
• canary.rego: Validates error rate and P99 latency before promotion.
• Thresholds are injected at runtime, keeping Rego logic domain-specific and version-controlled independently.

4. Observability & Audit Trail

The API exposes Prometheus-formatted metrics:

http_requests_total{method="GET",path="/healthz",status_code="200"} 42
http_request_duration_seconds_bucket{le="0.1"} 35
app_uptime_seconds 847
app_mode 0
chaos_active 0

The status dashboard renders real-time compliance:

╔═══════════════════════════════════════╗
║     SwiftDeploy Status Dashboard      ║
╠═══════════════════════════════════════╣
║ Mode: canary                         ║
║ Chaos: none                          ║
║ Req/s: 0.98                          ║
║ P99 Latency: 5ms                     ║
║ Error Rate: 0.00%                    ║
║ Uptime: 133s                         ║
╠═══════════════════════════════════════╣
║ Policy Compliance                    ║
║   Infrastructure: PASS               ║
║   Canary Safety:  PASS               ║
╚═══════════════════════════════════════╝

Every refresh appends to history.jsonl, enabling deterministic audit reconstruction.

5. Architecture Flow

User runs: swiftdeploy deploy
    │
    ▼
CLI gets host stats (disk, CPU)
    │
    ▼
CLI asks OPA: "Is it safe to deploy?"
    │
    ├── If safe → Start containers
    │
    └── If not safe → Block with reason

User runs: swiftdeploy promote canary
    │
    ▼
CLI scrapes /metrics endpoint
    │
    ▼
CLI calculates error rate and P99 latency
    │
    ▼
CLI asks OPA: "Is it safe to promote?"
    │
    ▼
OPA checks canary safety policy
    │
    ├── If safe → Switch to canary mode
    │
    └── If not safe → Block with reason

Pitfall Guide

1. OPA Rego Syntax Conflicts: Declaring default deny := [] alongside deny contains msg if { ... } triggers a compilation error. The contains keyword natively handles empty sets; remove explicit defaults.
2. OPA Data Path Resolution: OPA loads JSON data based on directory structure. Placing thresholds.json in the root breaks data.swiftdeploy.thresholds.* references. Always nest data files under a domain-specific subdirectory.
3. Missing Input Fields in OPA Queries: OPA policies often require input.timestamp for temporal validation. Omitting this field causes silent rule failures and defaults to FAIL. Always inject a UTC timestamp in every CLI-to-OPA payload.
4. Nginx DNS Resolution at Startup: Nginx resolves proxy_pass hostnames at startup by default. If the backend container isn't ready, it throws 502 errors. Configure resolver 127.0.0.11 valid=30s; and use a variable for the upstream to force runtime DNS lookup.
5. Container Restart vs Recreation: docker compose restart preserves existing environment variables and does not reload updated docker-compose.yml configurations. Use docker compose up -d --no-deps <service> to force recreation with new settings.
6. Over-Restricting Nginx Capabilities: Explicitly setting user: nginx and dropping all Linux capabilities prevents Nginx from creating runtime directories and binding to ports. Rely on the official image's internal user-switching logic instead.
7. Hardcoding Thresholds in Policy Logic: Embedding numeric limits directly in Rego files couples policy logic to operational parameters. Always externalize thresholds to JSON/YAML data files and inject them at query time.

Deliverables

• 📘 SwiftDeploy Architecture Blueprint: Complete system diagram, OPA policy mapping, and container lifecycle state machine.
• ✅ Pre-Deployment Validation Checklist: Step-by-step verification for manifest syntax, host resource thresholds, OPA connectivity, and DNS resolution.
• ⚙️ Configuration Templates: Production-ready manifest.yaml, thresholds.json, OPA Rego modules (infrastructure.rego, canary.rego), and Nginx/Docker Compose generator scripts.
• 📊 Audit & Monitoring Pack: history.jsonl schema documentation, Prometheus metric definitions, and automated audit_report.md generation pipeline.