doxa-maps-cdn/documentation/LAPTOP-6WAY.md

The three research-gallery ways, on your laptop

DX-life can take the dx-maps Research Gallery in three ways, one branch each. This page runs each of them on a laptop, against a local dx-maps checkout, so you can see and test all three before any server is involved. The same three also run on the team's servers; together they are the "6-way" embed test (3 ways × laptop and server).

Way	DX-life branch	Where the maps come from	Servers
Drop-in	research-gallery-drop-in	the dx-maps folder copied into this site's public/dx-maps	1
CDN	research-gallery-cdn	a dx-maps server (here: your laptop, port 4610)	2
Subdomain	research-gallery-subdomain	the same dx-maps server; the Research link opens the gallery on it	2

Before you start

• Two checkouts side by side (the commands below use these relative paths):

  doxa-maps/    dx-maps, on development (the team's table) or main (production)
  doxa-life/    this repo, one research-gallery-* branch at a time
  

• bun 1.3+ and node 20+.

• Memory: a DX-life dev server holds 1–2.5 GB. Run one way at a time unless your laptop has room to spare.

• Ports. None of these collides with dx-maps' own bun run dev (the Plugin Studio, 5173) or DX-life's default (3000). Use a different one if the log says a port is busy.

  What	Port
  dx-maps tree server (CDN, Subdomain)	4610
  DX-life, drop-in	4611
  DX-life, CDN	4612
  DX-life, subdomain	4613

• Once: cd doxa-life && bun install. The three branches share one lockfile, so switching branches needs no new install.

The first bun run dev compiles for about a minute. The first page may answer 503 until it finishes; then reload. The first time a browser opens a page, Vite may reload it once while it prepares dependencies.

1. Drop-in (one server)

cd doxa-life && git switch research-gallery-drop-in
rm -rf public/dx-maps && cp -R ../doxa-maps/public/dx-maps public/dx-maps
PORT=4611 bun run dev

There is no setting to change. This branch loads every map from its own /dx-maps/ (same origin), so the copy you just made is what it serves. Open:

• http://localhost:4611/research/ (the Research Gallery)
• http://localhost:4611/embed-test (every web plugin, embedded)

Afterwards, the branch keeps its own committed copy of the folder, so put it back: git restore public/dx-maps && git clean -fdq public/dx-maps.

2. CDN (two servers)

Terminal A, dx-maps serves its built folder like a CDN (loopback only; CORS on, which a cross-site script with an integrity hash needs; directories are not listed, as on production):

cd doxa-maps && PORT=4610 bun run serve

Terminal B, DX-life loads every map from it:

cd doxa-life && git switch research-gallery-cdn
NUXT_PUBLIC_DX_MAPS_BASE=http://localhost:4610/dx-maps PORT=4612 bun run dev

One setting: NUXT_PUBLIC_DX_MAPS_BASE, where the maps come from. Without it, the branch loads the team's public CDN. Open http://localhost:4612/research/ and http://localhost:4612/embed-test.

3. Subdomain (two servers)

Terminal A, the same dx-maps server as in 2.

Terminal B:

cd doxa-life && git switch research-gallery-subdomain
NUXT_PUBLIC_DX_MAPS_BASE=http://localhost:4610/dx-maps \
NUXT_PUBLIC_RESEARCH_GALLERY_URL=http://localhost:4610/dx-maps/doxa-maps-spa/doxa-maps-spa/index.html \
PORT=4613 bun run dev

Two settings.

• NUXT_PUBLIC_RESEARCH_GALLERY_URL is "the subdomain": the Research menu item, and every research link, opens the gallery there, adding ?tab= and ?lang=. The dx-maps server does not list directories, so the address ends in /index.html.
• NUXT_PUBLIC_DX_MAPS_BASE is for the maps DX-life still embeds on its own pages (home, pray, adopt, /embed-test). Leave it out, and those load from the team's public CDN instead of your laptop.

Open http://localhost:4613/, use the Research menu item, and open http://localhost:4613/embed-test.

What "working" looks like

• /embed-test: the production cards mount and draw their maps, with 0 page errors and 0 iframes (/ar/embed-test runs the same test right to left).
• /research/?tab=regions-dashboard opens the gallery on its Regions tab, and /regions redirects there. On the subdomain branch, both open the gallery on port 4610.
• Headless, dx-base's check-embed-6way.mjs (in the fleet's QA folder) checks, for every production plugin: the script, its integrity hash, its element, its page, CORS, and the copy-paste snippet.
  • The label reads <name>=<site origin>@<manifest URL>.
  • For the CDN way, the site is http://localhost:4612 and the manifest is on 4610.
  • For the Subdomain way, both are on 4610, as for the team's research.<host>.
  • The snippet check fails on the folder as committed: its copy-paste snippets are relative, so a pasted snippet points at the page it was pasted on. That is the same on the servers.

To make the snippets pasteable too, regenerate the folder's manifests with the address it is served from. It takes seconds and rebuilds nothing; only the two manifest files change.

cd doxa-maps
EMBED_BASE_URL=http://localhost:4610 bun run tree   # CDN and Subdomain: the tree server
EMBED_BASE_URL=http://localhost:4611 bun run tree   # Drop-in: this site; then copy the folder again, as in 1
git restore public                                  # afterwards, back to the committed folder

Stopping

Press Ctrl-C in each terminal. On the drop-in branch, restore the folder as shown in 1.

Checked

These exact commands were run on 2026-09-29 on a Linux box standing in for a laptop:

• dx-maps: development at 93061d2.
• DX-life: drop-in 97449c5, cdn 47e8f62, subdomain f3e4623 plus the /regions redirect fix.

Results:

• All three served /, /research/ and /embed-test.
• /regions redirected to the gallery's Regions tab.
• The headless check passed script, integrity hash, element, page and CORS for all 7 production plugins in each way. Only the snippet failed, for the reason above; the team's servers give the same result.
• With the manifests regenerated as shown above (4611 for drop-in, 4610 for CDN and Subdomain), all 21 checks passed 6 of 6, the snippet included.
• A DX-life dev server held about 1.2–1.5 GB.