doxa-maps 18e0c39ed9 Laptop: the Plugin Studio route in LAPTOP-6WAY, and one route on port 4616 at a time

LAPTOP-6WAY described two routes. The third, the public Plugin Studio (bun run laptop plugin-studio),
had only its compose profile and the command's help. It now has its own section: what the command
starts, the addresses, the admin password for publishing and PocketBase's dashboard, how the two
per-request addresses are set, and what to set while dx-maps' development has no public mode yet.
"Checked" records what was proven on 2026-09-29, the halves separately, and says the one command
end to end has not been run yet.

The subdomain and Plugin Studio routes both publish the dx-maps container on port 4616. Starting one
while the other runs failed inside docker compose with a port error. bun run laptop now stops first
and says to run bun run laptop down.

2026-09-29 05:33:15 +00:00

11 KiB

Raw Blame History

The Research Gallery on your laptop: three routes

DX-life takes the dx-maps Research Gallery in three 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 drop-in and subdomain routes also run on the team's servers (the embed test: each route on a laptop and on a server). The Plugin Studio route's own server is still to come.

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
Plugin Studio	`research-gallery-plugin-studio`	the dx-maps container in its public mode (the Plugin Studio open to everyone, and its `/cdn` of production maps) + this site	yes, about 5 GB	yes, the container's own; its dashboard asks for the admin password

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 and Plugin Studio routes, Docker with Compose: each 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.

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

The first time is as for the subdomain route: .env.laptop needs GIT_TOKEN, and the first start takes 5-10 minutes. .env.laptop also gets an ADMIN_PASSWORD.
It builds the same dx-maps image from ../doxa-maps/Dockerfile, and runs dx-maps development in its public mode (ACCESS=public).
Public mode is new. If your dx-maps checkout's deployment/cloud/README.md has no "Public Studio" section, development doesn't have it yet: add DXMAPS_BRANCH=repo/public-studio-mode to .env.laptop until it lands.
It uses port 4616, as the subdomain route does, so run one of the two at a time (bun run laptop down first).

It starts two services, both on 127.0.0.1 only:

Address	What
http://localhost:4614/	this site, plugin-studio branch. The Research menu and `/regions` open the Studio; every map loads from the Studio's `/cdn`
http://research.localhost:4616/	the public Plugin Studio: every plugin, open to everyone, with no sign-in, as its public server will run it
http://research.localhost:4616/admin/status and `/pb/_/`	publishing and PocketBase's dashboard: user `admin`, password `ADMIN_PASSWORD` from `.env.laptop`

How it is wired:

This site reads both addresses per request, never at build time. The compose file sets them: NUXT_PUBLIC_RESEARCH_GALLERY_URL=http://research.localhost:4616/ and NUXT_PUBLIC_DX_MAPS_BASE=http://research.localhost:4616/cdn/dx-maps.
Publishing is automatic. About a minute after the container starts, and whenever main moves, it publishes main to /cdn. The snippets point at http://research.localhost:4616/cdn.
research.localhost works as in the subdomain route (Safari may need the /etc/hosts line).

Stop: bun run laptop down (data kept; --wipe deletes it).

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;
- Plugin Studio: plugin-studio=http://localhost:4614@http://research.localhost:4616/cdn/dx-maps/manifest.json.
The snippet passes only when the manifests carry the address they're served from:
- the subdomain and Plugin Studio routes bake it in by themselves;
- 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.

The Plugin Studio route was checked in two halves on 2026-09-29:

the public Studio container (dx-maps repo/public-studio-mode, ACCESS=public) ran on a server, tunnelled as above;
this site's plugin-studio branch ran as a dev server beside it, with the two addresses above.