Web App Deployment

TLDR: The web app is a dev/demo tool. For production use, query via FlightSQL directly.

Quick Start (Dev)

cd analytics-web-app
python start_analytics_web.py

Opens on http://localhost:3000 with backend on :8000. Automatically sets localhost defaults.

Environment Variables

Required

# OIDC provider configuration (same format as FlightSQL server)
# Note: Web app only supports a single issuer
export MICROMEGAS_OIDC_CONFIG='{
  "issuers": [
    {
      "issuer": "https://accounts.google.com",
      "audience": "your-client-id.apps.googleusercontent.com"
    }
  ]
}'

# CORS and OAuth callback
export MICROMEGAS_WEB_CORS_ORIGIN="http://localhost:3000"
export MICROMEGAS_AUTH_REDIRECT_URI="http://localhost:3000/auth/callback"

# OAuth state signing secret (IMPORTANT: must be same across all instances)
# Generate with: openssl rand -base64 32
export MICROMEGAS_STATE_SECRET="your-random-secret-here"

# FlightSQL connection
export MICROMEGAS_FLIGHTSQL_URL="grpc://127.0.0.1:50051"

Optional

# Base path for reverse proxy deployments (e.g., behind ALB)
# All routes will be prefixed with this path
export MICROMEGAS_BASE_PATH="/analytics"

# Cookie settings (production)
export MICROMEGAS_COOKIE_DOMAIN=".example.com"
export MICROMEGAS_SECURE_COOKIES="true"  # HTTPS only

# Disable auth (dev only)
analytics-web-srv --disable-auth

Production Notes

CORS Origin must match OAuth redirect URI origin:

MICROMEGAS_WEB_CORS_ORIGIN="https://analytics.example.com"
MICROMEGAS_AUTH_REDIRECT_URI="https://analytics.example.com/auth/callback"

Deploying behind a reverse proxy with path prefix:

# Example: ALB routes /analytics/* to the web app
MICROMEGAS_BASE_PATH="/analytics"
MICROMEGAS_WEB_CORS_ORIGIN="https://example.com"
MICROMEGAS_AUTH_REDIRECT_URI="https://example.com/analytics/auth/callback"

Routes become: /analytics/health, /analytics/query, /analytics/auth/*, etc. The same container image works for any base path - no rebuild needed.

API Routes

Without MICROMEGAS_BASE_PATH: - GET /health - Health check - POST /query - Execute SQL query - GET /perfetto/{process_id}/info - Trace metadata - POST /perfetto/{process_id}/generate - Generate Perfetto trace - GET /auth/login - Initiate OAuth login - GET /auth/callback - OAuth callback - POST /auth/refresh - Refresh tokens - POST /auth/logout - Logout - GET /auth/me - Current user info

With MICROMEGAS_BASE_PATH="/analytics", all routes are prefixed (e.g., /analytics/health).

Configure OAuth redirect in your identity provider: - Add the redirect URI to allowed callbacks - For Google: Cloud Console → APIs & Services → Credentials

Architecture

• Frontend: Next.js on port 3000
• Backend: Rust (analytics-web-srv) on port 8000
• Auth: OIDC (ID tokens via httpOnly cookies)
• Data: FlightSQL queries to analytics service

Backend proxies FlightSQL with user's ID token. No direct data access.

Command Line Options

analytics-web-srv [OPTIONS]

Options:
  -p, --port <PORT>              Server port [default: 3000]
      --frontend-dir <DIR>       Frontend build directory [default: ../analytics-web-app/out]
      --disable-auth             Disable authentication (dev only)
  -h, --help                     Print help

Example:

analytics-web-srv --port 8000 --frontend-dir ./out --disable-auth

Warning: --disable-auth removes authentication middleware. Do not use in production.