Multi-domain setup

If your project uses multi-domain organization mode, you need a reverse proxy to route wildcard subdomains (e.g., tenant.project.localhost) to your local frontend and backend. We use Caddy via Docker for this.

Start Caddy with Docker Compose

From the root of your project, run:

cd packages/multi-domain
docker compose up -d

This will start a Caddy reverse proxy that routes:

  • *.project.localhost and project.localhost → Frontend (port 5173)
  • *.project.localhost/api and project.localhost/api → Backend API (port 3011)

Trust local HTTPS certificate

Caddy auto-generates TLS certificates. You need to trust the CA certificate on your machine.

Run these commands from the packages/multi-domain directory:

macOS:

docker compose cp caddy:/data/caddy/pki/authorities/local/root.crt /tmp/root.crt && \
    sudo security add-trusted-cert -d -r trustRoot \
    -k /Library/Keychains/System.keychain /tmp/root.crt

Windows (PowerShell as Admin):

docker compose cp caddy:/data/caddy/pki/authorities/local/root.crt $env:TEMP/root.crt; `
    certutil -addstore -f "ROOT" $env:TEMP/root.crt

Linux:

docker compose cp caddy:/data/caddy/pki/authorities/local/root.crt \
    /usr/local/share/ca-certificates/root.crt && \
    sudo update-ca-certificates

Configure environment variables

Update the following .env files to use the multi-domain URLs instead of localhost ports.

packages/backend/.env

FRONTEND_URL=https://*.project.localhost
BACKEND_URL=https://project.localhost

packages/frontend/.env

VITE_BACKEND_URL=""

packages/mobile/.env (if applicable)

EXPO_PUBLIC_ANDROID_WEB_URL=https://project.localhost
EXPO_PUBLIC_IOS_WEB_URL=https://project.localhost

Useful commands

View logs:

docker compose logs caddy -f

Reload config:

docker compose exec -w /etc/caddy caddy caddy reload

Stop:

docker compose down
Push notificationsVercel