SwiftDeploy: Building a Manifest-Driven Stack

Most deployment setups do not fail because the tools are weak. They fail because the process drifts: one person edits nginx.conf, another tweaks Compose, and soon nobody knows what the real deployment contract is.

SwiftDeploy solves that with a simple principle: declare intent once in manifest.yaml, and make everything else derived and verifiable.

It started as a config-generation CLI, but it became more useful when policy and observability were added. The interesting part is not that it creates files; it is that it can block unsafe actions when runtime signals say “don’t proceed.”

Link: Github Repository

The core idea in one view

From left to right:

Clients hit Nginx.
Nginx proxies to the Go app on the internal network.
The swiftdeploy CLI generates configs and asks OPA for policy decisions on loopback (127.0.0.1), not through public ingress.

That separation is intentional. User traffic and control decisions use different paths.

What makes this practical

Real manifest excerpt:

services:
  image: swiftdeploy-api-go:latest
  port: 3000
  mode: stable
  app_version: "1.0.0"

nginx:
  image: nginxinc/nginx-unprivileged:stable-alpine
  port: 8080
  proxy_timeout: 30s

opa:
  image: openpolicyagent/opa:latest
  port: 8181

policy:
  data_file: policy-data/thresholds.json
  decision_timeout_seconds: 5

From this, ./swiftdeploy init renders:

template-output/nginx.conf
template-output/docker-compose.yml

From there:

validate confirms preflight health,
deploy starts policy sidecar + stack,
promote switches stable/canary mode safely,
status and audit leave an evidence trail.

Why this is more than a wrapper script

The CLI enforces two decision points:

Pre-deploy gate
Host conditions (disk/cpu/memory snapshot) are checked against policy before full startup proceeds.
Pre-promote gate (canary -> stable)
Windowed metrics from /metrics are evaluated before promotion completes.

So this is not only “template rendering.” It is decision-aware deployment.

What I learned while building it

Policy paths are easy to get subtly wrong.
POST /v1/data/policy/infrastructure/decision is valid.
POST /v1/data/infrastructure/decision often returns {} and can waste debugging time.
Ingress isolation should be proven, not assumed.
Hitting OPA-shaped URLs on Nginx should return app-level 404/non-OPA response, while loopback OPA returns policy JSON.
Canary tests need traffic.
Windowed error-rate checks can look “healthy” if there is no meaningful request volume during the window.
Generated files are outputs, not source files.
If you edit generated Compose/Nginx files directly, init will overwrite them.

Outcome

With this setup, deployment becomes:

declarative (manifest.yaml as source of truth),
reproducible (templates + generated configs),
observable (/metrics, status),
enforceable (OPA gates),
auditable (history.jsonl -> audit_report.md).

That is the difference between “it runs on my machine” and “I can prove this rollout is safe.”

Verification Appendix (commands + expected checks)

Run from swiftdeploy-project/.

A) Path flow

./swiftdeploy build
./swiftdeploy init
./swiftdeploy validate
./swiftdeploy deploy
./swiftdeploy promote canary
./swiftdeploy promote stable
./swiftdeploy status 5
./swiftdeploy audit
./swiftdeploy teardown --clean

Expected highlights:

validate reports all checks PASS.
deploy ends with stack healthy.
promote canary enables X-Mode: canary on /healthz.
promote stable removes X-Mode after successful gate.
status appends records to history.jsonl.
audit generates audit_report.md.

SCREENSHOT_VALIDATE_PASS

SCREENSHOT_DEPLOY_HEALTHY

SCREENSHOT_PROMOTE_CANARY_AND_HEALTHZ

SCREENSHOT_PROMOTE_STABLE_AND_HEALTHZ

SCREENSHOT_STATUS_OUTPUT

SCREENSHOT_AUDIT_REPORT

SCREENSHOT_TEARDOWN_CLEAN

B) Confirm metrics and policy endpoints

Check that required Prometheus metric families are exposed through Nginx ingress:

curl -sS "http://127.0.0.1:8080/metrics" | grep -E "http_requests_total|http_request_duration_seconds|app_uptime_seconds|app_mode|chaos_active" | head

Check infrastructure policy decision endpoint (OPA loopback):

curl -sS -X POST "http://127.0.0.1:8181/v1/data/policy/infrastructure/decision" \
  -H "Content-Type: application/json" \
  -d '{"input":{"context":"pre-deploy","disk_free_gb":50,"cpu_load":0.3}}'

Check canary policy decision endpoint (OPA loopback):

curl -sS -X POST "http://127.0.0.1:8181/v1/data/policy/canary/decision" \
  -H "Content-Type: application/json" \
  -d '{"input":{"context":"pre-promote","window_seconds":30,"error_rate":0.001,"p99_latency_ms":100}}'

Expected:

Metrics families visible.
OPA responses contain a result object and allow.

SCREENSHOT_METRICS_OUTPUT

SCREENSHOT_OPA_INFRA_ALLOW

SCREENSHOT_OPA_CANARY_ALLOW

C) Confirm OPA is not exposed through ingress

curl -sS -o /dev/null -w "%{http_code}\n" "http://127.0.0.1:8080/v1/data/policy/infrastructure/decision"

Expected:

404 or non-OPA response via Nginx path.

SCREENSHOT_INGRESS_ISOLATION_CHECK

D) Test deny and recovery scenarios

Force deploy deny by tightening thresholds in policy-data/thresholds.json, then:

./swiftdeploy teardown
./swiftdeploy deploy

Force promote deny:

./swiftdeploy promote canary
curl -sS -X POST "http://127.0.0.1:8080/chaos" \
  -H "Content-Type: application/json" \
  -d '{"mode":"error","rate":1.0}'
./swiftdeploy promote stable

Recover:

curl -sS -X POST "http://127.0.0.1:8080/chaos" \
  -H "Content-Type: application/json" \
  -d '{"mode":"recover"}'
./swiftdeploy promote stable

SCREENSHOT_DEPLOY_DENIED_BY_POLICY

SCREENSHOT_PROMOTE_DENIED_BY_POLICY

SCREENSHOT_PROMOTE_SUCCESS_AFTER_RECOVER

推荐订阅源

DEV Community