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
--------------------

.. code-block:: bash

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

Environment Configuration
--------------------------

Create a ``.env`` file at the project root:

.. code-block:: bash

   # 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:

.. code-block:: bash

   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:

.. code-block:: bash

   # 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:

.. code-block:: bash

   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:

.. code-block:: bash

   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:

.. code-block:: bash

   # 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.