Deployment | Metroflow Docs

Choose a deployment path

Docker Compose

Single host, five-minute setup, ideal for evaluation and teams under ~20 users.

Kubernetes + Helm

HA API, horizontal crawler workers, external Postgres, and ingress for SSO.

Both paths ship the same services: metroflow-api (REST + graph), metroflow-crawler (connector workers), metroflow-ui (workspace), and metroflow-agent (Company Brain runtime). Compose bundles Postgres; Helm expects a managed database for production.

Docker Compose

Docker Compose is the fastest way to run a full Metroflow stack locally or on a single VM. Clone the open-source repository, copy the example environment file, and bring services up.

Clone and configure
Copy .env.example to .env and set METROFLOW_SECRET (32+ random bytes) and METROFLOW_DB_URL if not using the bundled Postgres.
Start services
All containers join the default Compose network. The workspace is available once health checks pass.
Create admin user
On first boot, open the workspace setup wizard or run the CLI seed command to create your org and admin account.
Add connectors
Point at dbt, Snowflake, or Airflow from Settings → Connectors. See Connectors for per-tool credentials.

shell: Docker Compose

$git clone https://github.com/metroflow/metroflow.git

$cd metroflow

$cp .env.example .env

# edit METROFLOW_SECRET and optional LLM keys

$docker compose up -d

✓ metroflow-api http://localhost:8080

✓ metroflow-ui http://localhost:4200

✓ metroflow-crawler connected

✓

Persist data. Compose mounts a volume for Postgres by default. Back up ./data/postgres before upgrades or use an external METROFLOW_DB_URL.

For teams sharing one host, put nginx or Caddy in front of port 4200 with TLS. Restrict crawler egress to your warehouse and orchestrator subnets via firewall rules.

Kubernetes & Helm

Production deployments use the official Helm chart in deploy/helm/metroflow. The chart deploys API, UI, crawler, and agent deployments with configurable replicas, ingress, and external secrets.

Install

shell: Helm

$helm repo add metroflow https://charts.metroflow.dev

$helm repo update

$helm install metroflow metroflow/metroflow -f values.prod.yaml -n metroflow --create-namespace

values.yaml highlights

Override these keys in your environment-specific values file:

values.prod.yaml

api:

replicaCount: 3

resources:

requests: { cpu: "500m", memory: "1Gi" }

crawler:

replicaCount: 2

workerConcurrency: 8

postgresql:

enabled: false

externalDatabase:

host: prod-pg.internal.example.com

existingSecret: metroflow-db-credentials

ingress:

enabled: true

hostname: metroflow.corp.example.com

tlsSecretName: metroflow-tls

agent:

llmProvider: anthropic

existingSecret: metroflow-llm-keys

Enable podDisruptionBudgets and topologySpreadConstraints for multi-AZ clusters. Crawler workers scale independently; heavy Snowflake estates often run 4+ crawler replicas with workerConcurrency: 16.

!

Managed Postgres recommended. Use RDS, Cloud SQL, or Aurora with automated backups and point-in-time recovery. The bundled subchart is for dev only.

Environment variables

Core configuration for all deployment modes. Set via .env (Compose), Kubernetes secrets, or your secrets manager.

Variable	Required	Description
`METROFLOW_DB_URL`	Yes	Postgres connection string. Format: `postgres://user:pass@host:5432/metroflow`. Bundled in Compose if omitted.
`METROFLOW_SECRET`	Yes	Signing key for sessions and API tokens. Minimum 32 bytes of entropy; rotate on compromise.
`METROFLOW_PUBLIC_URL`	Prod	External URL users hit (e.g. `https://metroflow.corp.example.com`). Used for OAuth redirects and email links.
`METROFLOW_LLM_PROVIDER`	For agents	`openai`, `anthropic`, `azure`, or `ollama` for air-gapped local models.
`METROFLOW_LLM_API_KEY`	For agents	Provider API key. Omit when using `ollama` or IAM-based Azure OpenAI.
`METROFLOW_LLM_MODEL`	No	Default model ID (e.g. `gpt-4o`, `claude-sonnet-4-20250514`). Per-agent overrides in workspace settings.
`METROFLOW_CRAWLER_CONCURRENCY`	No	Parallel connector jobs per crawler process. Default `4`; raise for large estates.
`METROFLOW_LOG_LEVEL`	No	`debug`, `info`, `warn`, `error`. Use `debug` temporarily when troubleshooting sync failures.
`METROFLOW_SSO_ISSUER`	SSO	OIDC issuer URL for Okta, Azure AD, or Google Workspace SSO.
`METROFLOW_SSO_CLIENT_ID`	SSO	OAuth client ID registered with your IdP.
`METROFLOW_SSO_CLIENT_SECRET`	SSO	OAuth client secret. Store in Kubernetes secret or vault, not plain ConfigMap.
`METROFLOW_ENCRYPTION_KEY`	Prod	AES-256 key for connector credentials at rest. Required when not using external secrets integration.

Resource requirements

Sizing depends on graph size (asset count), connector count, and concurrent agent users. Start conservative and scale crawler replicas first when sync duration grows.

Profile	Users / assets	CPU	RAM	Storage
Dev / PoC	< 10 users, < 5k assets	4 cores total	8 GB	20 GB SSD (Postgres + logs)
Team	10–50 users, 5k–50k assets	8–12 cores	16–24 GB	100 GB SSD; grow with graph
Enterprise	50+ users, 50k+ assets	16+ cores (distributed)	32+ GB	500 GB+ managed Postgres; object storage for exports optional

Postgres is the primary storage consumer; plan ~1–2 KB per graph node including indexes. Agent workloads add burst CPU when Company Brain handles concurrent chats; the agent service scales horizontally independently of the API.

Network egress is modest: crawlers call tool APIs inside your VPC. LLM calls egress only to your chosen provider unless you run Ollama on-prem.

VPC & air-gapped

Metroflow is built for self-hosting inside private networks. No telemetry or metadata is sent to Metroflow Inc. unless you opt into support bundles.

VPC deployment

Place API, UI, and crawler pods in application subnets with egress to warehouse and orchestrator endpoints. Database lives in a data subnet with security groups allowing only API and crawler sources. Use private ingress (internal ALB, Tailscale, or VPN) for user access.

Air-gapped installs

Mirror container images to your registry. Set METROFLOW_LLM_PROVIDER=ollama and run a local model server; agents work without external API calls. Pre-load Helm charts and disable automatic update checks. Connector credentials remain encrypted; rotate METROFLOW_ENCRYPTION_KEY per your key ceremony.

✓

Compliance packets. Export subgraphs and audit logs from the workspace for SOC 2 or HIPAA reviews. Metadata-only crawls simplify data-residency arguments.

Upgrade path

Metroflow follows semantic versioning. Patch releases are safe to apply without downtime when running 2+ API replicas behind a load balancer.

Back up Postgres
Snapshot the database before any minor or major upgrade. Migrations run automatically on API boot.
Compose: pull and recreate
Pin image tags in docker-compose.yml for reproducibility. docker compose pull && docker compose up -d rolls services with minimal interruption.
Helm: upgrade release
helm upgrade metroflow metroflow/metroflow -f values.prod.yaml --version X.Y.Z. Review release notes for breaking changes; major versions may require connector re-auth or env renames.
Verify crawls
After upgrade, trigger a manual sync on one connector and confirm graph search returns expected assets before announcing completion.

Rollback: Helm helm rollback metroflow <revision>; Compose revert image tags and recreate. Database migrations are forward-only; restore from backup if a failed migration occurs.