Configuration¶

VERA is configured through environment variables, typically set in a .env file at the project root. Docker Compose reads this file automatically.

Environment Variables¶

Database¶

Variable	Default	Description
`DATABASE_URL`	`postgresql+psycopg://vera:vera@postgres:5432/vera`	PostgreSQL connection string (async driver)
`POSTGRES_USER`	`vera`	PostgreSQL user (used by the `postgres` container)
`POSTGRES_PASSWORD`	`vera`	PostgreSQL password
`POSTGRES_DB`	`vera`	PostgreSQL database name

Celery / Redis¶

Variable	Default	Description
`CELERY_BROKER_URL`	`redis://:vera_redis@redis:6379/0`	Redis URL for Celery task broker
`CELERY_RESULT_BACKEND`	`redis://:vera_redis@redis:6379/0`	Redis URL for Celery result backend
`REDIS_PASSWORD`	`vera_redis`	Redis AUTH password
`STUCK_TASK_TIMEOUT_MINUTES`	`30`	Minutes before a stuck processing task is recovered

Ollama (AI Summaries)¶

Variable	Default	Description
`OLLAMA_URL`	`http://ollama:11434`	Ollama API endpoint
`OLLAMA_MODEL`	`llama3.1`	Default model for AI summaries
`OLLAMA_TIMEOUT`	`300`	Timeout in seconds for Ollama requests

Ollama is optional

VERA works without Ollama. If the Ollama service is unreachable, AI summaries are unavailable but all other features (upload, OCR, review, export) continue normally.

Upload & Retention¶

Variable	Default	Description
`MAX_UPLOAD_MB`	`25`	Maximum upload file size in megabytes
`RETENTION_DAYS`	`30`	Number of days to retain documents before cleanup
`UPLOAD_RATE_LIMIT`	`10/minute`	Rate limit for the upload endpoint (SlowAPI format)
`DATA_DIR`	`/data`	Directory for uploaded files (mounted as a volume)

Authentication (Hub)¶

Variable	Default	Description
`HUB_BASE_URL`	`http://hub:8000`	Base URL of the Hub authentication service
`HUB_AUTH_API_KEY`	(empty)	API key for Hub service-to-service auth

Authentication required

Hub is required for all deployments. Both HUB_BASE_URL and HUB_AUTH_API_KEY must be set. VERA will reject requests if Hub is not configured or unreachable. There is no unauthenticated mode.

Credential Caching (Hub Outage Resilience)¶

VERA caches validated credentials in Redis using HMAC-keyed hashes (no plaintext passwords are stored). If Hub becomes unreachable during a login attempt, VERA checks the credential cache and allows re-authentication for up to 4 hours after the last successful Hub validation.

This means users who have recently logged in can continue working during a brief Hub outage without being locked out.

Behaviour	Detail
Cache location	Redis (same instance as sessions and Celery broker)
TTL	4 hours from last successful Hub validation
Security	Credentials stored as HMAC-SHA256 hash keyed with `HUB_AUTH_API_KEY`
Logout	Cache entry removed on explicit logout

Session Revocation¶

VERA periodically checks Hub to verify that session users are still active. If an admin disables or deletes a user in Hub, VERA will reject their requests within 5 minutes (the user-status cache TTL). This check runs automatically — no configuration is required.

Note

During a Hub outage, the user-status check fails open — existing sessions remain valid. This is a deliberate trade-off to avoid locking out all users during infrastructure issues.

Security¶

Variable	Default	Description
`SECURE_COOKIES`	`true`	Set session cookies with `Secure` flag. Disable (`false`) for local HTTP-only development
`LOG_LEVEL`	`INFO`	Logging level (`DEBUG`, `INFO`, `WARNING`, `ERROR`). Use `DEBUG` only for development

Networking & CORS¶

Variable	Default	Description
`CORS_ORIGINS`	`http://localhost:3000`	Comma-separated list of allowed CORS origins
`BACKEND_PORT`	`4000`	Host port mapped to the backend container
`FRONTEND_PORT`	`3000`	Host port mapped to the frontend container
`NEXT_PUBLIC_API_BASE_URL`	`http://localhost:4000`	Backend URL used by the frontend (client-side)

Resource Limits¶

Variable	Default	Description
`BACKEND_MEMORY_LIMIT`	`1G`	Memory limit for the backend container
`WORKER_MEMORY_LIMIT`	`4G`	Memory limit for the Celery worker container
`WORKER_CPU_LIMIT`	`2.0`	CPU limit for the Celery worker container

Backup¶

Variable	Default	Description
`BACKUP_HOST_DIR`	`./backups`	Host directory for database backups
`BACKUP_RETENTION_DAYS`	`7`	Days to keep backup files
`BACKUP_INTERVAL_SECONDS`	`86400`	Interval between automated backups (default: 24 hours)

Docker Secrets¶

VERA supports Docker secrets for sensitive values. The hub_auth_api_key secret is configured in docker-compose.yml:

secrets:
  hub_auth_api_key:
    file: ${HUB_AUTH_API_KEY_FILE:-./secrets/hub_auth_api_key}

To set up the secret:

mkdir -p secrets
echo "your-hub-api-key-here" > secrets/hub_auth_api_key
chmod 600 secrets/hub_auth_api_key

Secrets directory

The secrets/ directory is gitignored. Never commit API keys to version control.

.env Setup¶

Copy the example and edit:

cp .env.example .env

A minimal .env for local development:

# Database
DATABASE_URL=postgresql+psycopg://vera:vera@postgres:5432/vera
POSTGRES_PASSWORD=vera

# Redis / Celery
REDIS_PASSWORD=vera_redis
CELERY_BROKER_URL=redis://:vera_redis@redis:6379/0
CELERY_RESULT_BACKEND=redis://:vera_redis@redis:6379/0

# Ollama (optional)
OLLAMA_URL=http://ollama:11434
OLLAMA_MODEL=llama3.1

# Hub auth (required)
HUB_BASE_URL=http://hub:8000
HUB_AUTH_API_KEY=your-key-here

# CORS
CORS_ORIGINS=http://localhost:3000

Database Migrations (Alembic)¶

VERA uses Alembic for PostgreSQL schema management. Always run migrations after pulling new code or on first startup:

docker compose exec backend alembic upgrade head

Check current migration status:

docker compose exec backend alembic current

View migration history:

docker compose exec backend alembic history --verbose

Always run migrations

Skipping alembic upgrade head after a code update can cause runtime errors if the database schema is out of date. The backend does not auto-migrate on startup.