doxa-life/doxa-maps-cdn
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

LAPTOP-6WAY: two routes, drop-in (this branch, no Docker) and subdomain (the container)

Browse source 
The same page as on the subdomain branch. The CDN route is retired, and its branch is kept
for history. This branch is the default route: PORT=4611 bun run dev, with no setting to
change. To try a newer dx-maps: bun run tree with this site's address, then dx-maps' bun run
dropin.
This commit is contained in:
doxa-maps 2026-09-29 03:35:51 +00:00
parent 909542b375
commit a35daff498
1 changed files with 106 additions and 108 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

214
documentation/LAPTOP-6WAY.md
View file

@ -1,142 +1,140 @@
# The three research-gallery ways, on your laptop
# The Research Gallery on your laptop: two routes
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).
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).
| 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 |
| 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
- **Two checkouts side by side** (the commands below use these relative paths):
- **Checkouts side by side:**
```
doxa-maps/ dx-maps, on development (the team's table) or main (production)
doxa-life/ this repo, one research-gallery-* branch at a time
doxa-life/ this repo
```
- **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.
- **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.
| 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)
## 1. Drop-in (the default: one server, no Docker)
```bash
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:
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.
- 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):
**To try a newer dx-maps** than the committed copy:
```bash
cd doxa-maps && PORT=4610 bun run serve
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
```
**Terminal B**, DX-life loads every map from it:
Afterwards, put the site's copy back: `git restore public/dx-maps && git clean -fdq public/dx-maps`.
```bash
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:**
## 2. Subdomain (the dx-maps team container, with PocketBase)
```bash
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.
```bash
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
```
**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`.
- `research.localhost` is your laptop's `research.<host>`: the gallery gets its own origin, as on the team's
server, while the maps stay on `localhost:4610`. Chrome and Firefox send every `*.localhost` name to this
computer. Safari and command-line tools may not: for them, add `127.0.0.1 research.localhost` to `/etc/hosts`.
- `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 at `research.localhost: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 `research.localhost: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.
```bash
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.
The dx-maps server does not list directories, so the gallery address ends in `/index.html`. Afterwards:
`cd doxa-maps && git restore public`.
## 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.
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:
- 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.
- **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.