Self-Hosting with Docker Compose

Prerequisites

Docker and Docker Compose v2
An Auth0 tenant (for user authentication)
Node.js 18+ (for the web frontend)

Quick start

git clone https://github.com/gregorycarter/bridge-town-core.git
cd bridge-town-core
cp .env.example .env
# Edit .env with your Auth0 credentials
docker compose up -d

This starts:

Service	Port	Description
`web`	3000	Next.js frontend
`mcp_server`	8000	FastAPI MCP server
`postgres`	5434	PostgreSQL 16 with RLS
`redis`	6380	Rate limiting + Celery broker
`gitea`	3001	Git server
`celery_worker`	—	Async task execution
`celery_beat`	—	Scheduled tasks

Environment variables

Key variables for the MCP server (mcp_server service):

Variable	Description
`DATABASE_URL`	PostgreSQL connection string
`REDIS_URL`	Redis URL for rate limiting
`GITEA_URL`	Internal Gitea URL
`AUTH0_DOMAIN`	Auth0 tenant domain (e.g. `your-tenant.us.auth0.com`)
`AUTH0_AUDIENCE`	Auth0 JWT audience — must be a URL (e.g. `https://api.example.com`). Used as the JWT audience claim value for /authorize and /token requests. In standard deployments this also serves as the OAuth metadata and relay-callback base URL.
`OAUTH_PUBLIC_BASE_URL`	(Optional) Public HTTPS base URL for OAuth metadata (RFC 9728/8414) and the localhost relay-callback endpoint. Set this only when your reverse proxy exposes the API at a different URL than `AUTH0_AUDIENCE` (e.g. `https://api.example.com` behind a proxy while `AUTH0_AUDIENCE` is an internal value). Defaults to `AUTH0_AUDIENCE` when not set.
`RATE_LIMIT_FAIL_OPEN`	`true` for dev (skip rate limiting if Redis is down)

Exposing via Tailscale Funnel

For external testing without a public deployment:

./scripts/start-funnel.sh

This starts Docker Compose with Funnel-specific overrides and configures Tailscale path-based routing:

/ → web (port 3000)
/mcp → mcp_server (port 8000)

See docker-compose.funnel.yml for the environment overrides.

Running tests

docker compose exec mcp_server pytest tests/ -x