Configuration

Overview

BR-ACC is configured using environment variables defined in a .env file. Copy .env.example to .env and customize the values for your deployment.

cp .env.example .env

Never commit your .env file to version control. It contains sensitive credentials and should remain local to each deployment.

Required Configuration

These settings must be configured before running BR-ACC:

Neo4j Database

NEO4J_PASSWORD

string

required

Password for the Neo4j database. Must be changed from default in production.

.env

NEO4J_PASSWORD=changeme

NEO4J_URI

string

default:"bolt://localhost:7687"

Neo4j connection URI. Use bolt://neo4j:7687 when running in Docker Compose.

.env

NEO4J_URI=bolt://localhost:7687

NEO4J_DATABASE

string

default:"neo4j"

Neo4j database name.

.env

NEO4J_DATABASE=neo4j

JWT Authentication

JWT_SECRET_KEY

string

required

Secret key for signing JWT tokens. Must be at least 32 characters in production.Generate a secure key:

openssl rand -hex 32

.env

JWT_SECRET_KEY=change-me-generate-with-openssl-rand-hex-32

Using a weak or default JWT secret allows attackers to forge authentication tokens. Always use a cryptographically secure random string in production.

CORS Origins

CORS_ORIGINS

string

default:"http://localhost:3000"

Allowed origins for CORS requests. Comma-separated list.

.env

# Development
CORS_ORIGINS=http://localhost:3000

# Production
CORS_ORIGINS=https://bracc.yourdomain.com

Do not use CORS_ORIGINS=* when allow_credentials is enabled. This is a security risk.

API Configuration

Server Settings

API_HOST

string

default:"0.0.0.0"

Host address for the API server.

.env

API_HOST=0.0.0.0

API_PORT

integer

default:"8000"

Port for the API server.

.env

API_PORT=8000

APP_ENV

string

default:"dev"

Application environment. Options: dev, staging, prod.

.env

APP_ENV=dev

LOG_LEVEL

string

default:"info"

Logging level. Options: debug, info, warning, error, critical.

.env

LOG_LEVEL=info

Authentication Settings

INVITE_CODE

string

default:""

Optional invite code required for user registration. Leave empty to allow open registration.

.env

INVITE_CODE=

Set to true in production to send session cookies only over HTTPS.

.env

# Development
AUTH_COOKIE_SECURE=false

# Production
AUTH_COOKIE_SECURE=true

The API uses cookie-based authentication with JWT tokens. The cookie name is bracc_session and has a TTL of 24 hours (configurable via jwt_expire_minutes in config.py:20).

Neo4j Memory Settings

These settings are critical for performance with large datasets. The defaults are suitable for development but must be increased for production.

NEO4J_HEAP_INITIAL

string

default:"512m"

Initial JVM heap size for Neo4j.

.env

# Development
NEO4J_HEAP_INITIAL=512m

# Production (40M+ nodes)
NEO4J_HEAP_INITIAL=4G

NEO4J_HEAP_MAX

string

default:"1G"

Maximum JVM heap size for Neo4j.

.env

# Development
NEO4J_HEAP_MAX=1G

# Production (40M+ nodes)
NEO4J_HEAP_MAX=8G

NEO4J_PAGECACHE

string

default:"512m"

Page cache size for Neo4j. This is the most important performance setting.

.env

# Development
NEO4J_PAGECACHE=512m

# Production (40M+ nodes)
NEO4J_PAGECACHE=12G

For production deployments with 40M+ nodes:

Use at least 32GB RAM (recommended: 64GB)
Set NEO4J_HEAP_INITIAL=4G, NEO4J_HEAP_MAX=8G, NEO4J_PAGECACHE=12G
See Production Deployment for details

Feature Flags

Product Tier

PRODUCT_TIER

string

default:"community"

Product tier. Options: community, professional, enterprise.

.env

PRODUCT_TIER=community

Pattern Detection

PATTERNS_ENABLED

boolean

default:"false"

Enable pattern detection features.

.env

PATTERNS_ENABLED=false

Pattern detection is a premium feature that identifies suspicious relationships in procurement data. See the Pattern Detection endpoint for details.

Public Access Mode

PUBLIC_MODE

boolean

default:"false"

Enable public access without authentication.

.env

PUBLIC_MODE=false

PUBLIC_ALLOW_PERSON

boolean

default:"false"

Allow public access to person entity pages.

.env

PUBLIC_ALLOW_PERSON=false

PUBLIC_ALLOW_ENTITY_LOOKUP

boolean

default:"false"

Allow public access to entity lookup.

.env

PUBLIC_ALLOW_ENTITY_LOOKUP=false

PUBLIC_ALLOW_INVESTIGATIONS

boolean

default:"false"

Allow public access to investigations.

.env

PUBLIC_ALLOW_INVESTIGATIONS=false

Pattern Detection Tuning

These settings control pattern detection algorithms. Only relevant when PATTERNS_ENABLED=true.

PATTERN_SPLIT_THRESHOLD_VALUE

float

default:"80000"

Threshold value for contract splitting detection.

.env

PATTERN_SPLIT_THRESHOLD_VALUE=80000

PATTERN_SPLIT_MIN_COUNT

integer

default:"3"

Minimum number of split contracts to trigger detection.

.env

PATTERN_SPLIT_MIN_COUNT=3

Threshold for shared resource detection (0.0-1.0).

.env

PATTERN_SHARE_THRESHOLD=0.6

PATTERN_SRP_MIN_ORGS

integer

default:"5"

Minimum organizations for Single Resource Provider pattern.

.env

PATTERN_SRP_MIN_ORGS=5

PATTERN_INEXIG_MIN_RECURRENCE

integer

default:"3"

Minimum recurrence for Inexigibilidade pattern.

.env

PATTERN_INEXIG_MIN_RECURRENCE=3

PATTERN_MAX_EVIDENCE_REFS

integer

default:"50"

Maximum evidence references per pattern.

.env

PATTERN_MAX_EVIDENCE_REFS=50

Frontend Configuration

VITE_API_URL

string

default:"http://localhost:8000"

API URL for the frontend. Used during development only.

.env

# Development
VITE_API_URL=http://localhost:8000

VITE_PUBLIC_MODE

boolean

default:"false"

Enable public mode in the frontend.

.env

VITE_PUBLIC_MODE=false

VITE_PATTERNS_ENABLED

boolean

default:"false"

Enable pattern detection UI in the frontend.

.env

VITE_PATTERNS_ENABLED=false

In production, the frontend uses Caddy as a reverse proxy with relative paths. The VITE_API_URL is only used during development.

Optional: External Integrations

Google Cloud (BigQuery)

GOOGLE_APPLICATION_CREDENTIALS

string

Path to Google Cloud service account JSON file. Required for Base dos Dados / TSE BigQuery integration.

.env

GOOGLE_APPLICATION_CREDENTIALS=path/to/service-account.json

ETL Source Tokens

WORLD_BANK_API_KEY

string

API key for World Bank data sources.

.env

WORLD_BANK_API_KEY=your-api-key

EU_SANCTIONS_TOKEN

string

Token for EU sanctions list API.

.env

EU_SANCTIONS_TOKEN=your-token

Configuration in Code

All environment variables are loaded via Pydantic settings in api/src/bracc/config.py:7-56. The configuration class provides type validation and defaults:

config.py

class Settings(BaseSettings):
    neo4j_uri: str = "bolt://localhost:7687"
    neo4j_user: str = "neo4j"
    neo4j_password: str = "changeme"
    neo4j_database: str = "neo4j"

    api_host: str = "0.0.0.0"
    api_port: int = 8000
    log_level: str = "info"
    app_env: str = "dev"

    jwt_secret_key: str = "change-me-in-production"
    jwt_algorithm: str = "HS256"
    jwt_expire_minutes: int = 1440
    rate_limit_anon: str = "60/minute"
    rate_limit_auth: str = "300/minute"
    invite_code: str = ""
    cors_origins: str = "http://localhost:3000"
    auth_cookie_name: str = "bracc_session"
    auth_cookie_secure: bool = False
    auth_cookie_samesite: Literal["lax", "strict", "none"] = "lax"
    # ... more settings

Environment-Specific Configuration

Development

.env

APP_ENV=dev
LOG_LEVEL=debug
AUTH_COOKIE_SECURE=false
CORS_ORIGINS=http://localhost:3000
VITE_API_URL=http://localhost:8000

# Use default memory settings
NEO4J_HEAP_INITIAL=512m
NEO4J_HEAP_MAX=1G
NEO4J_PAGECACHE=512m

Production

.env

APP_ENV=prod
LOG_LEVEL=info
AUTH_COOKIE_SECURE=true
CORS_ORIGINS=https://bracc.yourdomain.com

# Use strong secrets
NEO4J_PASSWORD=$(openssl rand -hex 32)
JWT_SECRET_KEY=$(openssl rand -hex 32)

# Use production memory settings
NEO4J_HEAP_INITIAL=4G
NEO4J_HEAP_MAX=8G
NEO4J_PAGECACHE=12G

# Optional: Enable invite code
INVITE_CODE=your-invite-code

Next Steps

Docker Setup

Set up Docker Compose

Production Deployment

Deploy to production

Security

Security best practices

Data Sources

Explore available data sources

Get Started

Data Model

Deployment

ETL Pipelines

Querying Data

Legal & Ethics

Overview

Required Configuration

Neo4j Database

JWT Authentication

CORS Origins

API Configuration

Server Settings

Authentication Settings

Neo4j Memory Settings

Feature Flags

Product Tier

Pattern Detection

Public Access Mode

Pattern Detection Tuning

Frontend Configuration

Optional: External Integrations

Google Cloud (BigQuery)

ETL Source Tokens

Configuration in Code

Environment-Specific Configuration

Development

Production

Next Steps

Docker Setup

Production Deployment

Security

Data Sources

Build docs developers (and LLMs) love

Get Started

Data Model

Deployment

ETL Pipelines

Querying Data

Legal & Ethics

​Overview

​Required Configuration

​Neo4j Database

​JWT Authentication

​CORS Origins

​API Configuration

​Server Settings

​Authentication Settings

​Neo4j Memory Settings

​Feature Flags

​Product Tier

​Pattern Detection

​Public Access Mode

​Pattern Detection Tuning

​Frontend Configuration

​Optional: External Integrations

​Google Cloud (BigQuery)

​ETL Source Tokens

​Configuration in Code

​Environment-Specific Configuration

​Development

​Production

​Next Steps

Docker Setup

Production Deployment

Security

Data Sources

Build docs developers (and LLMs) love

Overview

Required Configuration

Neo4j Database

JWT Authentication

CORS Origins

API Configuration

Server Settings

Authentication Settings

Neo4j Memory Settings

Feature Flags

Product Tier

Pattern Detection

Public Access Mode

Pattern Detection Tuning

Frontend Configuration

Optional: External Integrations

Google Cloud (BigQuery)

ETL Source Tokens

Configuration in Code

Environment-Specific Configuration

Development

Production

Next Steps