Getting Started¶

This guide walks you through setting up a complete Carbon Connect development environment from scratch. By the end, you will have the backend API server, Celery workers, and the frontend application running locally.

Prerequisites¶

Before you begin, ensure the following tools are installed on your machine:

Tool	Minimum Version	Purpose
Python	3.11+	Backend runtime; required for type hints and asyncio features
Poetry	1.7+	Python dependency management (`pip install poetry`)
Node.js	18+	Frontend runtime (Next.js, React)
npm	9+	Frontend package management (bundled with Node.js)
Docker Desktop	4.x	Containerized services (PostgreSQL, Valkey, Meilisearch)
Git	2.x	Version control

Windows Users

The project uses PostgreSQL on port 5433 (not the default 5432) to avoid conflicts with local Windows PostgreSQL installations. This is already configured in the Docker Compose file and .env template.

Step 1 -- Clone the Repository¶

git clone https://github.com/Carbon-Connect-Granted/carbon-connect-vrci.git
cd carbon-connect-vrci

Step 2 -- Start Docker Services¶

The backend depends on three core services running in Docker containers: PostgreSQL (with pgvector), Valkey (Redis-compatible cache), and Meilisearch (full-text search).

# Start core services in the background
docker compose up -d

# Verify all three containers are healthy
docker compose ps

You should see three containers running: granted_carbon_postgres, granted_carbon_valkey, and granted_carbon_meilisearch.

Dev Tools Profile

For database and cache management UIs, start the dev profile:

docker compose --profile dev up -d

This adds Adminer (database UI on port 8080) and Valkey Commander (cache UI on port 8081).

For more details on Docker services, see the Docker Services page.

Step 3 -- Configure Environment Variables¶

Create a .env file in the project root by copying the template values below:

.env

# Application
APP_ENV=development
APP_DEBUG=true
APP_SECRET_KEY=dev-secret-key-change-in-production

# PostgreSQL (port 5433 avoids Windows conflict)
POSTGRES_HOST=localhost
POSTGRES_PORT=5433
POSTGRES_DB=grant_engine
POSTGRES_USER=grant_user
POSTGRES_PASSWORD=grant_password_dev

# Valkey / Redis
REDIS_URL=redis://localhost:6379/0

# Meilisearch
MEILI_HOST=http://localhost:7700
MEILI_MASTER_KEY=meilisearch_dev_master_key_change_in_prod

# JWT Authentication
JWT_SECRET_KEY=jwt-dev-secret-key-change-in-production
JWT_ACCESS_TOKEN_EXPIRE_MINUTES=30
JWT_REFRESH_TOKEN_EXPIRE_DAYS=7

# Embeddings
EMBEDDING_MODEL=all-mpnet-base-v2
EMBEDDING_DIMENSION=768

# Claude API (required for AI application generation)
CLAUDE_API_KEY=your-anthropic-api-key
CLAUDE_MODEL=claude-sonnet-4-20250514

# Climatiq API (required for carbon calculations)
CLIMATIQ_API_KEY=your-climatiq-api-key

API Keys

The CLAUDE_API_KEY and CLIMATIQ_API_KEY are required for AI and carbon features respectively. Sign up at:

Anthropic Claude: console.anthropic.com
Climatiq: climatiq.io

The platform will function without these keys, but AI application generation and carbon calculations will be disabled.

For a full reference of all environment variables, see the Environment Variables page.

Step 4 -- Backend Setup¶

Install Python Dependencies¶

# Install all dependencies including dev dependencies
poetry install

# Verify the installation
poetry run python --version  # Should show Python 3.11+

Run Database Migrations¶

Apply all Alembic migrations to set up the database schema:

# Apply all migrations
poetry run alembic upgrade head

# Verify migration status
poetry run alembic current

First-Time Migration

The migration automatically creates the pgvector extension and all required tables: tenants, users, companies, grants, matches, applications, and supporting tables.

Install Pre-commit Hooks¶

# Install git hooks for secret detection and code quality
poetry run pre-commit install

Start the API Server¶

# Start FastAPI with hot-reload
poetry run uvicorn backend.app.main:app --reload

The API server will start at http://localhost:8000. You can access:

Swagger UI: http://localhost:8000/docs
ReDoc: http://localhost:8000/redoc
Health Check: http://localhost:8000/api/v1/health

Start the Celery Worker¶

Open a separate terminal for background task processing:

# Start Celery worker with info-level logging
poetry run celery -A backend.app.worker.celery_app worker -l info

Celery is Optional for Basic Development

The Celery worker handles background tasks like grant scraping, embedding generation, and email notifications. The API server works independently for most development tasks.

Run the Test Suite¶

# Run all 533+ backend tests
poetry run pytest tests/ -v

# Run with coverage report
poetry run pytest --cov=backend --cov-report=html

# Run only fast tests (skip E2E)
poetry run pytest -m "not e2e"

Step 5 -- Frontend Setup¶

In a new terminal, navigate to the frontend directory:

# Install Node.js dependencies
cd frontend
npm install

# Start the development server with Turbo
npm run dev -- --turbo

The frontend will start at http://localhost:3000.

Running TestsRunning LinterType Checking

# Run frontend tests
npm run test

# Lint all frontend code
npx eslint .

# Verify TypeScript compilation
npx tsc --noEmit

Step 6 -- Verify Everything Works¶

Run the verification script to confirm all services are reachable:

poetry run python scripts/verify_services.py

You can also run manual checks:

# Check PostgreSQL
docker exec granted_carbon_postgres psql -U grant_user -d grant_engine -c "\dt"

# Check Valkey
docker exec granted_carbon_valkey valkey-cli ping

# Check Meilisearch
curl http://localhost:7700/health

# Check FastAPI
curl http://localhost:8000/api/v1/health

Service Ports Summary¶

Service	Port	URL
FastAPI	8000	`http://localhost:8000`
Next.js	3000	`http://localhost:3000`
PostgreSQL	5433	`postgresql://grant_user:grant_password_dev@localhost:5433/grant_engine`
Valkey	6379	`redis://localhost:6379/0`
Meilisearch	7700	`http://localhost:7700`
Adminer	8080	`http://localhost:8080` (dev profile)
Valkey Commander	8081	`http://localhost:8081` (dev profile)

Common First-Time Issues¶

PostgreSQL connection refused on port 5432

The project uses port 5433, not the default 5432, to avoid conflicts with local Windows PostgreSQL installations. Verify your .env file has POSTGRES_PORT=5433.

Alembic migration fails with 'pgvector not defined'

The migration file may reference pgvector.sqlalchemy.Vector incorrectly. Ensure the init SQL script (scripts/init-extensions.sql) runs during container startup to create the vector extension.

Docker containers not starting

Ensure Docker Desktop is running.
Check for port conflicts: netstat -an | findstr "5433 6379 7700"
Remove old volumes and restart: docker compose down -v && docker compose up -d

bcrypt/passlib compatibility error

bcrypt 5.x is incompatible with passlib 1.7.4. The project pins bcrypt = "<5.0.0" in pyproject.toml. Run poetry install to ensure the correct version.

Next Steps¶

Once your environment is running:

Explore the Architecture Overview to understand system design.
Review the Database Schema to understand the data model.
Read the API Reference to understand available endpoints.
Check the Testing Philosophy before writing code.