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

The Research Gallery on your laptop: two routes

DX-life takes the dx-maps Research Gallery in two routes, one branch each. This page runs each of them on a laptop, so you can see and test them before any server is involved. The same two run on the team's servers; together that is the embed test (2 routes × laptop and server).

Route	DX-life branch	What runs	Docker	PocketBase
Drop-in (the default)	research-gallery-drop-in	this site alone; the maps are its own copy in public/dx-maps	no	no
Subdomain	research-gallery-subdomain	the dx-maps team container (Plugin Studio, PocketBase, the research site) + a local sign-in + this site	yes, about 5 GB	yes, for plugins that have users, an API or a database

The CDN route (research-gallery-cdn) was retired on 2026-09-29. Its branch is kept for history.

Before you start

• Checkouts side by side:

  doxa-maps/    dx-maps, on development (the team's table) or main (production)
  doxa-life/    this repo
  

• bun 1.3+ and node 20+. For the subdomain route, Docker with Compose: it uses about 1.4 GB, 2.5 GB while publishing; give Docker 4-6 GB.
• Once: cd doxa-life && bun install. The branches share one lockfile.

1. Drop-in (the default: one server, no Docker)

cd doxa-life && git switch research-gallery-drop-in
PORT=4611 bun run dev

Open http://localhost:4611/research/ (the Research Gallery) and http://localhost:4611/embed-test (every web plugin, embedded). There is no setting to change: the branch loads every map from its own /dx-maps/ (same origin), a copy committed with it. The first bun run dev compiles for about a minute; a page may answer 503 until it's done.

To try a newer dx-maps than the committed copy:

cd doxa-maps && EMBED_BASE_URL=http://localhost:4611 bun run tree   # seconds; only the two manifests change
bun run dropin                                                       # copies dx-maps/ into ../doxa-life/public
git restore public                                                   # dx-maps back to its committed folder

Afterwards, put the site's copy back: git restore public/dx-maps && git clean -fdq public/dx-maps.

2. Subdomain (the dx-maps team container, with PocketBase)

cd doxa-life && git switch research-gallery-subdomain
bun run laptop subdomain

The first time, it makes .env.laptop (secrets, never committed) and stops if GIT_TOKEN is empty.

• Put a read token for the team's git server there and run it again.
• It builds dx-maps' container from ../doxa-maps/Dockerfile, the image the team's server runs.
• Pull dx-maps development first. The first start takes 5-10 minutes: the container clones, installs and publishes.

It starts three services, all on 127.0.0.1 only:

Address	What
http://localhost:4613/	this site, subdomain branch. The Research menu and /regions open the research site
http://research.localhost:4615/	the research site: the gallery at /, /embed-test, and the maps under /dx-maps/, which this site embeds
http://localhost:4616/	the Plugin Studio, PocketBase (/pb), /cdn, /admin
http://localhost:4620/team	the local sign-in provider

Sign-in and roles, the same as the team's server:

• Sign in to the Studio as admin (everything, including publishing and the PocketBase dashboard) or designer (the Studio and PocketBase's API).
• Any other name is a plain team member, and is refused, as on the server.
• There's no password: the provider is a local stand-in.

How it is wired:

• research.localhost is your laptop's research.<host>. Chrome and Firefox send every *.localhost name to this computer. Safari may not: add 127.0.0.1 research.localhost to /etc/hosts.
• The sign-in provider runs inside the dx-maps container's network, so localhost:4620 means the same to your browser and to the container. No hosts-file entry is needed for sign-in.
• Publishing is automatic: a minute after main holds a new commit, the container rebuilds /cdn and the research site. The snippets point at http://research.localhost:4615.

If memory is short, the command says so before starting anything, and names what to close, or the lighter drop-in route.

Stop: bun run laptop down keeps PocketBase's data and the published build; bun run laptop down --wipe deletes them. bun run laptop status shows what's running.

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 route that means http://research.localhost:4615/?tab=regions-dashboard.
• 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>:
  • drop-in: drop-in=http://localhost:4611@http://localhost:4611/dx-maps/manifest.json;
  • subdomain: subdomain=http://research.localhost:4615@http://research.localhost:4615/dx-maps/manifest.json.
• The snippet passes only when the manifests carry the address they're served from:
  • the subdomain route bakes it in by itself;
  • for the drop-in, regenerate the manifests as shown in 1.

Without Docker, the subdomain route by hand (no PocketBase)

Two terminals. dx-maps serves its built folder (loopback only), and this site points its research links at it.

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

The dx-maps server does not list directories, so the gallery address ends in /index.html. Afterwards: cd doxa-maps && git restore public.

Checked

The subdomain route was run on 2026-09-29 with this branch's compose.laptop.yaml.

• Docker ran on a server, because the checking box has no Docker. Its ports were tunnelled to a Linux box's localhost, standing in for the laptop's browser.
• The dx-maps image was built from development's root Dockerfile. The container cloned development and, 2.5 minutes after it started, published main (93061d2) by itself.

Results:

• 20 of 20 route checks passed:
  • the sign-in provider answers on the same address inside and outside;
  • a plain member is refused;
  • designer gets the Studio, but not the PocketBase dashboard or publishing;
  • admin gets all three;
  • PocketBase's team API is open, with sign-in through the team provider;
  • the research site serves the gallery at / and a manifest whose snippets point at http://research.localhost:4615;
  • /regions on this site goes to http://research.localhost:4615/?tab=regions-dashboard.
• check-embed-6way on subdomain=http://research.localhost:4615@…/dx-maps/manifest.json: 7 of 7 production maps pass all 6 checks, the snippet included.
• Memory once running: dx-maps 0.3 GB, this site 0.9 GB, the sign-in provider 0.15 GB. The first publish added about 1 GB for a minute.