Skip to main content

Docker Compose Setup

Complete guide to running Orange with Docker Compose for local development.

Prerequisites​

Overview​

Docker Compose manages all service dependencies:

  • PostgreSQL 16 - Main database
  • Redis 7 - Cache and Celery message broker
  • OpenTelemetry Collector - Metrics and trace collection

Initial Setup​

1. Clone Repository​

git clone https://github.com/equalcollective/santra-be.git
cd santra-be

2. Configure Environment​

# Copy environment template
cp .env.example .env

Edit .env with required values:

# Generate a secure secret key
SECRET_KEY=your-secret-key-here-change-in-production

# Azure Blob Storage (required for file uploads)
AZURE_STORAGE_CONNECTION_STRING=DefaultEndpointsProtocol=https;AccountName=...
AZURE_STORAGE_CONTAINER_NAME=report-uploads

# Create first admin user
FIRST_SUPERUSER_EMAIL=admin@example.com
FIRST_SUPERUSER_PASSWORD=changeme

# Optional: Disable telemetry for local dev
OTEL_ENABLED=false

See .env.example for complete documentation of all configuration options.

3. Start Services​

# Automated start (recommended)
bash scripts/start_dev_compose.sh

This script:

  • Starts all services in background
  • Waits for PostgreSQL to be ready
  • Shows you next steps

Manual start:

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

4. Install Python Dependencies​

# Create virtual environment and install dependencies
uv sync

5. Run Database Migrations​

# Apply all migrations
uv run alembic upgrade head

6. Start the API Server​

# Start with auto-reload
uv run uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

Or use the helper script:

bash scripts/run_dev.sh

7. Start Celery Worker (Optional)​

For background tasks like async report processing:

# In a new terminal
bash scripts/start_celery_worker.sh

Or manually:

uv run celery -A app.celery_app worker --loglevel=info

Service Details​

PostgreSQL​

Connection String:

postgresql://orange_user:orange_password@localhost:5432/orange_db

Default Credentials:

  • User: orange_user
  • Password: orange_password
  • Database: orange_db

Access:

# Connect via psql
docker compose -f docker-compose.dev.yml exec postgres psql -U orange_user -d orange_db

# Check health
docker compose -f docker-compose.dev.yml exec postgres pg_isready

Redis​

Connection String:

redis://localhost:6379/0

Access:

# Connect via redis-cli
docker exec -it santra-be-redis-1 redis-cli

# Test connection
docker exec -it santra-be-redis-1 redis-cli ping
# Should return: PONG

OpenTelemetry Collector​

Ports:

  • 4317 - OTLP gRPC receiver
  • 4318 - OTLP HTTP receiver

Configuration: See otel-collector-config.yaml in project root.

Enable in production:

# .env
OTEL_ENABLED=true
OTEL_EXPORTER_OTLP_ENDPOINT=https://ingest.us.signoz.cloud:443
SIGNOZ_ACCESS_TOKEN=your-token-here

Managing Services​

Check Status​

docker compose -f docker-compose.dev.yml ps

View Logs​

# All services
docker compose -f docker-compose.dev.yml logs -f

# Specific service
docker compose -f docker-compose.dev.yml logs -f postgres
docker compose -f docker-compose.dev.yml logs -f redis

Restart Services​

# All services
docker compose -f docker-compose.dev.yml restart

# Specific service
docker compose -f docker-compose.dev.yml restart postgres

Stop Services​

# Stop but keep data
docker compose -f docker-compose.dev.yml stop

# Stop and remove containers (keeps volumes)
docker compose -f docker-compose.dev.yml down

# Stop and remove everything including data
docker compose -f docker-compose.dev.yml down -v

Reset Everything​

# Nuclear option: remove all containers, volumes, networks
docker compose -f docker-compose.dev.yml down -v
docker compose -f docker-compose.dev.yml up -d
uv run alembic upgrade head

Next Steps​