Local Development Environment

The local dev environment mirrors production as closely as possible using Caddy as a reverse proxy and custom hostnames via the hosts file.

Architecture

Browser
  │
  ▼
/etc/hosts (resolves *.geoassistant.localhost → 127.0.0.1)
  │
  ▼
Caddy (reverse proxy)
  ├── geoassistant.localhost          → localhost:5173  (marketing site)
  ├── app.geoassistant.localhost      → localhost:5174  (SaaS app)
  ├── docs.geoassistant.localhost     → localhost:8000  (Sphinx docs)
  ├── docs.geogeometry.geoassistant.localhost → localhost:8001
  └── api.geoassistant.localhost      → localhost:8002  (FastAPI)

Hosts File

The hosts file tells your OS to resolve custom domains to your local machine instead of looking them up on the internet.

On Windows: C:\Windows\System32\drivers\etc\hosts

127.0.0.1   geoassistant.localhost
127.0.0.1   app.geoassistant.localhost
127.0.0.1   docs.geoassistant.localhost
127.0.0.1   docs.geogeometry.geoassistant.localhost
127.0.0.1   api.geoassistant.localhost

Caddyfile

{
    local_certs
}

geoassistant.localhost {
    reverse_proxy localhost:5173
}

app.geoassistant.localhost {
    reverse_proxy localhost:5174
}

docs.geoassistant.localhost {
    reverse_proxy localhost:8000
}

docs.geogeometry.geoassistant.localhost {
    reverse_proxy localhost:8001
}

api.geoassistant.localhost {
    reverse_proxy localhost:8002
}

local_certs tells Caddy to generate self-signed certificates for HTTPS locally, so the dev environment behaves like production.

Environment Variables

Each service has its own .env file. For the API locally:

AUTH0_DOMAIN=auth.geoassistant.org
AUTH0_CLIENT_ID=your_client_id
AUTH0_CLIENT_SECRET=your_secret
AUTH0_REDIRECT_URI=https://api.geoassistant.localhost/auth/callback
FRONTEND_URL=https://geoassistant.localhost
APP_URL=https://app.geoassistant.localhost
COOKIE_DOMAIN=.geoassistant.localhost
COOKIE_SECURE=false

For the React frontends:

VITE_API_URL=https://api.geoassistant.localhost
VITE_APP_URL=https://app.geoassistant.localhost