diff --git a/README.md b/README.md index aa5462426..8c6bf9da8 100644 --- a/README.md +++ b/README.md @@ -369,38 +369,37 @@ put it* and *how a page shows it*. Two questions: **where does the folder go** (hosting), and **how does a page show a map** (embedding). -#### Where the folder goes +#### Where the folder goes: two routes -| Put the folder… | How | iframe | JS embed | Good to know | -|---|---|:-:|:-:|---| -| **in dx-life's `public/` folder** | copy one folder; dx-life becomes the host | ✅ | ✅ | this is how the Research Gallery runs on the dx-life research page (below) | -| **on Cloudflare Pages** | drag and drop the folder in the dashboard | ✅ | ✅ | fits the drag-and-drop limits (1,000 files, 25 MiB per file); add the `_headers` file below for JS embeds on other sites | -| **on GitHub, served by jsDelivr** | push the repo to a public GitHub repo | — | ✅ | a free CDN for scripts; it serves HTML as plain text, so iframes won't render — use it for JS embeds only | -| **on any web server** | copy the folder | ✅ | ✅ | send `Access-Control-Allow-Origin: *` for JS embeds on other sites | +**The easiest path: drop-in.** The folder goes into your own site's `public/`, and your site's own server +serves every map: one server, no PocketBase, nothing else to run. Set `dropin.dest` in +`vite.doxa-maps-build-config.json` to your site's `public/` (the default is `../doxa-life/public`), then: -**Live example:** the dx-life branch [`research-gallery`](https://git.nuxtbase.app/doxa-life/doxa-maps-cdn/src/branch/research-gallery) drops this folder into dx-life's `public/` and fills `/research` with the Research Gallery. Run it with `bun install && bun run dev`, then open `/research/`. +```bash +bun run build && bun run dropin # copies dx-maps/ into your site's public/; the rest of the site is left alone +``` + +This is the route the three DX Life branches were proven on: real pages rendering maps, one server, +all seven drop-in checks passing. Live example: the dx-life branch +[`research-gallery`](https://git.nuxtbase.app/doxa-life/doxa-maps-cdn/src/branch/research-gallery) +drops the folder into `public/` and fills `/research` with the Research Gallery (`bun install && bun run dev`, +then open `/research/`). + +**Subdomain: the dx-maps container with PocketBase.** When maps need a backend of their own (accounts, +saved data, an API for mobile apps), run the dx-maps container on its own subdomain, such as +`maps.your-site`. It serves the same folder with PocketBase beside it, and its schema ships as migration +files in the repo. The `Dockerfile` and `compose.yaml` sit at the repo root; recipe and settings: +[deployment/cloud/](./deployment/cloud/README.md).
-More about hosting the folder +More about the folder -- **The folder works from any address.** Every link inside it is relative, so you can put it at - `https://your-site/dx-maps/` or at a CDN root and nothing breaks (`bun run check:drop` proves it). +- **The folder works from any address.** Every link inside it is relative, so it can sit at + `https://your-site/dx-maps/` or at the root of a subdomain and nothing breaks (`bun run check:drop` proves it). - **iframes need nothing special.** A map's page loads inside the frame from wherever the folder is. - **JS embeds on another site need one header.** The embed loads scripts and `manifest.json` across - sites with a security hash, so the host must allow it. On Cloudflare Pages (or Netlify), put a file - named `_headers` in the folder you upload: - - ```text - /* - Access-Control-Allow-Origin: * - ``` - -- **jsDelivr** serves any public GitHub repo as a CDN, e.g. - `https://cdn.jsdelivr.net/gh//@/public/dx-maps//.js`. It needs a - **GitHub** repo (this project's public copy is on its own git host), files under 20 MB (the largest - here is 7.5 MB), and it returns HTML as plain text — hence scripts only. -- **Netlify Drop** (drag and drop at app.netlify.com/drop) works best under 50 MB; at about 80 MB, use the - Netlify CLI instead. + sites with a security hash, so the host must allow it: `Access-Control-Allow-Origin: *`. The + container sends it; a drop-in needs it only if other sites embed from yours.
@@ -688,15 +687,7 @@ bun run dev # → open the URL Vite prints: that page is the No build needed first — the built maps are already in the repo. To start a plugin, copy `plugin-designs/template-bundle/` to `plugin-designs//`; the studio finds it automatically. -### The easiest path: one server for your site and its maps - -1. **Work in the studio.** `bun run dev` opens the Plugin Studio (with voice, if you set up Rudder above): - build and try maps there; they update as you save. -2. **Point the drop-in at your site.** In `vite.doxa-maps-build-config.json`, set `dropin.dest` to your - site's `public/` folder (the default is `../doxa-life/public`). -3. **Build and drop in.** `bun run build && bun run dropin` copies the maps into your site's - `public/dx-maps/`, and your site's own server serves them: one server, nothing else to deploy. - The drop-in touches only `dx-maps/`; the rest of your site is left alone. +To put the maps on your own site, take [the easiest path: drop-in](#where-the-folder-goes-two-routes).
Make changes to the studio itself @@ -740,15 +731,15 @@ The studio is a plugin like any other: `plugin-designs/plugin-studio/plugin-stud ### Run it in the cloud **One shared dev server for the whole team, no laptop setup.** A container clones the repo, follows -`main`, and hot-reloads every change an agent lands, so everyone sees the Plugin Studio update in +`development`, and hot-reloads every change an agent lands, so everyone sees the Plugin Studio update in their browser within seconds, with no rebuild. Add OIDC settings and it puts a "Sign in with *your provider*" page in front of everything, open only to the groups you allow. Recipe and settings: [deployment/cloud/](./deployment/cloud/README.md). Working from your own laptop alongside the team (zero config, everything local by default): [documentation/HOWTO-join-the-table.md](./documentation/HOWTO-join-the-table.md). When your agent runs on a server instead: [documentation/CLOUD-DEVELOPMENT-ENVIRONMENT.md](./documentation/CLOUD-DEVELOPMENT-ENVIRONMENT.md). -All four ways dx-maps ships (laptop, shared cloud dev server, public embeds, a folder in your own site): -[documentation/DEPLOY.md](./documentation/DEPLOY.md). +The two ways dx-maps ships (a drop-in into your own site, or the container on its own subdomain): +[the two routes](#where-the-folder-goes-two-routes) and [documentation/DEPLOY.md](./documentation/DEPLOY.md). ---