deploy: retarget for melvin.me's real topology (haproxy, separate 0.0.219 instance)

Recon showed melvin.me is already a live JSS 0.0.204 pod (pm2, port
5420, shared /home/ubuntu/jss with losos.org) behind haproxy. So the
plugins land as an ISOLATED new pm2 app on port 5480 with their own
pinned 0.0.219 — no touch to the shared install or the live sites —
fronted at forge.melvin.me via one haproxy backend. Swapped the nginx
assumption for haproxy-forge.cfg (nginx kept as alt); ecosystem env and
README updated (subdomain, own data root, git 2.43 confirmed OK).

Author: melvincarvalho

deploy/README.md

@@ -1,10 +1,36 @@
-# Deploying JSS + plugins to a public host (pm2 + nginx)
+# Deploying JSS + plugins to a public host (pm2 + haproxy)
 
 The runbook for putting this repo on a box like `melvin.me`. The code needs
 **no build step** — deploying is `git pull` + `pm2 restart`. The care is all
 in three things: which plugins you expose, keeping the public Host consistent,
 and persisting the data root.
 
+## Where this lands on melvin.me (as-recon'd 2026-07-12)
+
+The box already runs, under pm2, a **separate JSS pod per site** — `melvin.me`
+(`jss start --port 5420 --root /home/ubuntu/www/melvin.me --single-user …
+--idp-issuer https://melvin.me/ --git --activitypub --nostr --webrtc --tunnel
+--pay`) and `losos.org`, both off the shared `/home/ubuntu/jss` install, which
+is **JSS 0.0.204**. haproxy on :80/:443 routes by hostname to each backend.
+
+Two consequences:
+
+1. **The plugins need JSS ≥ 0.0.219** (serverInfo/reservePath/mountApp/
+   api.plugins live there; the forge won't run on 0.0.204). Do **not** upgrade
+   the shared install to get them — that would move melvin.me *and* losos.org
+   15 patch versions at once. Instead this repo's `npm ci` brings its **own**
+   pinned 0.0.219 in its own `node_modules`, and runs as a **new, isolated pm2
+   app** (`forge`, port 5480) with zero effect on the live 0.0.204 pods.
+2. **Mount it as a subdomain** — `forge.melvin.me` → haproxy backend
+   `127.0.0.1:5480`. A path split (`melvin.me/forge`) collides with the
+   existing pod's own `/api`, `/oauth`, `/.well-known/*`. See
+   `haproxy-forge.cfg`.
+
+The box is otherwise ready: Ubuntu 24.04, node 22, **git 2.43** (≥2.38 so forge
+merges work), `git-http-backend` present, pm2 6.
+
+## Prerequisites (check on the box first)
+
 ## Prerequisites (check on the box first)
 
 ```bash
@@ -23,13 +49,13 @@ pm2 -v                                    # process manager
 ## 1. Get the code
 
 ```bash
-sudo mkdir -p /var/lib/jss && sudo chown ubuntu:ubuntu /var/lib/jss   # PERSISTENT data root
+mkdir -p /home/ubuntu/forge-data          # PERSISTENT data root (own to ubuntu)
 cd /home/ubuntu
 git clone https://github.com/JavaScriptSolidServer/plugins.git
-cd plugins && git checkout gh-pages && npm ci
+cd plugins && git checkout gh-pages && npm ci   # brings its OWN jss 0.0.219
 ```
 
-The data root (`/var/lib/jss`) holds pods, forge repos, issue indexes, and the
+The data root (`/home/ubuntu/forge-data`) holds pods, forge repos, issue indexes, and the
 **Blocktrails trail private keys**. Keep it OUTSIDE the checkout (so `git pull`
 never touches it) and back it up. Losing the trail keys orphans your anchors.
 
@@ -38,30 +64,36 @@ never touches it) and back it up. Losing the trail keys orphans your anchors.
 JSS mints WebIDs against `idpIssuer` (`https://melvin.me`) and checks pod
 ownership against the **request Host**. Behind a TLS proxy this means two rules:
 
-1. **nginx passes `Host` through unchanged** — `proxy_set_header Host $host;`
-   (in the supplied conf). A rewritten Host = 403 on users' own writes.
+1. **haproxy passes `Host` through unchanged** — in `mode http` it does by
+   default; just don't add `http-request set-header Host …`. A rewritten Host
+   = 403 on users' own writes.
 2. **The server's own loopback presents the public Host.** `serve.prod.js`
    sets every plugin's `loopbackUrl` to `PUBLIC_URL`, so add a hosts entry so
    that self-call resolves locally instead of hair-pinning out to the internet:
 
    ```bash
-   echo "127.0.0.1 melvin.me" | sudo tee -a /etc/hosts
+   echo "127.0.0.1 forge.melvin.me" | sudo tee -a /etc/hosts
    ```
 
-   Now a plugin's loopback to `https://melvin.me/...` hits local nginx →
-   JSS, presenting `Host: melvin.me`, and pod-owning writes pass WAC.
+   Now a plugin's loopback to `https://forge.melvin.me/...` hits local haproxy
+   → the forge instance, presenting `Host: forge.melvin.me`, and pod-owning
+   writes pass WAC.
+
+## 3. haproxy
 
-## 3. nginx
+Add the backend + ACL from `deploy/haproxy-forge.cfg` to your existing
+`/etc/haproxy/haproxy.cfg` (subdomain `forge.melvin.me` → `127.0.0.1:5480`),
+then:
 
 ```bash
-sudo cp deploy/nginx-melvin.me.conf /etc/nginx/sites-available/melvin.me
-sudo ln -sf /etc/nginx/sites-available/melvin.me /etc/nginx/sites-enabled/
-# ensure this line exists in http{} (nginx.conf) for WebSocket upgrades:
-#   map $http_upgrade $connection_upgrade { default upgrade; '' close; }
-sudo nginx -t && sudo systemctl reload nginx
+sudo haproxy -c -f /etc/haproxy/haproxy.cfg   # validate
+sudo systemctl reload haproxy
 ```
 
-TLS cert via certbot if you don't have one: `sudo certbot --nginx -d melvin.me`.
+Needs a cert covering `forge.melvin.me` (a `*.melvin.me` wildcard, or add one
+to the crt-list) and a DNS record `forge.melvin.me → this box`.
+(`nginx-melvin.me.conf` is kept in this dir as an alternative if you ever move
+off haproxy.)
 
 ## 4. pm2
 
@@ -76,14 +108,14 @@ pm2 logs jss  # watch it come up
 ## 5. Verify
 
 ```bash
-curl -s https://melvin.me/dashboard/ -o /dev/null -w '%{http_code}\n'   # 200
-curl -s https://melvin.me/forge/ -o /dev/null -w '%{http_code}\n'       # 200
+curl -s https://forge.melvin.me/dashboard/ -o /dev/null -w '%{http_code}\n'   # 200
+curl -s https://forge.melvin.me/forge/ -o /dev/null -w '%{http_code}\n'       # 200
 # register a pod, then confirm a pod-owning write round-trips (the Host check):
-#   open https://melvin.me/forge/ , sign in, open an issue — 200, not 403.
+#   open https://forge.melvin.me/forge/ , sign in, open an issue — 200, not 403.
 ```
 
-Point Phanpy (or any Mastodon client) at `https://melvin.me` to exercise the
-fediverse surface.
+Point Phanpy (or any Mastodon client) at `https://forge.melvin.me` to exercise
+the fediverse surface. (Your existing `melvin.me` pod is untouched.)
 
 ## Updating
 

deploy/ecosystem.config.cjs

@@ -16,7 +16,11 @@
 module.exports = {
   apps: [
     {
-      name: 'jss',
+      // A SEPARATE instance from the existing melvin.me/losos.org pods. It
+      // brings its own pinned JSS 0.0.219 (this repo's node_modules), so it
+      // does NOT touch the shared /home/ubuntu/jss install (v0.0.204) that
+      // serves the live sites. New name, new port, new data root.
+      name: 'forge',
       script: 'deploy/serve.prod.js',
       cwd: '/home/ubuntu/plugins', // the checkout of JavaScriptSolidServer/plugins
       interpreter: 'node',
@@ -27,9 +31,11 @@ module.exports = {
       kill_timeout: 5000, // give fastify.close() room on SIGINT
       env: {
         NODE_ENV: 'production',
-        PUBLIC_URL: 'https://melvin.me',
-        DATA: '/var/lib/jss', // PERSISTENT — pods, forge repos, Blocktrails keys
-        PORT: '3240',
+        // Subdomain origin (recommended) — its own IdP/pods, no collision with
+        // the melvin.me pod's own /api, /.well-known, etc.
+        PUBLIC_URL: 'https://forge.melvin.me',
+        DATA: '/home/ubuntu/forge-data', // PERSISTENT — pods, forge repos, Blocktrails keys
+        PORT: '5480', // haproxy forge_be → 127.0.0.1:5480 (5420 is the melvin.me pod)
         BIND: '127.0.0.1',
         // METRICS_TOKEN: 'set-a-long-random-string-to-expose-/metrics',
         // ADMIN_AGENTS: 'https://melvin.me/melvin/profile/card#me',

deploy/haproxy-forge.cfg

@@ -0,0 +1,34 @@
+# haproxy snippet to front the JSS + plugins instance on melvin.me's box.
+# The box already runs haproxy on :80/:443 routing by hostname to per-site
+# backends (melvin.me → :5420, losos.org → …). This adds ONE more backend for
+# the plugins instance WITHOUT touching the existing sites.
+#
+# RECOMMENDED: a subdomain (forge.melvin.me) — its own origin, no path rew[]
+# collisions with the melvin.me pod's own /api, /.well-known, etc.
+#
+# Merge these into the existing haproxy.cfg (usually /etc/haproxy/haproxy.cfg),
+# then: sudo haproxy -c -f /etc/haproxy/haproxy.cfg && sudo systemctl reload haproxy
+
+# --- in your existing `frontend https-in` (the ssl-terminating frontend) ------
+#   Requires a cert covering forge.melvin.me (wildcard *.melvin.me, or add one
+#   to the crt-list). haproxy preserves the Host header in mode http by default
+#   — do NOT add `http-request set-header Host …`, or you reintroduce the
+#   pod-ownership 403.
+    acl host_forge hdr(host) -i forge.melvin.me
+    use_backend forge_be if host_forge
+
+# --- new backend --------------------------------------------------------------
+backend forge_be
+    mode http
+    option forwardfor
+    http-request set-header X-Forwarded-Proto https
+    # git packs + media uploads: let big/streamed bodies through.
+    timeout server 300s
+    server forge1 127.0.0.1:5480 check
+
+# ---- PATH alternative (melvin.me/forge) — NOT recommended --------------------
+# The forge shares fixed roots with the existing melvin.me pod (/api, /oauth,
+# /.well-known/*), so a path split would collide and mis-route. If you must do
+# path-based, route ONLY /forge, /dashboard, /gallery to forge_be and accept
+# that fediverse/identity endpoints stay on the existing pod. A subdomain
+# avoids all of this.