diff --git a/documentation/LAPTOP-6WAY.md b/documentation/LAPTOP-6WAY.md index b04818aa..905a97c7 100644 --- a/documentation/LAPTOP-6WAY.md +++ b/documentation/LAPTOP-6WAY.md @@ -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.`. 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 + `=@`: + - 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.`: 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 `=@`. - - 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.`. - - 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.