How to Configure Flowsint for Production Using Docker Compose: A Complete Guide

To configure Flowsint for production using Docker Compose, copy the .env.example file to .env, populate the required secrets, and run docker compose -f docker-compose.prod.yml up -d to launch the API, UI, Neo4j, Redis, and optional worker services behind a persistent Docker network.

Flowsint is an open-source intelligence platform that orchestrates graph-based data flows inside containers. The reconurge/flowsint repository ships with a dedicated docker-compose.prod.yml file that pins immutable service images and isolates the production network. In this guide you will learn exactly how to configure Flowsint for production using Docker Compose, referencing the actual source paths and commands used by the project maintainers.

Architecture and Prerequisites

Before you deploy, ensure Docker Engine and Docker Compose are installed on your host. The production stack defined in docker-compose.prod.yml creates a dedicated bridge network named flowsint_net and mounts a named volume called neo4j_data for graph persistence.

The stack is composed of the following services:

• flowsint-api – The FastAPI backend (ghcr.io/reconurge/flowsint-api:latest) defined in flowsint-api/pyproject.toml. It exposes GraphQL endpoints and handles data ingestion, reading settings such as DATABASE_URL and API_SECRET_KEY from flowsint-api/src/flowsint_api/config.py.
• flowsint-app – The React/Vite front-end (ghcr.io/reconurge/flowsint-app:latest). It uses the VITE_API_URL variable sourced from flowsint-app/src/config.ts.
• neo4j – The graph database (neo4j:5) that stores nodes, edges, and enrichment results. Its data directory is bound to the neo4j_data volume.
• redis – The caching layer (redis:7-alpine) used for sessions and background job queues, reachable at redis://redis:6379.
• worker (optional) – The background worker (ghcr.io/reconurge/flowsint-worker:latest) that executes long-running enrichment tasks using the same database and cache connections as the API.

Environment Configuration

Production secrets and hostnames are injected at runtime through an .env file. The repository provides a template in .env.example.

1. Copy the template:

cp .env.example .env

2. Edit .env with production values. At minimum, set the following variables:

DATABASE_URL=bolt://neo4j:7687
NEO4J_AUTH=neo4j/your_strong_password
REDIS_URL=redis://redis:6379
API_SECRET_KEY=your_super_secret_key
VITE_API_URL=https://your-domain.com/api
HOST=0.0.0.0
PORT=80

These values are consumed directly by the FastAPI backend configuration logic in flowsint-api/src/flowsint_api/config.py and the Vite front-end build configuration in flowsint-app/src/config.ts. Never commit the .env file to version control.

Deploying the Production Stack

With your environment file in place at the repository root, you can bring the services online.

Pull the latest images first:

docker compose -f docker-compose.prod.yml pull

Launch the stack in detached mode:

docker compose -f docker-compose.prod.yml up -d

Verify that all containers are healthy:

docker compose -f docker-compose.prod.yml ps

The API will be available at http://<host>/api and the UI at http://<host>. For public-facing deployments, place a TLS-terminating reverse proxy in front of the exposed ports.

Updating and Scaling Services

When a new image tag is released, update the deployment without touching the database or cache:

docker compose -f docker-compose.prod.yml pull
docker compose -f docker-compose.prod.yml up -d --no-deps --build

The --no-deps flag ensures only the changed service containers restart, leaving Neo4j and Redis running.

To scale the API or worker horizontally, use the --scale flag:

docker compose -f docker-compose.prod.yml up -d --scale flowsint-api=3 --scale worker=2

Data Persistence, Backups, and Migrations

The neo4j_data named volume survives container restarts. To create a logical backup of the graph database, run:

docker exec -i flowsint_neo4j \
  neo4j-admin dump --database=neo4j --to=/backups/neo4j.dump
docker cp flowsint_neo4j:/backups/neo4j.dump ./backup/

Database schema migrations live in the neo4j-migrations/ directory and are managed by flowsint_core.migrations. Execute them once before the first production start:

docker compose -f docker-compose.prod.yml run --rm flowsint-api \
  python -m flowsint_core.migrations

Summary

• The production topology is defined in docker-compose.prod.yml and uses pinned images for reproducible deployments.
• Secrets are supplied through an .env file derived from .env.example; the API and UI read these values via config.py and config.ts respectively.
• Neo4j persists graph data to the neo4j_data volume, while Redis handles caching and queues.
• Deploy with docker compose -f docker-compose.prod.yml up -d, update with pull followed by up -d --no-deps --build, and scale services with the --scale flag.
• Back up Neo4j with neo4j-admin dump and apply schema migrations via python -m flowsint_core.migrations before going live.

Frequently Asked Questions

Do I need to modify docker-compose.prod.yml before deploying?

No. The file is designed to work out of the box as long as you provide a valid .env file at the repository root. You only need to edit the Compose file if you are adding custom networks, changing published ports, or integrating an external reverse proxy.

How do I back up the Neo4j graph database?

Use the neo4j-admin dump command inside the running Neo4j container, then copy the dump file to your host with docker cp. The data itself is stored in the neo4j_data Docker volume, so the graph survives container restarts even without an immediate backup.

Can I scale the API or worker independently?

Yes. The docker-compose.prod.yml stack supports horizontal scaling via the --scale flag. For example, running --scale flowsint-api=3 creates three API containers behind the internal Docker network load balancer without affecting the database or cache.

Where does Flowsint load environment variables from?

The FastAPI backend loads variables through flowsint-api/src/flowsint_api/config.py, and the front-end reads VITE_API_URL from flowsint-app/src/config.ts. Both sources expect values to be present in the host environment or in an .env file that Docker Compose injects at container start-up.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}