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

> Learn to configure Flowsint for production with Docker Compose. Deploy the API, UI, Neo4j, and Redis efficiently. Follow our complete guide to set up your persistent Docker network.

- Repository: [reconurge/flowsint](https://github.com/reconurge/flowsint)
- Tags: how-to-guide
- Published: 2026-06-05

---

**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`](https://github.com/reconurge/flowsint/blob/main/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`](https://github.com/reconurge/flowsint/blob/main/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`](https://github.com/reconurge/flowsint/blob/main/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`](https://github.com/reconurge/flowsint/blob/main/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`](https://github.com/reconurge/flowsint/blob/main/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:

```bash
cp .env.example .env

```

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

```text
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`](https://github.com/reconurge/flowsint/blob/main/flowsint-api/src/flowsint_api/config.py) and the Vite front-end build configuration in [`flowsint-app/src/config.ts`](https://github.com/reconurge/flowsint/blob/main/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:

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

```

Launch the stack in detached mode:

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

```

Verify that all containers are healthy:

```bash
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:

```bash
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:

```bash
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:

```bash
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:

```bash
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`](https://github.com/reconurge/flowsint/blob/main/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`](https://github.com/reconurge/flowsint/blob/main/config.py) and [`config.ts`](https://github.com/reconurge/flowsint/blob/main/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`](https://github.com/reconurge/flowsint/blob/main/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`](https://github.com/reconurge/flowsint/blob/main/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`](https://github.com/reconurge/flowsint/blob/main/flowsint-api/src/flowsint_api/config.py), and the front-end reads `VITE_API_URL` from [`flowsint-app/src/config.ts`](https://github.com/reconurge/flowsint/blob/main/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.