Deployment overview

ArcFlow ships as Rust binaries (arcflow-server, arcflow-relay, arcflow CLI) plus Docker Compose stacks under docker/. Production deployments center on three scenarios: local development, self-hosted server with Postgres, and the static product pattern (server + Relay + browser SDK).

Each scenario maps to a Compose file or bare-metal process layout. The server is the control plane for runs, registry, admin sites, traces, and recovery. Relay is optional but required for browser-facing chat without exposing LLM keys. Postgres is required for server runs, admin APIs, and trace persistence. Qdrant is required when vector memory or site knowledge ingest uses embeddings.

Deployment scenarios

Scenario	Primary audience	Compose file	Minimum services
Local development	Developer	`docker/docker-compose.dev.yml`	Postgres, Qdrant
Server API + admin	Platform	`docker/docker-compose.server.yml`	Postgres, migrate job, server
Production static product	Operator, platform	`docker/docker-compose.prod.yml`	Postgres, Qdrant, migrate, server, relay
BYO Relay only	Frontend team	`examples/relay/byo-docker/`	Relay + upstream server URL

Local development

Developers run Postgres and Qdrant via docker-compose.dev.yml, then build the SDK or server on the host. This stack does not start ArcFlow binaries; it provides dependencies for cargo run, SDK tests, and RAG examples.

Self-hosted server

docker-compose.server.yml builds arcflow-migrate (one-shot), arcflow-server, and optionally arcflow-relay. Use this when operators call /v1/runs and admin routes directly from backend services or CI, without a public browser chat widget.

Static product (Relay + published workflows)

docker-compose.prod.yml adds Qdrant and production-oriented volume mounts. Operators create sites via admin API, ingest knowledge, publish chat workflows, and embed Relay URL plus site token in a static frontend. See Relay deployment and Sites management (ArcFlow repository).

Startup sequence (server)

Regardless of Compose or bare metal, a healthy server deployment follows this order:

Validate environment (ARCFLOW_SERVER_API_KEY, ARCFLOW_POSTGRESQL_URL, provider keys as needed).
Ensure Postgres is reachable.
Apply migrations (arcflow migrate up or rely on auto-migrate, then verify /ready).
Start arcflow-server (non-root user in official Dockerfile).
Confirm GET /health returns 200 and GET /ready returns 200 before routing traffic.

Relay starts after the upstream server is listening. Relay reads site configuration from Postgres when ARCFLOW_POSTGRESQL_URL is set, or from ARCFLOW_RELAY_SITES_JSON for BYO deployments.

Docker Compose file reference

File	Purpose
`docker/docker-compose.dev.yml`	Postgres 16 + Qdrant for host-side dev
`docker/docker-compose.server.yml`	Migrate + server + relay + static demo nginx
`docker/docker-compose.prod.yml`	Production-like stack with named volumes
`docker/docker-compose.otel.yml`	Optional OTel collector overlay (OpenTelemetry export (alpha))

Contract guides for self-hosted and meta-repo layout live in the ArcFlow repository (not duplicated on this site).

Normative HTTP detail: HTTP API reference. Admin-only routes are documented in the ArcFlow repository.

Operator dashboard (deferred)

The operator UI lives in the private ArcFlow-Dashboard repository. OSS holds the specification in this documentation and a starter scaffold at deploy/arcflow-dashboard-v0/. Operator dashboard UI (dashboard v1 UI) is deferred until exit criteria in Dashboard spec (ArcFlow repository) pass in private repo CI. Until then, use admin API directly, OSS shell scripts (scripts/static-*.sh), or the v0 starter. See Dashboard spec (ArcFlow repository).

Meta-repo layout

Private platform repos submodule OSS ArcFlow and ArcFlow-Dashboard. Template: deploy/meta-repo-template/. Convention ports: server 8080, relay 8090, dashboard dev 5174.