doxa-maps/documentation/DEPLOY.md

Deploying dx-maps — the 4 ways it ships

dx-maps is one repo that runs in four places. Two are for building maps (your laptop, a shared cloud dev server); two are for showing them (public embeds, a folder inside your own site). The building ones run the live source with hot reload; the showing ones serve the built folder, dx-maps/, which is checked for private files before it is published.

#	Where	For	What you run	What you get
1	Your laptop	building, alone or with a team	bun run dev	the Plugin Studio at http://localhost:5173
2	A shared cloud dev server	a team, or an agent on a server	the Docker image in deployment/cloud/	the Plugin Studio at https://<your-host>/, behind your team's sign-in
3	Public embeds	other sites showing a map	the built dx-maps/ folder on /cdn or any static host	https://<host>/…/dx-maps/<plugin>/<profile>/index.html and …/<plugin>/<plugin>.js
4	Inside your own site	one site hosting every map	copy dx-maps/ into the site's public/	the maps at https://<your-site>/<folder>/…

---

1. Your laptop — bun run dev

git clone --depth 1 https://git.nuxtbase.app/doxa-open/doxa-maps.git
cd doxa-maps
bun install --frozen-lockfile
bun run dev          # → http://localhost:5173/  is the Plugin Studio

Zero config: no .env is needed. Everything is local by default — hot reload of your own edits, a local PocketBase at /api/pb, and Rudder's voice engine once it is set up (Go 1.22+, then bash backend/rudder-engine/setup-runtime.sh). Every setting, with its default, is in .env.example; an empty value means the default.

• Follow what teammates land on a shared branch: set DX_SYNC_REMOTE (a remote name or a repo URL).
• Use the team's shared PocketBase instead of a local one: set DX_PB_URL.

Details: HOWTO-join-the-table.md.

2. A shared cloud dev server — Docker or Coolify, with /data

One running copy of the Plugin Studio that follows a branch and hot-reloads every push, for a whole team or for an agent that lives on a server. Nobody edits files on it: changes arrive by pushing.

docker build -t dx-maps-dev deployment/cloud
docker run -d -p 5173:5173 -v dx-maps-data:/data \
  -e REPO_URL=https://<host>/<owner>/<repo>.git -e BRANCH=main dx-maps-dev

Or paste deployment/cloud/Dockerfile into a container host (Coolify's "Dockerfile" build pack) and give it a domain.

• Give it a persistent /data volume. It holds the team PocketBase (dev and prod) and the last published build. Without one, every restart or redeploy starts empty.
• Put the sign-in in front before it is reachable from the internet: the OIDC_* settings. Only the groups you allow get in.
• About 2.5 GB of memory and 2 vCPUs.

It also serves the team PocketBase at /pb/ and, after an admin triggers a build, the public embed folder at /cdn/ (way 3).

Details: deployment/cloud/README.md and CLOUD-DEVELOPMENT-ENVIRONMENT.md.

3. Public embeds — /cdn or any static host

The built folder, dx-maps/, is what other sites embed. Every link inside it is relative, so it works from any address.

• From the cloud dev server: /cdn/ serves the production branch, never main. main is the shared sandbox where everyone lands all day; production moves only when you decide the current state is ready to be public. The container notices when production moves and rebuilds /cdn by itself (about 2 minutes after the move, then about 2 minutes to build). Each build removes private files, refuses to publish if any remain, keeps the last good build if anything fails, and swaps /cdn/dx-maps/ over atomically. /cdn/ is public (no sign-in) and sends Access-Control-Allow-Origin: *, so both iframes and JS embeds work on other sites.

  To publish (promote main to production), once the checks pass on the commit you want public:

  git fetch origin && git checkout main && git merge --ff-only origin/main
  bun run gates:pre                   # the checks must pass on exactly this commit
  git push origin main:production     # /cdn follows within a few minutes
  

  An admin can also rebuild at once (POST /admin/build), and /admin/status shows what /cdn serves and what production points at.

• On any static host: build locally with BUILD_ALLOW=1 bun run build and upload public/dx-maps/. For JS embeds on other sites, the host must send Access-Control-Allow-Origin: *.

Every page loads its script with an integrity hash, so a tampered or stale script is refused by the browser. The Plugin Studio's "copy embed" gives you the iframe and the script snippet for each map.

Details, per host (Cloudflare Pages, jsDelivr, any web server) and per embed style: README — What the build makes and README-SECTION-3-cli-commands.md.

4. Inside your own site — the folder in public/

Copy the built dx-maps/ folder into your site's public/ (renaming it is fine) and your site becomes the host: no second server and no cross-site setup, because the maps and the page share one origin.

Live example: the DX-life branch research-gallery drops the folder into DX-life's public/ and fills /research with the Research Gallery. Run it with bun install && bun run dev, then open /research/.

---

Which one? Building maps: 1, plus 2 if several people or agents work together. Showing maps on other sites: 3. Showing them on a site you already run: 4.