1bbfeae07c
Laptop (bun run dev, zero config); a shared cloud dev server (Docker or Coolify, with a persistent /data); public embeds from /cdn or any static host; the built folder inside a site's public/, as DX-life does. Each with the command, what you get, and the detailed doc.
94 lines
5 KiB
Markdown
94 lines
5 KiB
Markdown
# Deploying dx-maps — the 4 ways it ships
|
|
|
|
dx-maps is one repo that runs in four places. Two are for **building** maps (your laptop, a shared
|
|
cloud dev server); two are for **showing** them (public embeds, a folder inside your own site). The
|
|
building ones run the live source with hot reload; the showing ones serve the **built** folder,
|
|
`dx-maps/`, which is checked for private files before it is published.
|
|
|
|
| # | Where | For | What you run | What you get |
|
|
|---|---|---|---|---|
|
|
| 1 | **Your laptop** | building, alone or with a team | `bun run dev` | the Plugin Studio at http://localhost:5173 |
|
|
| 2 | **A shared cloud dev server** | a team, or an agent on a server | the Docker image in `deployment/cloud/` | the Plugin Studio at `https://<your-host>/`, behind your team's sign-in |
|
|
| 3 | **Public embeds** | other sites showing a map | the built `dx-maps/` folder on `/cdn` or any static host | `https://<host>/…/dx-maps/<plugin>/<profile>/index.html` and `…/<plugin>/<plugin>.js` |
|
|
| 4 | **Inside your own site** | one site hosting every map | copy `dx-maps/` into the site's `public/` | the maps at `https://<your-site>/<folder>/…` |
|
|
|
|
---
|
|
|
|
## 1. Your laptop — `bun run dev`
|
|
|
|
```bash
|
|
git clone --depth 1 https://git.nuxtbase.app/doxa-open/doxa-maps.git
|
|
cd doxa-maps
|
|
bun install --frozen-lockfile
|
|
bun run dev # → http://localhost:5173/ is the Plugin Studio
|
|
```
|
|
|
|
Zero config: no `.env` is needed. Everything is local by default — hot reload of your own edits, a local
|
|
PocketBase at `/api/pb`, and Rudder's voice engine once it is set up (Go 1.22+, then
|
|
`bash backend/rudder-engine/setup-runtime.sh`). Every setting, with its default,
|
|
is in [`.env.example`](../.env.example); an empty value means the default.
|
|
|
|
- Follow what teammates land on a shared branch: set `DX_SYNC_REMOTE` (a remote name or a repo URL).
|
|
- Use the team's shared PocketBase instead of a local one: set `DX_PB_URL`.
|
|
|
|
Details: [HOWTO-join-the-table.md](./HOWTO-join-the-table.md).
|
|
|
|
## 2. A shared cloud dev server — Docker or Coolify, with `/data`
|
|
|
|
One running copy of the Plugin Studio that follows a branch and hot-reloads every push, for a whole team
|
|
or for an agent that lives on a server. Nobody edits files on it: changes arrive by pushing.
|
|
|
|
```bash
|
|
docker build -t dx-maps-dev deployment/cloud
|
|
docker run -d -p 5173:5173 -v dx-maps-data:/data \
|
|
-e REPO_URL=https://<host>/<owner>/<repo>.git -e BRANCH=main dx-maps-dev
|
|
```
|
|
|
|
Or paste `deployment/cloud/Dockerfile` into a container host (Coolify's "Dockerfile" build pack) and give
|
|
it a domain.
|
|
|
|
- **Give it a persistent `/data` volume.** It holds the team PocketBase (dev and prod) and the last
|
|
published build. Without one, every restart or redeploy starts empty.
|
|
- **Put the sign-in in front** before it is reachable from the internet: the `OIDC_*` settings. Only the
|
|
groups you allow get in.
|
|
- About **2.5 GB of memory and 2 vCPUs**.
|
|
|
|
It also serves the **team PocketBase** at `/pb/` and, after an admin triggers a build, the **public
|
|
embed folder** at `/cdn/` (way 3).
|
|
|
|
Details: [deployment/cloud/README.md](../deployment/cloud/README.md) and
|
|
[CLOUD-DEVELOPMENT-ENVIRONMENT.md](./CLOUD-DEVELOPMENT-ENVIRONMENT.md).
|
|
|
|
## 3. Public embeds — `/cdn` or any static host
|
|
|
|
The built folder, `dx-maps/`, is what other sites embed. Every link inside it is relative, so it works
|
|
from any address.
|
|
|
|
- **From the cloud dev server:** an admin runs a build (`POST /admin/build`; about 2 minutes). It builds
|
|
the current commit, removes private files, refuses to publish if any remain, then swaps
|
|
`/cdn/dx-maps/` over atomically. `/cdn/` is public (no sign-in) and sends
|
|
`Access-Control-Allow-Origin: *`, so both iframes and JS embeds work on other sites.
|
|
- **On any static host:** build locally with `BUILD_ALLOW=1 bun run build` and upload `public/dx-maps/`.
|
|
For JS embeds on other sites, the host must send `Access-Control-Allow-Origin: *`.
|
|
|
|
Every page loads its script with an integrity hash, so a tampered or stale script is refused by the
|
|
browser. The Plugin Studio's "copy embed" gives you the iframe and the script snippet for each map.
|
|
|
|
Details, per host (Cloudflare Pages, jsDelivr, any web server) and per embed style:
|
|
[README — What the build makes](../README.md#what-the-build-makes--3-outputs) and
|
|
[README-SECTION-3-cli-commands.md](./README-SECTION-3-cli-commands.md).
|
|
|
|
## 4. Inside your own site — the folder in `public/`
|
|
|
|
Copy the built `dx-maps/` folder into your site's `public/` (renaming it is fine) and your site becomes
|
|
the host: no second server and no cross-site setup, because the maps and the page share one origin.
|
|
|
|
**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 DX-life's `public/` and fills `/research` with the Research Gallery. Run it with
|
|
`bun install && bun run dev`, then open `/research/`.
|
|
|
|
---
|
|
|
|
**Which one?** Building maps: **1**, plus **2** if several people or agents work together. Showing maps
|
|
on other sites: **3**. Showing them on a site you already run: **4**.
|