Setup & Configuration

Quick Start

Get up and running in 3 commands:


cd services/api_gateway
uv sync
uv run pytest

That’s it! The tests use testcontainers to spin up PostgreSQL automatically, so you can verify everything works without any database setup.

What this does:

Installs all dependencies
Runs 40 tests with a real PostgreSQL container
Verifies database models, API endpoints, and AI client
Takes ~15 seconds

Prerequisites

Python 3.13+
Docker (for tests and local PostgreSQL)
uv (Python package manager) - Install: curl -LsSf https://astral.sh/uv/install.sh | sh

Full Setup

For running the service locally (not just tests):

1. Install dependencies


cd services/api_gateway
uv sync

2. Start PostgreSQL


# Option A: Docker Compose (from repo root)
docker compose up -d postgres
 
# Option B: Standalone Docker
docker run -d \
  --name dermadetect-postgres \
  -e POSTGRES_PASSWORD=postgres \
  -e POSTGRES_DB=dd_api \
  -p 5432:5432 \
  postgres:16

3. Run migrations


uv run alembic upgrade head

4. Verify everything works


# Run tests
uv run pytest
 
# Start the service
uv run uvicorn src.main:app --reload --port 8000
 
# Check health endpoint
curl http://localhost:8000/healthy

Configuration

Configuration is managed through environment variables and the Settings class in src/config.py:5.

Good defaults are already set - you can run the service without any .env file for local development.

Default Settings (works out of the box)

DATABASE_URL: postgresql://postgres:postgres@localhost:5432/dd_api
AI_SERVICE_URL: http://localhost:8001
CORS_ORIGINS: ["*"] (allow all origins)

Optional Settings

Only needed if you’re customizing or deploying:

AZURE_STORAGE_CONNECTION_STRING: Azure Blob Storage (required for image upload endpoint)
AZURE_STORAGE_CONTAINER_NAME: Container name (default: dermadetect-images)
DB_ECHO: Enable SQL query logging (default: false)
MAX_UPLOAD_SIZE_MB: Max image size (default: 2)

Custom Configuration

Create a .env file only if you need to override defaults:


cp .env.example .env
# Edit as needed

Example .env:


DATABASE_URL=postgresql://user:pass@myhost:5432/dermadetect
AI_SERVICE_URL=http://ai-service:8001
DB_ECHO=true

Accessing the API

Once running, access the service at:

API Base: http://localhost:8000
Health Check: http://localhost:8000/healthy
Swagger Docs: http://localhost:8000/docs (interactive API docs)
ReDoc: http://localhost:8000/redoc (alternative API docs)

Database Migrations

Create a new migration


uv run alembic revision --autogenerate -m "description of changes"

Apply migrations


uv run alembic upgrade head

Rollback one migration


uv run alembic downgrade -1