diff --git a/README.MD b/README.MD index 28c83fc..f3757f1 100644 --- a/README.MD +++ b/README.MD @@ -28,8 +28,9 @@ cd ../.. && npm run gate:0 Gates (`npm run gate:N`) continue the middleware plan in [TODO.md](TODO.md). Phases 0–8, 10, 11 already passed in the source tree; 9 and 12+ are still open. Path prefixes now use `packages/`. +**Bring online:** https://zapier.georgelambert.org/packages/verae-ops/GETTING-STARTED.pdf **Live catalog (PDF default):** https://zapier.georgelambert.org/ · [Markdown indexes](https://zapier.georgelambert.org/index-md.html) -**Install / Docker / Proxmox / metal:** https://zapier.georgelambert.org/packages/verae-ops/README.pdf +**Billing / users (zappier-edge):** https://zapier.georgelambert.org/packages/zappier/docs/USER-MANUAL.pdf **Sphinx:** https://zapier.georgelambert.org/sphinx/ · [LaTeX PDF](https://zapier.georgelambert.org/sphinx/verae-zapier-modules.pdf) ## Documentation map diff --git a/docs/00-sources/provenance.md b/docs/00-sources/provenance.md index 4e17975..4f9e971 100644 --- a/docs/00-sources/provenance.md +++ b/docs/00-sources/provenance.md @@ -4,7 +4,7 @@ This workspace composes three existing trees. Canonical work after import is her | Package / tree | Imported from | Role | |----------------|---------------|------| -| `packages/zappier` | `/Users/marchon/zappier` | Commercial platform: custom rate card, tiers, API keys, customer portal, admin, Stripe meter, PO invoices, usage ledger. Demo `/v1/transform` and `/v1/storage` are **not** Verae. | +| `packages/zappier` (**zappier-edge**) | Standalone git tree `/Users/marchon/zappier` (no GitHub remote; published at https://git.georgelambert.org/marchon/zappier-edge) | **Billing and user middleware:** custom rate card, tiers, API keys, customer portal, admin users, Stripe meter, PO invoices, usage ledger. Demo `/v1/transform` and `/v1/storage` are **not** Verae. | | `packages/verae-zapier-middleware` | `/Users/marchon/datacubes/verae-zapier-api/verae-zapier-middleware` | Verae timestamp adapter: `/zapier/v1/*`, MOCK_VERAE, NATS workers, REST Hooks. Coarse `PLAN_LIMITS` — not used on the public edge after composition. | | `packages/verae-zapier` | `/Users/marchon/datacubes/verae-zapier-api/verae-zapier` | Zapier Platform CLI app (JS). Today talks to middleware with `zmw_` keys; will talk to zappier `x-api-key` after PR 5. | | `vendor/zapier-platform` | `/Users/marchon/research/zapier-platform` (upstream `git@github.com:zapier/zapier-platform.git`) | Official CLI/core/schema/examples. Reference only; do not fork for product code. | diff --git a/packages/overview/INDEX.md b/packages/overview/INDEX.md index 547a7bd..ce83659 100644 --- a/packages/overview/INDEX.md +++ b/packages/overview/INDEX.md @@ -1,6 +1,8 @@ # Documentation index -Read **high-level first**, then **architecture**, then the rest. Live catalog (PDF by default): https://zapier.georgelambert.org/ — [Markdown indexes](https://zapier.georgelambert.org/index-md.html) +**Bring the system online:** https://zapier.georgelambert.org/packages/verae-ops/GETTING-STARTED.pdf + +Live catalog (PDF by default): https://zapier.georgelambert.org/ — [Markdown indexes](https://zapier.georgelambert.org/index-md.html) Operator console (loopback): http://127.0.0.1:3850/ · [CONSOLE.pdf](https://zapier.georgelambert.org/packages/verae-fleet/docs/CONSOLE.pdf) diff --git a/packages/overview/README.md b/packages/overview/README.md index 7488ca7..0f53d3f 100644 --- a/packages/overview/README.md +++ b/packages/overview/README.md @@ -3,6 +3,7 @@ High-level description of the whole system: what it is, which **independent git repositories** implement it, how it stays up, how it behaves when the local network fails, and how it talks to the **central Verae NATS.IO 3-server cluster**. New work is added by **new address routing**, not by teaching Zapier about NATS. **This repo:** https://git.georgelambert.org/marchon/overview +**Bring online:** https://zapier.georgelambert.org/packages/verae-ops/GETTING-STARTED.pdf **Live catalog (PDF by default):** https://zapier.georgelambert.org/ · [Markdown indexes](https://zapier.georgelambert.org/index-md.html) **Clone:** `ssh://git@git.georgelambert.org:2223/marchon/overview.git` diff --git a/packages/verae-ops/GETTING-STARTED.md b/packages/verae-ops/GETTING-STARTED.md new file mode 100644 index 0000000..d4539e1 --- /dev/null +++ b/packages/verae-ops/GETTING-STARTED.md @@ -0,0 +1,95 @@ +# Bring Verae Time × Zapier online + +This is the **top document** for install, first-up, and monitoring. Platform-specific detail lives in the numbered ops chapters; do not start there. + +**Catalog:** https://zapier.georgelambert.org/packages/verae-ops/GETTING-STARTED.pdf +**Billing / users (zappier-edge):** https://zapier.georgelambert.org/packages/zappier/docs/USER-MANUAL.pdf +**Operator console:** http://127.0.0.1:3850/ (loopback) · https://zapier.georgelambert.org/packages/verae-fleet/docs/CONSOLE.pdf + +## What you are turning on + +| Piece | Job | Default | +|-------|-----|---------| +| **zappier-edge** | Billing, API keys, customer portal, admin, Stripe | `:3000` public HTTPS | +| **verae-middleware** | Zapier `/zapier/v1`, chain, NATS | `:3100` | +| **NATS JetStream** | Private jobs / archive | `:4222` **not public** | +| **worm ×3, tree-node ×3** | Off-chain files and Merkle leaves | fleet floor | +| **fleet** | Replica floors, SSH hosts, Trace, Docs | `:3850` loopback | + +Zapier cloud talks **only** to zappier-edge over HTTPS. + +The billing and user platform is the standalone **zappier** project (`/Users/marchon/zappier`, Forgejo [zappier-edge](https://git.georgelambert.org/marchon/zappier-edge)): portal signup, TOTP, API keys, rate card, Stripe meter, PO invoices, admin users. Verae middleware does **not** replace it. + +## 15-minute lab (one machine) + +```bash +git clone ssh://git@git.georgelambert.org:2223/marchon/master-zapier-plan-draft.git +cd master-zapier-plan-draft +export MONOREPO="$PWD" +cd packages/verae-ops +docker compose up --build +``` + +Check: + +```bash +curl -fsS http://127.0.0.1:3000/health # zappier-edge (billing + users) +curl -fsS http://127.0.0.1:3100/health # middleware +``` + +Open: + +- Customer portal: http://127.0.0.1:3000/portal — sign up, copy `x-api-key` +- Admin: http://127.0.0.1:3000/admin +- API docs: http://127.0.0.1:3000/docs + +Do **not** publish NATS `4222`. + +## Operator console (monitor) + +On the same machine (or SSH tunnel `ssh -L 3850:127.0.0.1:3850 user@host`): + +```bash +cd "$MONOREPO/packages/verae-fleet" +node src/cli.js serve +``` + +http://127.0.0.1:3850/ — Fleet (green/yellow/red), Trace, Docs. Tree-node **min 3**; pause does not count. + +```bash +node src/cli.js status +node src/cli.js ssh-check ns1 +``` + +## Point Zapier at the lab + +1. TLS in front of `:3000` (Caddy). +2. Zapier app env: `MIDDLEWARE_BASE_URL=https://` (edge meters, then proxies to middleware). +3. Connect with the portal API key. + +## Production (pick one) + +| Where | Read | +|-------|------| +| Docker | [02-docker.pdf](02-docker.pdf) | +| Proxmox | [03-proxmox.pdf](03-proxmox.pdf) | +| Cloud VMs | [04-virtual-servers.pdf](04-virtual-servers.pdf) | +| Dedicated / NS1 | [05-dedicated-hardware.pdf](05-dedicated-hardware.pdf) | +| Env vars & NATS | [06-linking-services.pdf](06-linking-services.pdf) | +| Backup / upgrade | [07-maintenance.pdf](07-maintenance.pdf) | + +## Daily monitor + +| Check | Expect | +|-------|--------| +| `curl -fsS https://zappier.example.com/health` | 200 | +| `curl -fsS https://middleware.example.com/health` | 200 | +| NATS `http://127.0.0.1:8222/healthz` on each node | ok (localhost only) | +| Fleet tree-node available ≥ 3 | green | +| Portal login + key still works | 200 `/v1/status` with `x-api-key` | + +## If something is red + +1. Fleet row color: yellow = paused/degraded, red = below floor — `restart` that replica. +2. 401/402 from Zapier → zappier-edge keys and rate card, not NATS. +3. Archive lookup empty → bloom miss is **silence**; check worm/tree floors, not “error replies”. diff --git a/packages/verae-ops/README.md b/packages/verae-ops/README.md index ad9715f..d4895d2 100644 --- a/packages/verae-ops/README.md +++ b/packages/verae-ops/README.md @@ -11,6 +11,7 @@ This is the operations repo. Application code lives in the other independent git ## Reading order +0. **[GETTING-STARTED.md](GETTING-STARTED.md)** — install, first-up, monitor (read this first) 1. [01-dependencies.md](01-dependencies.md) — what must exist, who talks to whom 2. [02-docker.md](02-docker.md) — Compose (NATS 3-node cluster + HTTPS edges) 3. [03-proxmox.md](03-proxmox.md) — LXC / QEMU VMs diff --git a/packages/zappier/README.md b/packages/zappier/README.md index 8d123a4..a9f0763 100644 --- a/packages/zappier/README.md +++ b/packages/zappier/README.md @@ -5,8 +5,11 @@ monthly credits, a usage ledger, Stripe metered billing, purchase-order invoicing, a company admin console, a self-service customer portal, and a Zapier integration. +This is the **billing and user platform** (originally the standalone `zappier` git tree at `~/zappier`). Forgejo name: **zappier-edge**. It owns signup, TOTP, API keys, rate card, Stripe meter, PO invoices, admin users, and the customer portal. Verae middleware does not replace this. + **Forgejo:** https://git.georgelambert.org/marchon/zappier-edge -**Catalog README:** https://zapier.georgelambert.org/packages/zappier/README.pdf +**Catalog README:** https://zapier.georgelambert.org/packages/zappier/README.pdf +**Bring the whole system online:** https://zapier.georgelambert.org/packages/verae-ops/GETTING-STARTED.pdf ## Documentation (public PDFs) diff --git a/scripts/build-docs-site.py b/scripts/build-docs-site.py index a8a9d55..15e9267 100755 --- a/scripts/build-docs-site.py +++ b/scripts/build-docs-site.py @@ -21,14 +21,9 @@ SECTIONS = [ ( "Start here", [ - ("packages/overview/README.md", "System overview (plain language)"), - ("packages/overview/INDEX.md", "Documentation index"), - ("packages/verae-ops/README.md", "Install & maintenance (Docker, Proxmox, VMs, metal)"), - ("packages/verae-fleet/docs/CONSOLE.md", "Operator console (Fleet · Trace · Docs)"), - ("README.md", "Workspace README"), - ("docs/04-activate/SETUP-ZAPIER-DEVELOPER.pdf", "Zapier developer setup (PDF)"), - ("docs/OPEN.md", "Still open"), - ("TODO.md", "Implementation TODO / gates"), + ("packages/verae-ops/GETTING-STARTED.md", "Bring the system online (install, first-up, monitor)"), + ("packages/overview/README.md", "What the system is (plain language)"), + ("packages/verae-fleet/docs/CONSOLE.md", "Operator console (loopback Fleet · Trace · Docs)"), ], ), ( @@ -52,9 +47,7 @@ SECTIONS = [ ( "Per-module README (public PDFs)", [ - ("packages/overview/README.md", "overview"), - ("packages/verae-ops/README.md", "verae-ops (install)"), - ("packages/zappier/README.md", "zappier-edge"), + ("packages/zappier/README.md", "zappier-edge (billing + users)"), ("packages/verae-zapier-middleware/README.md", "verae-middleware"), ("packages/verae-zapier/README.md", "verae-zapier-app"), ("packages/verae-activate/README.md", "verae-activate"), @@ -70,25 +63,32 @@ SECTIONS = [ ], ), ( - "Install / run", + "Billing, users, portal (zappier-edge)", [ - ("packages/verae-ops/README.md", "Ops index"), - ("packages/verae-ops/01-dependencies.md", "Dependencies and data flow"), + ("packages/zappier/README.md", "zappier-edge README (the billing/user platform)"), + ("packages/zappier/docs/USER-MANUAL.md", "Operations & usage"), + ("packages/zappier/docs/USER-MANAGEMENT.md", "Admin users, pricing, customer types"), + ("packages/zappier/docs/CUSTOMER-PORTAL.md", "Signup, 2FA, API keys, reloads"), + ("packages/zappier/docs/ACCOUNTING.md", "Invoices, PO billing, reports"), + ("packages/zappier/docs/DEVELOPER.md", "Developer reference"), + ], + ), + ( + "Install (detail)", + [ + ("packages/verae-ops/GETTING-STARTED.md", "Bring online (start here)"), ("packages/verae-ops/02-docker.md", "Docker Compose"), - ("packages/verae-ops/03-proxmox.md", "Proxmox LXC / QEMU"), - ("packages/verae-ops/04-virtual-servers.md", "Virtual servers"), + ("packages/verae-ops/03-proxmox.md", "Proxmox"), ("packages/verae-ops/05-dedicated-hardware.md", "Dedicated hardware"), - ("packages/verae-ops/06-linking-services.md", "Linking dependent services"), - ("packages/verae-ops/07-maintenance.md", "Maintenance"), + ("packages/verae-ops/06-linking-services.md", "Linking services"), ], ), ( "Samples", [ ("packages/zappier/zapier-app/README.md", "Sample Zapier app (metered zappier API)"), - ("packages/verae-activate/README.md", "Activate-now Add Numbers sample"), + ("packages/verae-activate/README.md", "Activate-now Add Numbers"), ("packages/verae-zapier-simulator/README.md", "Hop-trace simulator"), - ("packages/verae-nats-process/README.md", "New NATS address template"), ], ), ( @@ -174,10 +174,11 @@ def render_md(src: Path, html_dest: Path, pdf_dest: Path, title: str) -> str: str(html_dest), "--standalone", f"--resource-path={resource}", - "--highlight-style=breezedark", + "--syntax-highlighting=breezedark", f"--metadata=title={title}", f"--include-in-header={header}", f"--include-before-body={banner}", + f"--lua-filter={ROOT / 'scripts' / 'pdf-links.lua'}", ], capture_output=True, text=True, diff --git a/scripts/build-readme-latex.py b/scripts/build-readme-latex.py index fd629c3..65e65dd 100644 --- a/scripts/build-readme-latex.py +++ b/scripts/build-readme-latex.py @@ -48,6 +48,7 @@ def main() -> None: "--metadata=title=Verae Time × Zapier — repository READMEs", f"--include-in-header={hdr}", "--syntax-highlighting=breezedark", + f"--lua-filter={ROOT / 'scripts' / 'pdf-links.lua'}", ], check=True, ) diff --git a/scripts/pdf-links.lua b/scripts/pdf-links.lua new file mode 100644 index 0000000..36ab21b --- /dev/null +++ b/scripts/pdf-links.lua @@ -0,0 +1,19 @@ +-- Rewrite in-document links so catalog PDFs point at other PDFs, not .md/.html. +function Link(el) + local t = el.target or "" + if t:match("^https?://") and not t:match("zapier%.georgelambert%.org") then + return el + end + if t:match("^mailto:") or t:match("^#") then + return el + end + local path, frag = t:match("^(.-)(#.*)$") + if not path then + path, frag = t, "" + end + if path:match("%.md$") or path:match("%.html$") then + path = path:gsub("%.md$", ".pdf"):gsub("%.html$", ".pdf") + el.target = path .. frag + end + return el +end