Quickstart

Prerequisites

Metroflow runs entirely in containers. You need a machine with enough headroom for the API, crawler, graph store, and workspace UI.

• Docker 24+ with Docker Compose v2 (docker compose)
• 4 GB RAM minimum (8 GB recommended if syncing large dbt projects)
• Git to clone the open-source repository
• Optional: Snowflake or Postgres credentials for your first connector sync

Install with Docker Compose

Five steps from empty directory to a live workspace. Each step includes the exact commands to run.

1. Clone the repository

   Pull the latest stable branch from GitHub. All services are defined in the root docker-compose.yml.

   shell copy

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

   $cd metroflow
2. Configure environment variables

   Copy the example env file and set secrets. At minimum, generate a METROFLOW_SECRET_KEY and confirm the database URL.

   shell copy

   $cp .env.example .env

   # Edit .env: required keys:

   METROFLOW_SECRET_KEY=your-random-32-char-secret

   METROFLOW_DATABASE_URL=postgresql://metroflow:metroflow@db:5432/metroflow

   METROFLOW_PUBLIC_URL=http://localhost:4200
   !

   Warning: Never commit .env to version control. Use your secrets manager or CI variables in production deployments.

3. Start all services

   Docker Compose pulls images and starts the API, crawler, graph database, and workspace UI. First boot may take 2–3 minutes while images download.

   shell copy

   $docker compose up -d

   ✓ metroflow-api running

   ✓ metroflow-crawler running

   ✓ metroflow-ui running

   ✓ metroflow-db running
4. Open the workspace

   Navigate to the workspace UI in your browser. Sign in with the default admin credentials from .env, then change the password on first login.

   browser copy

   http://localhost:4200
5. Connect your first source

   In the workspace, open Settings → Connectors → Add source. Pick dbt and Snowflake (or Postgres for a zero-credential trial), paste credentials, and trigger an initial sync.

Verify installation

Confirm the API is reachable and all dependent services report healthy before connecting sources.

You can also tail crawler logs to watch the first sync after adding a connector:

Connect your first source

The fastest path to a populated graph is dbt + Snowflake. Metroflow reads your manifest and warehouse metadata, then links models to tables automatically.

1. Add Snowflake

In the workspace connector wizard, select Snowflake and provide read-only credentials. Metroflow ingests information_schema metadata only.

2. Add dbt

Point Metroflow at your dbt project directory or CI artifact. It parses manifest.json and catalog.json to build model-level lineage.

3. Run initial sync

Trigger a manual sync from the connector detail page or via the API. Within a few minutes you should see tables, models, and ref edges in the graph explorer.

Kubernetes (optional)

For production, use the official Helm chart. It mirrors the Compose topology with configurable replicas, ingress, and external Postgres.

See Deployment for ingress, TLS, external secrets, and horizontal scaling guidance.

Next steps

Your control plane is live. Continue with these guides to expand coverage and automate workflows.