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

le for API, Nginx, and OPA containers within an isolated bridge network.

Stage 4B: Observability & Policy Enforcement

Prometheus Metrics Endpoint The API service exposes /metrics in Prometheus format:

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

These metrics provide real-time visibility into request volume, latency distribution, uptime, deployment mode, and chaos testing state.

OPA: The Policy Engine OPA runs as an isolated container acting as a deterministic safety gate. The CLI never makes allow/deny decisions; it queries OPA and enforces the response.

• Decoupled Policies: Rego files are separate from CLI code, enabling independent updates.
• Graceful Degradation: If OPA is unreachable, the CLI warns but continues operation.
• Network Isolation: OPA is not exposed to external traffic, reducing attack surface.

Data-Driven Thresholds Thresholds are externalized from Rego logic into a configuration file, enabling runtime adjustments without policy recompilation.

thresholds.json:

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

Status Dashboard & Audit Trail The swiftdeploy status command renders a real-time compliance dashboard:

╔═══════════════════════════════════════╗
║     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 structured data to history.jsonl. The swiftdeploy audit command parses this log to generate audit_report.md, containing event timelines and policy violation records.

Architecture Flow

User runs: swiftdeploy deploy
    │
    ▼
CLI gets host stats (disk, CPU)
    │
    ▼
CLI asks OPA: "Is it safe to deploy?"
    │
    ▼
OPA checks infrastructure policy
    │
    ├── 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: Defining default deny := [] alongside deny contains msg if { ... } triggers a compilation error. The contains keyword inherently handles empty sets; remove the default declaration to resolve rule conflicts.
2. OPA Data Path Resolution: OPA resolves JSON data files based on directory structure, not just filenames. Placing thresholds.json in the root causes data.thresholds to return undefined. Nest it under a domain folder (e.g., swiftdeploy/thresholds.json) and reference it via data.swiftdeploy.thresholds.
3. Missing Context in Policy Queries: OPA policies requiring temporal validation will fail if input.timestamp is omitted. Always inject a current timestamp into every CLI-to-OPA query payload to prevent false-negative policy evaluations.
4. Nginx Static DNS Resolution at Startup: Nginx resolves upstream hostnames during configuration parsing. If the backend container isn't running yet, Nginx fails with 502 errors. Use Docker's internal DNS resolver (resolver 127.0.0.11 valid=30s;) and assign the upstream to a variable to force runtime resolution.
5. Container Restart vs Recreation: docker compose restart preserves the original container's environment and filesystem layers. To apply updated docker-compose.yml variables or image tags, use docker compose up -d --no-deps <service> to force recreation.
6. Privilege Conflicts in Official Images: Explicitly setting user: nginx and dropping Linux capabilities on the official Nginx Alpine image breaks internal directory creation and socket binding. Rely on the image's built-in user-switching logic and only apply capability restrictions when absolutely necessary.

Deliverables

• 📘 SwiftDeploy Architecture Blueprint: Complete system diagram detailing manifest parsing, OPA policy evaluation flow, Docker network topology, and Prometheus metric ingestion paths. Includes decision matrices for canary promotion and infrastructure validation.
• ✅ Pre-Deployment & Promotion Checklist: Step-by-step validation protocol covering manifest syntax verification, OPA policy compilation, threshold alignment, container health readiness, and audit log initialization.
• ⚙️ Configuration Templates: Production-ready manifest.yaml, thresholds.json, OPA Rego policy skeletons (infrastructure.rego, canary.rego), and Nginx dynamic resolver configuration snippets. All templates include inline validation rules and environment-specific variable placeholders.