Installation

This guide covers setting up the full Co-design stack (backend + supporting services) for local development.

Prerequisites

Docker and Docker Compose (v2+)
Python 3.12+ (for backend development without Docker)
Git
Access to the GitLab repository

Clone the Repository

git clone git@gitlab.eurobios.com:esa/codesign/codesign-backend.git
cd codesign-backend

Environment Configuration

Create a .env file at the project root:

# Required environment variables
ENV=development
BACKEND_PORT=8000

# PostgreSQL
POSTGRES_USER=codesign
POSTGRES_PASSWORD=codesign_secret
POSTGRES_DB=codesign
POSTGRES_HOST=postgres
POSTGRES_PORT=5432

# LLM Gateway
LITELLM_MASTER_KEY=sk-your-litellm-key
LLM_BASE_URL=http://litellm:4000
LLM_LITE_PORT=4000
LLM_LITE_USER=admin
LLM_LITE_PASSWORD=admin_password

# OVH LLM Provider Keys
OVH_ENDPOINT_API_KEY_1=your-key-here

# Vector Database
WEAVIATE_HOST=codesign-weaviate
WEAVIATE_PORT=8080
WEAVIATE_GRPC_PORT=50051
VECTOR_DB_NAME=codesign_collection

# Neo4j (optional)
NEO4J_HTTP_PORT=7474
NEO4J_BOLT_PORT=7687

# Search services
SEARXNG_URL=http://searxng:8080
CRAWL4AI_URL=http://crawl4ai:8000

# Application settings
ROOT_PATH=
RESET_DB_ON_STARTUP=false
DEBUG=false
DATABASE=postgresql+asyncpg://${POSTGRES_USER}:${POSTGRES_PASSWORD}@${POSTGRES_HOST}:5432/${POSTGRES_DB}

Start with Docker Compose (Recommended)

Build and start all services:

docker compose up --build -d

This starts:

backend — FastAPI application on port ${BACKEND_PORT}
postgres — PostgreSQL 16 database
litellm — LLM proxy gateway on port ${LLM_LITE_PORT}
neo4j — Graph database (optional)

Verify the stack is running:

# Check all services
docker compose ps

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

# Access Swagger docs
open http://localhost:8000/docs

Local Development (Without Docker)

If you prefer running the backend natively:

cd backend

# Create virtual environment
python -m venv .venv
source .venv/bin/activate

# Install dependencies
pip install -e ".[dev]"

# Run the backend
uvicorn backend.api.main:app --host 0.0.0.0 --port 8000 --reload

Note

You still need PostgreSQL, Weaviate, and LiteLLM running (via Docker or installed locally) for the backend to work properly.

Frontend Setup

The frontend is a separate React application. Refer to the codesign-frontend repository for setup instructions:

git clone git@gitlab.eurobios.com:esa/codesign/codesign-frontend.git
cd codesign-frontend
npm install
npm run dev

Configure the frontend to point to your local backend:

# In frontend .env
NEXT_PUBLIC_API_URL=http://localhost:8000

Troubleshooting

Backend won’t start:: Check that PostgreSQL is accessible and the POSTGRES_URL is correct.
LLM calls fail:: Ensure LiteLLM is healthy (curl http://localhost:4000/health/liveliness) and that OVH API keys are configured.
Vector search not working:: Verify Weaviate is running and the collection VECTOR_DB_NAME exists.