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

README: dx-maps ships two ways, the drop-in first and the subdomain container second

Browse source 
The deployment section named four hosting options, three of them CDN-shaped (Cloudflare Pages,
jsDelivr, Netlify). dx-maps now ships two routes, and the section says so in that order:

- The easiest path: drop-in. The folder goes into your own site's public/ and your site's server serves
  every map; bun run build && bun run dropin. One server, no PocketBase. It is the route the DX Life
  branches were proven on.
- Subdomain: the dx-maps container with PocketBase, for maps that need a backend of their own; the
  Dockerfile and compose.yaml at the repo root.

The notes that still hold stay (relative links, iframes, the one CORS header for JS embeds). The
quick start's own drop-in steps become a pointer to the route, and the cloud dev server is described
as following development, not main.
This commit is contained in:
Doxa Maps 2026-09-29 02:52:30 +00:00
parent af22670dfd
commit 7adf480f3d
1 changed files with 28 additions and 37 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

65
README.md
View file

@ -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).
<details>
<summary><b>More about hosting the folder</b></summary>
<summary><b>More about the folder</b></summary>
- **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/<owner>/<repo>@<tag>/public/dx-maps/<plugin>/<plugin>.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.
</details>
@ -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/<your-map>/`; 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).
<details>
<summary><b>Make changes to the studio itself</b></summary>
@ -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).
---