Skip to main content

​
Overview

BR-ACC uses Docker Compose to orchestrate four main services:
  • Neo4j - Graph database (5-community with APOC)
  • API - FastAPI backend
  • Frontend - Vite/React interface
  • ETL - Data ingestion pipeline (optional)
The ETL service uses a Docker Compose profile and only runs when explicitly activated. See the ETL documentation for details.

​
Quick Start

1

Clone the repository

git clone https://github.com/your-org/bracc.git
cd bracc
2

Create environment file

Copy the example environment file and configure it:
cp .env.example .env
Change NEO4J_PASSWORD and JWT_SECRET_KEY before running in production. See Configuration for details.
3

Start the services

docker compose up -d
This starts Neo4j, API, and Frontend. The API waits for Neo4j to be healthy before starting.
4

Verify services are running

Check service status:
docker compose ps
You should see all three services with status “Up (healthy)”.
5

Access the application

​
Service Configuration

​
Neo4j Database

The Neo4j service is configured with APOC plugins and health checks:
docker-compose.yml
neo4j:
  container_name: bracc-neo4j
  image: neo4j:5-community
  ports:
    - "7474:7474"  # Browser UI
    - "7687:7687"  # Bolt protocol
  environment:
    NEO4J_AUTH: neo4j/${NEO4J_PASSWORD}
    NEO4J_PLUGINS: '["apoc"]'
    NEO4J_server_memory_heap_initial__size: ${NEO4J_HEAP_INITIAL:-512m}
    NEO4J_server_memory_heap_max__size: ${NEO4J_HEAP_MAX:-1G}
    NEO4J_server_memory_pagecache_size: ${NEO4J_PAGECACHE:-512m}
    NEO4J_dbms_memory_transaction_total_max: 1G
  volumes:
    - neo4j-data:/data
    - ./infra/neo4j/import:/var/lib/neo4j/import
    - ./infra/neo4j/init.cypher:/var/lib/neo4j/init.cypher
  healthcheck:
    test: ["CMD", "cypher-shell", "-u", "neo4j", "-p", "${NEO4J_PASSWORD}", "RETURN 1"]
    interval: 10s
    timeout: 5s
    retries: 8
The default memory settings are suitable for development. For production with 40M+ nodes, see Production Deployment.

​
API Service

The FastAPI backend connects to Neo4j and exposes port 8000:
docker-compose.yml
api:
  build: ./api
  ports:
    - "8000:8000"
  environment:
    NEO4J_URI: bolt://neo4j:7687
    NEO4J_USER: neo4j
    NEO4J_PASSWORD: ${NEO4J_PASSWORD}
    JWT_SECRET_KEY: ${JWT_SECRET_KEY:-change-me-generate-with-openssl-rand-hex-32}
    INVITE_CODE: ${INVITE_CODE:-}
    LOG_LEVEL: ${LOG_LEVEL:-info}
    APP_ENV: ${APP_ENV:-dev}
    CORS_ORIGINS: ${CORS_ORIGINS:-http://localhost:3000}
  depends_on:
    neo4j:
      condition: service_healthy
  healthcheck:
    test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://localhost:8000/health')"]
    interval: 10s
    timeout: 5s
    retries: 8
    start_period: 20s

​
Frontend Service

The Vite/React frontend runs on port 3000:
docker-compose.yml
frontend:
  build: ./frontend
  ports:
    - "3000:3000"
  environment:
    VITE_API_URL: ${VITE_API_URL:-http://localhost:8000}
  depends_on:
    api:
      condition: service_healthy

​
ETL Service (Optional)

The ETL service uses a Docker profile and only runs when explicitly activated:
docker-compose.yml
etl:
  build: ./etl
  profiles: ["etl"]
  working_dir: /workspace
  environment:
    NEO4J_URI: bolt://neo4j:7687
    NEO4J_USER: neo4j
    NEO4J_PASSWORD: ${NEO4J_PASSWORD}
    PYTHONUNBUFFERED: "1"
  volumes:
    - .:/workspace
  depends_on:
    neo4j:
      condition: service_healthy
To run ETL operations: 
# Run a specific ETL task
docker compose run --rm etl python -m etl.tasks.load_contracts

# Or start the ETL service interactively
docker compose --profile etl run --rm etl bash

​
Common Operations

​
View Logs

docker compose logs -f

​
Restart Services

docker compose restart

​
Stop and Clean Up

docker compose down
Using docker compose down -v will delete all data in the Neo4j database. Only use this if you want to start fresh.

​
Database Backup

To backup the Neo4j database: 
# Create a backup
docker compose exec neo4j neo4j-admin database dump neo4j --to-path=/data

# Copy backup to host
docker cp bracc-neo4j:/data/neo4j.dump ./backup-$(date +%Y%m%d).dump

​
Database Restore

To restore from a backup: 
# Stop the database
docker compose stop neo4j

# Copy backup to container
docker cp ./backup.dump bracc-neo4j:/data/neo4j.dump

# Restore the database
docker compose exec neo4j neo4j-admin database load neo4j --from-path=/data

# Restart the database
docker compose start neo4j

​
Health Checks

All services implement health checks to ensure proper startup order:
  • Neo4j: Validates connection using cypher-shell
  • API: Checks the /health endpoint
  • Frontend: Depends on API health
  • ETL: Depends on Neo4j health
You can check service health with: 
docker compose ps
Healthy services show “Up (healthy)” in the status column.

​
Troubleshooting

​
Neo4j fails to start

If Neo4j fails the health check: 
# Check Neo4j logs
docker compose logs neo4j

# Common issues:
# 1. Insufficient memory - increase NEO4J_HEAP_MAX
# 2. Port conflict - ensure 7474 and 7687 are available
# 3. Invalid password - check NEO4J_PASSWORD in .env

​
API cannot connect to Neo4j

If the API fails to connect: 
# Verify Neo4j is healthy
docker compose ps neo4j

# Check API logs for connection errors
docker compose logs api

# Ensure NEO4J_PASSWORD matches in .env

​
Frontend cannot reach API

If the frontend shows connection errors: 
# Verify API is healthy
docker compose ps api

# Check VITE_API_URL in .env
# For development: http://localhost:8000
# For production: https://api.yourdomain.com

​
Next Steps

Configuration

Configure environment variables and settings

Production Deployment

Deploy BR-ACC to production

ETL Pipeline

Set up data ingestion

API Reference

Explore the API endpoints

Build docs developers (and LLMs) love

Get started for freeTalk to us