Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/geremyjampiersalasgarcia-eng/Caso_Practico_Semillero_IA/llms.txt

Use this file to discover all available pages before exploring further.

Docker Compose manages two background services that the Mesa de Ayuda IA backend depends on: PostgreSQL for persistent conversation history and CRM audit records, and Arize Phoenix for LLM observability and tracing. Both services must be healthy before the FastAPI backend is started.

​
Starting services

From the project root, launch only the postgres and phoenix services in detached mode: 
docker-compose up -d postgres phoenix
ServiceRole
postgresStores conversation history and CRM opportunity records written by the Action Agent. Backed by PostgreSQL 16 Alpine.
phoenixRuns the Arize Phoenix UI for tracing every LLM call, agent step, and retrieval event. All spans from the LangGraph orchestrator appear here in real time.
The backend and frontend services defined in docker-compose.yml are intentionally excluded from this command — for local development, those are run outside Docker (Python venv + npm run dev) so that hot-reload and debuggers work seamlessly.

​
Service details

​
postgres

postgres:
  image: postgres:16-alpine
  container_name: mesa_ayuda_db
  restart: unless-stopped
  environment:
    POSTGRES_USER: mesa_ayuda_user
    POSTGRES_PASSWORD: mesa_ayuda_pass_2024
    POSTGRES_DB: mesa_ayuda_db
  ports:
    - "5433:5432"
  volumes:
    - postgres_data:/var/lib/postgresql/data
  healthcheck:
    test: ["CMD-SHELL", "pg_isready -U mesa_ayuda_user -d mesa_ayuda_db"]
    interval: 5s
    timeout: 5s
    retries: 5
  • Image: postgres:16-alpine — lightweight Alpine-based PostgreSQL 16
  • Container name: mesa_ayuda_db
  • Credentials: user mesa_ayuda_user, password mesa_ayuda_pass_2024, database mesa_ayuda_db
  • Host port: 5433 (mapped from container port 5432) — avoids conflicts with any PostgreSQL already running on your machine
  • Health check: runs pg_isready every 5 seconds with up to 5 retries before reporting unhealthy

​
phoenix

phoenix:
  image: arizephoenix/phoenix:latest
  container_name: mesa_ayuda_phoenix
  restart: unless-stopped
  ports:
    - "6006:6006"
    - "4317:4317"
    - "4318:4318"
  environment:
    - PHOENIX_HOST=0.0.0.0
    - PHOENIX_PORT=6006
  • Image: arizephoenix/phoenix:latest
  • Container name: mesa_ayuda_phoenix
  • UI port: 6006 — open http://localhost:6006 to browse traces
  • OTLP ports: 4317 (gRPC) and 4318 (HTTP) for OpenTelemetry trace ingestion from the backend

​
Verifying health

After starting the services, confirm both containers are running and postgres has passed its health check: 
docker-compose ps
Expected output once both services are fully started (allow 5–10 seconds for PostgreSQL to initialize): 
NAME                   IMAGE                        COMMAND                  SERVICE    CREATED         STATUS                   PORTS
mesa_ayuda_db          postgres:16-alpine           "docker-entrypoint.s…"   postgres   12 seconds ago  Up 11 seconds (healthy)  0.0.0.0:5433->5432/tcp
mesa_ayuda_phoenix     arizephoenix/phoenix:latest  "/app/entrypoint.sh"     phoenix    12 seconds ago  Up 10 seconds            0.0.0.0:4317->4317/tcp, 0.0.0.0:4318->4318/tcp, 0.0.0.0:6006->6006/tcp
The key indicator is (healthy) in the STATUS column for mesa_ayuda_db. The backend’s SQLAlchemy connection pool will fail if it connects before the pg_isready check passes.
If mesa_ayuda_db shows (health: starting) for longer than 30 seconds, inspect the container logs to diagnose the issue:
docker-compose logs postgres
Common causes include a stale data volume from a previous run with different credentials, or a port conflict on 5433.

​
Volume mounts

Volume / MountTypeWhat is stored
postgres_dataNamed Docker volumeAll PostgreSQL data files — conversations, CRM records, schema migrations
./backend/data → /app/dataBind mount (backend service)data/chroma_db/ vector collections and data/raw/ source documents
The postgres_data named volume is managed by Docker and persists across container restarts and docker-compose down calls. To wipe the database completely, you must explicitly remove the volume: 
docker-compose down -v   # removes containers AND named volumes
The ./backend/data bind mount is only active when the backend service itself runs inside Docker. In local development, the backend/data/ directory on your filesystem is used directly.

​
Startup order

The startup order is strict and must not be skipped.
  1. Start Docker services first: docker-compose up -d postgres phoenix
  2. Wait for postgres to report (healthy) via docker-compose ps
  3. Only then start the FastAPI backend (e.g. uvicorn app.main:app --reload)
Starting the backend before PostgreSQL is healthy will cause the initial database connection to fail. While the backend will fall back to SQLite in that case, conversation history written to SQLite will not be migrated to PostgreSQL when the Docker service becomes available later.

​
Port reference

ServiceContainer PortHost PortPurpose
postgres54325433PostgreSQL — conversation history & CRM
phoenix60066006Arize Phoenix observability UI
phoenix43174317OTLP gRPC trace ingestion
phoenix43184318OTLP HTTP trace ingestion
backend (if containerized)80008000FastAPI REST API
frontend (if containerized)30003000Next.js chat UI
PostgreSQL uses host port 5433 (not the standard 5432) to avoid conflicts with a locally installed PostgreSQL instance. The DATABASE_URL in .env must reference port 5433 when connecting from the host:
DATABASE_URL=postgresql://mesa_ayuda_user:[email protected]:5433/mesa_ayuda_db
Inside the Docker network (container-to-container), the standard port 5432 is used:
DATABASE_URL=postgresql://mesa_ayuda_user:mesa_ayuda_pass_2024@postgres:5432/mesa_ayuda_db

Build docs developers (and LLMs) love

Get started for freeTalk to us