Docker Compose
===============

The platform uses Docker Compose for orchestrating all services.

Service Definitions
--------------------

Backend
~~~~~~~~

.. code-block:: yaml

   backend:
     build:
       context: ./backend
       dockerfile: dockerfile
       target: runtime
     container_name: backend-${ENV}
     ports:
       - "${BACKEND_PORT}:1456"
     depends_on:
       litellm:
         condition: service_healthy
     networks:
       - internal
       - codesign-shared

The backend:

- Builds from the ``backend/`` directory using a multi-stage Dockerfile
- Waits for LiteLLM to be healthy before starting
- Runs on internal port 1456, mapped to ``BACKEND_PORT``
- Connects to both internal and shared networks

PostgreSQL
~~~~~~~~~~~

.. code-block:: yaml

   postgres:
     image: postgres:16-alpine
     container_name: postgres-${ENV}
     environment:
       POSTGRES_DB: ${POSTGRES_DB}
       POSTGRES_USER: ${POSTGRES_USER}
       POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
     volumes:
       - postgres_data:/var/lib/postgresql/data
     ports:
       - "${POSTGRES_PORT:-5432}:5432"
     networks:
       - internal

LiteLLM
~~~~~~~~~

.. code-block:: yaml

   litellm:
     image: ghcr.io/berriai/litellm:main-stable
     container_name: litellm-${ENV}
     command: ["--config", "/app/config.yaml", "--port", "4000"]
     volumes:
       - ./service_llm_lite/llm_lite_config.yaml:/app/config.yaml:ro
     environment:
       - LITELLM_MASTER_KEY=${LITELLM_MASTER_KEY}
       - OVH_ENDPOINT_API_KEY_1
       - OVH_ENDPOINT_API_KEY_2
       # ... up to 6 keys for load balancing
     healthcheck:
       test: ["CMD", "python", "-c", "...urllib..."]
       interval: 10s
       timeout: 5s
       retries: 5
     networks:
       - internal

Neo4j (Optional)
~~~~~~~~~~~~~~~~~

.. code-block:: yaml

   neo4j:
     build:
       context: ./graph
       dockerfile: dockerfile
     container_name: neo4j-${ENV}
     ports:
       - "${NEO4J_HTTP_PORT}:7474"
       - "${NEO4J_BOLT_PORT}:7687"
     environment:
       NEO4J_AUTH: neo4j/password
       NEO4J_PLUGINS: '["apoc"]'
     networks:
       - internal

Networks
---------

.. code-block:: yaml

   networks:
     internal:
       name: codesign-${ENV}-internal
       driver: bridge
     codesign-shared:
       external: true

- **internal** — Isolated per-environment network (backend ↔ postgres ↔ litellm ↔ neo4j)
- **codesign-shared** — External network shared with Weaviate, SearXNG, Crawl4AI

Create the shared network before first deployment:

.. code-block:: bash

   docker network create codesign-shared

Volumes
--------

.. code-block:: yaml

   volumes:
     postgres_data:     # PostgreSQL persistent storage
     neo4j_data:        # Neo4j graph data
     neo4j_logs:        # Neo4j logs
     neo4j_import:      # Neo4j import directory
     neo4j_plugins:     # Neo4j plugins (APOC)

Common Operations
------------------

.. code-block:: bash

   # Build all services
   docker compose build

   # Start all services
   docker compose up -d

   # View logs
   docker compose logs -f backend

   # Restart a single service
   docker compose restart backend

   # Stop everything
   docker compose down

   # Stop and remove volumes (WARNING: data loss)
   docker compose down -v

   # Rebuild and restart backend only
   docker compose up --build -d backend

Multi-Environment Support
--------------------------

Use the ``ENV`` variable to run multiple environments on the same host:

.. code-block:: bash

   # Staging
   ENV=staging BACKEND_PORT=8001 docker compose up -d

   # Production
   ENV=production BACKEND_PORT=8000 docker compose up -d

Each environment gets its own:

- Container names (e.g., ``backend-staging``, ``backend-production``)
- Network (``codesign-staging-internal``, ``codesign-production-internal``)
- Volumes (namespaced by Docker Compose project)