Skip to content

Full Installation Guide

This guide provides complete instructions for setting up a CalcBridge development environment with all components, including the API server, database, cache, workers, and optional frontend.

System Requirements

Minimum Requirements

Component Requirement
CPU 4 cores
RAM 8 GB
Disk 20 GB free space
OS macOS 12+, Ubuntu 20.04+, Windows 10+ (WSL2)

Software Dependencies

Software Version Required
Python 3.11 or 3.12 Yes
Docker 24.0+ Yes
Docker Compose 2.20+ Yes
Git 2.30+ Yes
Node.js 18+ Optional (frontend)
npm 9+ Optional (frontend)

Step 1: Clone the Repository

# Clone the repository
git clone https://github.com/InsightCapital/calcbridge.git
cd calcbridge

# Verify you're in the right directory
ls -la
# You should see: docker-compose.yml, pyproject.toml, src/, etc.

Step 2: Create Python Virtual Environment

# Create virtual environment with Python 3.11+
python3.11 -m venv .venv

# Activate the environment
source .venv/bin/activate

# Verify Python version
python --version  # Should show 3.11.x or 3.12.x

# Create virtual environment
python -m venv .venv

# Activate the environment
.venv\Scripts\Activate.ps1

# Verify Python version
python --version

# Create virtual environment
python3.11 -m venv .venv

# Activate the environment
source .venv/bin/activate

# Verify Python version
python --version

Step 3: Install Python Dependencies

# Install all dependencies (recommended for development)
pip install -e ".[dev,test]"

# Or install from requirements files
pip install -r requirements.txt        # Production only
pip install -r requirements-dev.txt    # Development + testing

Dependency Groups

Group Includes
Base FastAPI, SQLAlchemy, Celery, pandas, openpyxl
dev ruff, mypy, pre-commit
test pytest, pytest-asyncio, testcontainers, hypothesis
loadtest locust, gevent

Step 4: Set Up Environment Variables

Copy the example environment file and customize it:

# Copy the example file
cp .env.example .env

# Open in your editor
code .env  # or vim .env, nano .env

Required Changes for Production

The following values MUST be changed before deploying to production:

# Generate secure keys
python -c "import secrets; print(secrets.token_urlsafe(32))"

Update these values in .env: 

JWT_SECRET_KEY=<generated-secure-key>
ENCRYPTION_MASTER_KEY=<generated-secure-key>

Essential Configuration

# Environment
ENVIRONMENT=development
DEBUG=false
LOG_LEVEL=INFO

# Database (matches docker-compose.yml)
DATABASE_URL=postgresql+psycopg://calcbridge:calcbridge_dev@localhost:5433/calcbridge

# Cache (matches docker-compose.yml)
VALKEY_HOST=localhost
VALKEY_PORT=6380

# Security (CHANGE IN PRODUCTION)
JWT_SECRET_KEY=change-me-in-production-use-a-secure-random-key
ENCRYPTION_MASTER_KEY=change-me-in-production-use-a-secure-random-key

Step 5: Start Infrastructure Services

Start PostgreSQL and Valkey using Docker Compose:

# Start core infrastructure
docker compose up -d postgres valkey

# Verify services are healthy
docker compose ps

# View logs if needed
docker compose logs -f postgres valkey

Expected Output

NAME                  STATUS          PORTS
calcbridge-postgres   Up (healthy)    0.0.0.0:5433->5432/tcp
calcbridge-valkey     Up (healthy)    0.0.0.0:6380->6379/tcp

Service Details

Service Container Port (Host) Port (Container)
PostgreSQL calcbridge-postgres 5433 5432
Valkey calcbridge-valkey 6380 6379

Step 6: Run Database Migrations

Apply the SQL migrations to set up the database schema:

# Apply all migrations in order
for migration in db/migrations/V*.sql; do
  echo "Applying: $migration"
  PGPASSWORD=calcbridge_dev psql -h localhost -p 5433 -U calcbridge -d calcbridge -f "$migration"
done

# Copy migrations into container and apply
for migration in db/migrations/V*.sql; do
  echo "Applying: $migration"
  docker exec -i calcbridge-postgres psql -U calcbridge -d calcbridge < "$migration"
done

# Apply a specific migration
./scripts/apply_migration_docker.sh db/migrations/V001__initial_schema.sql

Verify Migration Success

# Connect to database and list tables
PGPASSWORD=calcbridge_dev psql -h localhost -p 5433 -U calcbridge -d calcbridge -c "\dt"

Step 7: Start the API Server

Launch the FastAPI server with development settings:

# Development mode with hot reload
PYTHONPATH=. uvicorn src.api.main:app --reload --port 8000

# Or with more workers for testing
PYTHONPATH=. uvicorn src.api.main:app --workers 4 --port 8000

Verify the Server

  1. Health Check: http://localhost:8000/health
  2. API Documentation: http://localhost:8000/docs
  3. OpenAPI Schema: http://localhost:8000/openapi.json

Server Running

INFO:     Uvicorn running on http://127.0.0.1:8000
INFO:     Started reloader process [12345]
INFO:     Started server process [12346]
INFO:     Waiting for application startup.
INFO:     Application startup complete.

Step 8: Start Celery Workers (Optional)

For background task processing (Excel parsing, calculations):

# Handles parse, export tasks
celery -A src.workers.celery_app worker \
  --loglevel=INFO \
  --concurrency=4 \
  --queues=default,parse,export

# Handles CPU-intensive calculations
celery -A src.workers.celery_app worker \
  --loglevel=INFO \
  --concurrency=2 \
  --queues=calculate,priority

# Start all workers via Docker Compose
docker compose up -d celery-worker celery-worker-calc celery-beat

Step 9: Start the Frontend (Optional)

If you want to use the web interface:

# Navigate to frontend directory
cd frontend

# Install dependencies
npm install

# Start development server
npm run dev

# Access at http://localhost:3002

Frontend Port

The frontend runs on port 3002 by default to avoid conflicts with other services.

Verify Installation

Run the test suite to verify everything is working:

# Run unit tests (no Docker required)
PYTHONPATH=. pytest tests/unit/ -v

# Run integration tests (requires Docker)
PYTHONPATH=. pytest tests/integration/ -v

# Run all tests with coverage
PYTHONPATH=. pytest tests/ --cov=src --cov-report=html

Quick Smoke Test

# Test API health
curl http://localhost:8000/health

# Test API readiness (database + cache)
curl http://localhost:8000/health/ready

# Register a test user
curl -X POST http://localhost:8000/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email":"test@example.com","password":"TestPass123!","full_name":"Test User","organization_name":"Test Org"}'

Docker Compose Services Reference

The full docker-compose.yml includes these services:

Service Profile Purpose
postgres default PostgreSQL 16 database
valkey default Valkey cache (Redis-compatible)
api default FastAPI application
celery-worker default Default task worker
celery-worker-calc default Calculation worker
celery-worker-dlq default Dead letter queue worker
celery-beat default Task scheduler
flower monitoring Celery monitoring UI
prometheus monitoring Metrics collection
grafana monitoring Metrics visualization
alertmanager monitoring Alert routing

Starting Different Profiles

# Core services only
docker compose up -d postgres valkey

# All default services
docker compose up -d

# With monitoring stack
docker compose --profile monitoring up -d

Directory Structure

After installation, your directory should look like this:

calcbridge/
├── .venv/                  # Python virtual environment
├── .env                    # Environment configuration
├── docker-compose.yml      # Service orchestration
├── pyproject.toml          # Python project config
├── src/
│   ├── api/               # FastAPI application
│   ├── calculations/      # Formula engine
│   ├── core/              # Core utilities
│   ├── db/                # Database layer
│   ├── imports/           # Excel parser
│   ├── services/          # Business services
│   └── workers/           # Celery tasks
├── db/
│   └── migrations/        # SQL migrations
├── tests/
│   ├── unit/             # Unit tests
│   ├── integration/      # Integration tests
│   └── security/         # Security tests
├── frontend/             # Next.js frontend
└── config/               # Prometheus, Grafana configs

Next Steps