LOCAL_SERVICES.md

Local services required for full integration testing

Overview

• Unit tests run isolated with mocks; no services needed.
• For end-to-end / integration you should run the services below.

Core services (recommended minimal set)

• redis: Used by Celery broker and LangGraph RedisSaver checkpointer.
• minio: S3-compatible object storage when STORAGE_BACKEND=minio.
• supabase (postgres + storage + realtime + rest + kong): Optional but required if using Supabase storage or DB-backed features.
• keycloak: OIDC provider used for authentication (tests mock get_current_user).
• chromadb: Vector DB used by HS-code embeddings (optional unless running embedding flows).

Starting the minimal set with docker-compose (from repo root):

# From repository root
docker-compose up -d redis minio chromadb supabase-db supabase-storage supabase-realtime supabase-rest supabase-kong keycloak

Notes & env vars

• The repo docker-compose.yml already configures sensible defaults. Override with environment variables in .env at apps/api/.env or repo root.
• Typical overrides:
  • POSTGRES_PASSWORD (postgres/supabase)
  • MINIO_ROOT_USER / MINIO_ROOT_PASSWORD
  • SUPABASE_JWT_SECRET
  • KEYCLOAK_ADMIN / KEYCLOAK_ADMIN_PASSWORD

Quick checks

• Redis available at redis://localhost:6379 (or redis://redis:6379 inside Docker network).
• Minio console: http://localhost:9001, API: http://localhost:9000
• Supabase storage API: http://localhost:5000 (configured in compose)
• Keycloak admin console: http://localhost:8080

Integration test tips

• Many tests mock Supabase and Keycloak; only enable real services when running integration/e2e tests.
• If you want a minimal integration run, start redis and minio first and set STORAGE_BACKEND=minio in your .env before running the API.

Running integration tests

• Start the minimal services with the helper script from the repo root:

.\scripts\integration-up.ps1

• Run only integration-marked tests:

cd apps/api
.venv\Scripts\python.exe -m pytest -m integration -q

• A dedicated GitHub Actions workflow is available at .github/workflows/integration.yml for manual or main-branch integration runs.

• Run unit tests (fast, uses mocks):

cd apps/api
.venv\Scripts\python.exe -m pytest tests/ -q

CI recommendations

• Run unit tests on every push; run integration tests in a separate CI job that brings up services (docker-compose or Testcontainers) and runs pytest -m integration.
• Use pytest.ini to declare markers (already added at apps/api/pytest.ini).

Next steps

• I can run a minimal docker-compose up for you and then run integration tests, or add a docker-compose.integration.yml with a trimmed service list. Which would you prefer?