doxa-maps/deployment/cloud

Run dx-maps in the cloud: one shared dev server for a team

One container runs the Plugin Studio with hot reload for everyone. It clones the repo, pulls the branch every few seconds, and Vite hot-reloads whatever changed, so every change an agent lands on main shows up in everyone's browser within seconds. No rebuild; bun run build is only for publishing.

With no OIDC settings it runs open, like bun run dev on a laptop. With OIDC settings a sign-in page ("Sign in with your provider") sits in front of everything: the Studio, every map, and the hot-reload websocket. Only people in the allowed groups get in.

Deploy

1. Build the image from Dockerfile. It's a small bootstrap (Bun, git, and the oauth2-proxy binary); at start it clones the repo and runs entry.sh from it, so the recipe updates with the repo. Paste it into any container host (Coolify's "Dockerfile" build pack, Railway, docker build).
2. Set the environment below and expose the container's PORT over HTTPS.
3. Give it about 2 GB of memory (Vite plus the dependency install).

Variable	Needed	Meaning
REPO_URL	yes	the dx-maps git URL to clone
BRANCH	no (main)	the branch to follow
PULL_INTERVAL	no (15)	seconds between pulls
GIT_TOKEN	private repos	a read token for the clone and pulls
PORT	no (5173)	the port the container serves on
HMR_CLIENT_PORT, HMR_PROTOCOL	behind HTTPS	443 and wss, so browsers reach the hot-reload websocket

Sign-in (optional)

Set all of these to turn the gate on. Register a confidential client at your OIDC provider with the redirect URL https://<your-host>/oauth2/callback; PKCE (S256) is used as well.

Variable	Meaning
OIDC_ISSUER	the provider's issuer URL (its /.well-known/openid-configuration must resolve)
OIDC_CLIENT_ID, OIDC_CLIENT_SECRET	the registered client
OIDC_REDIRECT_URL	https://<your-host>/oauth2/callback
OIDC_ALLOWED_GROUPS	comma-separated groups allowed in; required (the server refuses to start without it, because many providers allow open sign-up)
OIDC_DISPLAY_NAME	the name on the button, e.g. "Sign in with Acme"
OIDC_GROUPS_CLAIM	the token claim holding groups (default groups)
OIDC_COOKIE_SECRET	32 characters; keeps people signed in across restarts (random if unset)

Secrets reach oauth2-proxy through its environment, never its command line.