Skip to Content
ServicesAPI GatewaySetup & Configuration

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 Python dependencies
  • Runs tests with a real PostgreSQL container
  • Verifies database models, API endpoints, and AI client

Prerequisites

  • Python 3.11+
  • Node.js 22+ (for Physician Portal)
  • 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

Physician Portal (React App)

The portal lives in services/api_gateway/physician_portal/. It is a Vite + React app that proxies API calls to the FastAPI backend.

cd services/api_gateway/physician_portal
npm install
npm run dev
# Portal available at http://localhost:3000
# API calls proxied to http://localhost:8081 (FastAPI)

Build for production / Docker

The Dockerfile handles this automatically in its first stage:

# Multi-stage build: Node builds the React app, then Python copies the dist
docker build -f services/api_gateway/Dockerfile .

To build the portal manually:

cd services/api_gateway/physician_portal
npm ci
npm run build
# Output: services/api_gateway/physician_portal/dist/

FastAPI then serves dist/ as static files when PORTAL_DIST directory exists.

Accessing the API

Once running, access the service at:

  • Physician Portal: http://localhost:8081/ (when running with Docker or after npm run build)
  • Portal Dev Server: http://localhost:3000/ (when running npm run dev)
  • Health Check: http://localhost:8081/healthy
  • Swagger Docs: http://localhost:8081/docs (interactive 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
Last updated on
API Gateway ServiceAuthentication