Upgrade gateway

.env.example

@@ -0,0 +1,91 @@
+# =============================================================================
+# NeroSpatial Backend - Environment Configuration Template
+# =============================================================================
+# Copy this file to .env and fill in your values:
+#   cp .env.example .env
+#
+# IMPORTANT: Never commit .env to Git!
+# =============================================================================
+
+# -----------------------------------------------------------------------------
+# Application
+# -----------------------------------------------------------------------------
+APP_NAME=NeroSpatial Backend
+APP_VERSION=0.1.0
+DEBUG=true
+ENVIRONMENT=development
+LOG_LEVEL=INFO
+
+# -----------------------------------------------------------------------------
+# Server
+# -----------------------------------------------------------------------------
+HOST=0.0.0.0
+PORT=8000
+
+# -----------------------------------------------------------------------------
+# Azure Key Vault (REQUIRED for production/staging)
+# All secrets are loaded from Key Vault. Only these credentials go in .env
+# -----------------------------------------------------------------------------
+AZURE_KEY_VAULT_URL=https://your-vault-name.vault.azure.net/
+AZURE_TENANT_ID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
+AZURE_CLIENT_ID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
+AZURE_CLIENT_SECRET=your-client-secret-here
+
+# -----------------------------------------------------------------------------
+# Azure App Configuration (REQUIRED for production/staging)
+# Single source of truth for all non-secret configuration
+# -----------------------------------------------------------------------------
+AZURE_APP_CONFIG_URL=https://your-config-name.azconfig.io
+
+# -----------------------------------------------------------------------------
+# PostgreSQL (URLs only - password from Key Vault)
+# These are defaults/overrides. Production uses App Configuration.
+# -----------------------------------------------------------------------------
+POSTGRES_HOST=localhost
+POSTGRES_PORT=5432
+POSTGRES_DB=nerospatial
+POSTGRES_USER=nerospatial
+# POSTGRES_PASSWORD - Loaded from Key Vault secret "postgres-password"
+POSTGRES_POOL_MIN=5
+POSTGRES_POOL_MAX=20
+
+# -----------------------------------------------------------------------------
+# Redis (URLs only - password from Key Vault)
+# These are defaults/overrides. Production uses App Configuration.
+# -----------------------------------------------------------------------------
+REDIS_HOST=localhost
+REDIS_PORT=6379
+REDIS_DB=0
+# REDIS_PASSWORD - Loaded from Key Vault secret "redis-password"
+
+# -----------------------------------------------------------------------------
+# JWT Authentication
+# Keys loaded from Key Vault. These are defaults/overrides.
+# -----------------------------------------------------------------------------
+JWT_ALGORITHM=RS256
+JWT_ACCESS_TOKEN_TTL=900
+JWT_REFRESH_TOKEN_TTL=604800
+JWT_CACHE_TTL=300
+# JWT_PRIVATE_KEY - Loaded from Key Vault secret "jwt-private-key"
+# JWT_PUBLIC_KEY - Loaded from Key Vault secret "jwt-public-key"
+
+# -----------------------------------------------------------------------------
+# OpenTelemetry
+# -----------------------------------------------------------------------------
+OTEL_ENDPOINT=http://localhost:4317
+OTEL_ENABLE_TRACING=true
+OTEL_ENABLE_METRICS=true
+
+# -----------------------------------------------------------------------------
+# Startup Configuration
+# -----------------------------------------------------------------------------
+STARTUP_TIMEOUT_SECONDS=30
+STARTUP_RETRY_ATTEMPTS=3
+STARTUP_RETRY_DELAY_SECONDS=2
+
+# -----------------------------------------------------------------------------
+# Google OAuth (Skip for now - Phase 2)
+# -----------------------------------------------------------------------------
+# GOOGLE_CLIENT_ID - Loaded from Key Vault (when implemented)
+# GOOGLE_CLIENT_SECRET - Loaded from Key Vault (when implemented)
+# GOOGLE_REDIRECT_URI=http://localhost:8000/auth/callback

.github/workflows/ci.yml

@@ -31,7 +31,7 @@ jobs:
           enable-cache: true
 
       - name: Set up Python
-        run: uv python install 3.11
+        run: uv python install 3.13.7
 
       - name: Install dependencies
         run: uv sync --extra dev
@@ -47,6 +47,17 @@ jobs:
     runs-on: ubuntu-latest
     needs: lint
 
+    services:
+      redis:
+        image: redis:7-alpine
+        ports:
+          - 6379:6379
+        options: >-
+          --health-cmd "redis-cli ping"
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+
     steps:
       - name: Checkout code
         uses: actions/checkout@v4
@@ -57,7 +68,7 @@ jobs:
           enable-cache: true
 
       - name: Set up Python
-        run: uv python install 3.11
+        run: uv python install 3.13.7
 
       - name: Install dependencies
         run: uv sync --extra dev

.gitignore

@@ -37,6 +37,7 @@ ENV/
 .env.local
 .env.*.local
 .env
+keys/
 
 # OS
 .DS_Store
@@ -47,5 +48,5 @@ Thumbs.db
 
 # UV
 .uv/
-**.mdc**
-.cursor/
+.cursor/
+*.mdc*

Dockerfile

@@ -4,7 +4,7 @@
 # Multi-stage build for optimized production image
 
 # Stage 1: Build stage with uv for fast dependency installation
-FROM python:3.11-slim AS builder
+FROM python:3.13.7-slim AS builder
 
 # Install uv
 COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv
@@ -28,7 +28,7 @@ RUN --mount=type=cache,target=/root/.cache/uv \
 
 
 # Stage 2: Production runtime
-FROM python:3.11-slim AS runtime
+FROM python:3.13.7-slim AS runtime
 
 # Create non-root user for security
 RUN groupadd --gid 1000 appgroup && \

README.md

@@ -37,15 +37,86 @@ uv run python main.py
 
 ## Endpoints
 
-- `GET /health` - Health check endpoint
-- `GET /helloword` - Hello world endpoint
+### Health Endpoints
+
+- `GET /health` - Detailed health check with dependency status
+- `GET /ready` - Readiness probe (Kubernetes/load balancer)
+- `GET /live` - Liveness probe (Kubernetes)
+
+### Application Endpoints
+
+- `GET /helloworld` - Hello world endpoint
+
+## Infrastructure Setup
+
+### Local Development
+
+Start infrastructure services (PostgreSQL, Redis, Jaeger) using Docker Compose:
+
+```bash
+docker compose -f docker-compose.infra.yml up -d
+```
+
+This will start:
+
+- PostgreSQL on port 5432
+- Redis on port 6379
+- Jaeger (tracing) on ports 4317 (OTLP) and 16686 (UI)
+
+### Database Initialization
+
+The database schema is automatically initialized when the PostgreSQL container starts for the first time via `scripts/init-db.sql`.
+
+### JWT Key Generation
+
+Generate JWT RS256 keys for authentication:
+
+```bash
+./scripts/generate-keys.sh
+```
+
+This creates `keys/private.pem` and `keys/public.pem`. Store these in Azure Key Vault for production.
+
+### Azure Key Vault Setup
+
+Set up Azure Key Vault and upload secrets:
+
+```bash
+./scripts/setup-keyvault.sh
+```
+
+This script will:
+
+1. Create Key Vault (if not exists)
+2. Create Service Principal with proper permissions
+3. Upload JWT keys and other secrets
+4. Output credentials for your `.env` file
 
 ## Configuration
 
-Configuration is managed through:
+Configuration is managed through a hierarchy:
+
+1. **Azure App Configuration** (single source of truth for production/staging)
+
+   - Non-secret settings (URLs, ports, feature flags)
+   - Environment-specific configuration using labels
+
+2. **Azure Key Vault** (secrets)
+
+   - Passwords, JWT keys, OAuth credentials
+   - Referenced from App Configuration
+
+3. **`.env` file** (bootstrap and development fallback)
+   - Azure credentials to access App Config and Key Vault
+   - Local overrides for development
+   - Minimal - only what's needed to bootstrap
+
+### Environment Validation
+
+- **Production/Staging**: Requires Azure App Config and Key Vault URLs. Server will not start without them.
+- **Development**: Optional Azure services. Falls back to `.env` file if not configured.
 
-- `config.py` - Configuration module using Pydantic Settings
-- `.env` - Environment variables for secrets (will be replaced by Azure Key Vault in the future)
+See `.env.example` for all available configuration options.
 
 ## Pre-commit Hooks
 

api/__init__.py

@@ -0,0 +1 @@
+"""API routes package."""

api/health.py

@@ -0,0 +1,91 @@
+"""
+Health check endpoints for production monitoring.
+
+Provides /health, /ready, and /live endpoints for Kubernetes and load balancers.
+"""
+
+from datetime import UTC, datetime
+
+from fastapi import APIRouter, Request
+from fastapi.responses import JSONResponse
+
+from core.app_state import AppState
+
+router = APIRouter(tags=["Health"])
+
+
+@router.get("/health")
+async def health_check(request: Request) -> JSONResponse:
+    """
+    Detailed health check with dependency status.
+
+    Returns:
+        - status: overall health status
+        - checks: individual service checks
+        - metadata: app info and uptime
+    """
+    state: AppState = request.app.state.app_state
+
+    checks = {
+        "database": state.db_pool is not None and await state.db_pool.ping() if hasattr(state.db_pool, "ping") else state.db_pool is not None,
+        "redis": await state.redis_client.ping() if state.redis_client else False,
+        "key_vault": state.key_vault.is_available() if state.key_vault else False,
+    }
+
+    all_healthy = all(checks.values())
+    uptime = (datetime.now(UTC) - state.started_at).total_seconds()
+
+    return JSONResponse(
+        status_code=200 if all_healthy else 503,
+        content={
+            "status": "healthy" if all_healthy else "unhealthy",
+            "checks": checks,
+            "metadata": {
+                "service": state.settings.app_name,
+                "version": state.settings.app_version,
+                "environment": state.settings.environment,
+                "uptime_seconds": uptime,
+            },
+        },
+    )
+
+
+@router.get("/ready")
+async def readiness_check(request: Request) -> JSONResponse:
+    """
+    Readiness probe for Kubernetes/load balancers.
+
+    Returns 200 only when app is fully initialized and ready.
+    Used by load balancers to know when to send traffic.
+    """
+    state: AppState = request.app.state.app_state
+
+    if not state.is_ready:
+        return JSONResponse(
+            status_code=503,
+            content={"status": "not_ready", "errors": state.startup_errors},
+        )
+
+    # Verify critical dependencies
+    db_ok = state.db_pool is not None and (await state.db_pool.ping() if hasattr(state.db_pool, "ping") else True)
+    redis_ok = state.redis_client is not None and await state.redis_client.ping()
+
+    if not (db_ok and redis_ok):
+        return JSONResponse(
+            status_code=503,
+            content={"status": "not_ready", "database": db_ok, "redis": redis_ok},
+        )
+
+    return JSONResponse(content={"status": "ready"})
+
+
+@router.get("/live")
+async def liveness_check() -> JSONResponse:
+    """
+    Liveness probe for Kubernetes.
+
+    Returns 200 if the process is alive.
+    Does NOT check dependencies - only process health.
+    Used by Kubernetes to know when to restart container.
+    """
+    return JSONResponse(content={"status": "alive"})