Skip to main content

​
Prerequisites

Before starting, ensure you have the following installed:
  • Docker Desktop (v20.10+)
  • Docker Compose plugin (v2.0+)
  • Git for cloning the repository
Verify Docker is running: docker --version and docker compose version

​
Clone and Configure

1

Clone the repository

git clone <repository-url>
cd latentgeo
2

Create environment file

Copy the example environment file and configure your credentials:
cp .env.example .env
Required variables:
# Database (Supabase)
DATABASE_URL=postgresql://user:password@host:5432/database

# Redis (included in Docker Compose)
REDIS_URL=redis://redis:6379/0

# Auth0
AUTH0_DOMAIN=your-domain.auth0.com
AUTH0_API_AUDIENCE=your-api-audience
AUTH0_CLIENT_ID=your-client-id
AUTH0_CLIENT_SECRET=your-client-secret

# API Keys
NVIDIA_API_KEY=your-nvidia-key
GOOGLE_PAGESPEED_API_KEY=your-pagespeed-key

# Supabase Storage
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_KEY=your-anon-key
SUPABASE_SERVICE_ROLE_KEY=your-service-role-key
3

Start development environment

Launch all services with hot reload enabled:
docker compose -f docker-compose.dev.yml up --build
This starts:
  • Backend (FastAPI) on port 8000 with auto-reload
  • Frontend (Next.js) on port 3000 with hot module replacement
  • Worker (Celery) for background tasks
  • Redis for caching and task queue
4

Verify services are running

# Check all containers
docker compose -f docker-compose.dev.yml ps

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

# Visit frontend
open http://localhost:3000

​
Development Mode Features

The docker-compose.dev.yml configuration includes:

​
Hot Reload

volumes:
  - ./backend:/app:cached
command: uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload

​
Code Mounting

  • Backend code is mounted from ./backend to /app
  • Frontend code is mounted from ./frontend to /app
  • Changes are reflected immediately without rebuilding

​
Resource Limits

Optimized for local development: 
deploy:
  resources:
    limits:
      cpus: '2.0'
      memory: 2G
    reservations:
      cpus: '1.0'
      memory: 1G

​
Accessing Services

​
Local URLs

ServiceURLDescription
Frontendhttp://localhost:3000Next.js application
Backend APIhttp://localhost:8000FastAPI server
API Docshttp://localhost:8000/docsSwagger UI
ReDochttp://localhost:8000/redocAlternative API docs
OpenAPI Schemahttp://localhost:8000/openapi.jsonOpenAPI specification

​
Database Connection

Connect to Supabase PostgreSQL using the DATABASE_URL from your .env file: 
# Using psql
psql $DATABASE_URL

# Using pgcli (better UX)
pgcli $DATABASE_URL

​
Redis CLI

Access Redis for debugging: 
docker compose -f docker-compose.dev.yml exec redis redis-cli

​
SSE (Server-Sent Events) Configuration

LatentGEO uses SSE for real-time audit progress updates: 
# Redis-first mode (recommended)
SSE_SOURCE=redis
SSE_FALLBACK_DB_INTERVAL_SECONDS=10
SSE_HEARTBEAT_SECONDS=30
SSE_RETRY_MS=5000
The frontend consumes SSE via /api/v1/sse/audits/{audit_id}/progress through a Next.js proxy route.

​
Troubleshooting

​
Port Conflicts

If port 5432, 6379, 8000, or 3000 are already in use: 
# Change database port
export DEV_DB_HOST_PORT=5433

# Rebuild with new port
docker compose -f docker-compose.dev.yml up --build

​
Logs

View logs for specific services: 
# All services
docker compose -f docker-compose.dev.yml logs -f

# Backend only
docker compose -f docker-compose.dev.yml logs -f backend

# Worker only
docker compose -f docker-compose.dev.yml logs -f worker

​
Reset Everything

Clean slate: 
# Stop and remove containers, volumes
docker compose -f docker-compose.dev.yml down -v

# Rebuild from scratch
docker compose -f docker-compose.dev.yml up --build

​
Database Connection Issues

If you see connection errors: 
# Verify DATABASE_URL is set
echo $DATABASE_URL

# Test connection from backend container
docker compose -f docker-compose.dev.yml exec backend python -c "from app.core.database import engine; print(engine.connect())"
Ensure DB_POOL_PRE_PING=false when using Supabase connection pooler.

​
Next Steps

Run Tests

Learn how to run the test suite

Backend Services

Explore the service layer architecture

Frontend Components

Build UI with Radix components

Contributing

Contribution guidelines and workflow

Build docs developers (and LLMs) love

Get started for freeTalk to us