Clarify Docker-first deploy workflow

.beads/issues.jsonl

@@ -10,6 +10,7 @@
 {"_type":"issue","id":"islandflow-ayo","title":"Drop stale backlog events from live fanout","description":"Follow-up to live freshness rollout: /ws/live was still fanning out stale backlog events for freshness-gated channels, which kept tape panes in Live feed behind despite active synthetic ingest. Gate fanout and cache ingest by freshness for options/nbbo/equities/flow.","status":"closed","priority":1,"issue_type":"bug","assignee":"dirtydishes","owner":"dishes@dpdrm.com","created_at":"2026-04-28T21:26:39Z","created_by":"dirtydishes","updated_at":"2026-04-28T21:26:44Z","started_at":"2026-04-28T21:26:44Z","closed_at":"2026-04-28T21:26:44Z","close_reason":"Completed","dependency_count":0,"dependent_count":0,"comment_count":0}
 {"_type":"issue","id":"islandflow-0v6","title":"Fix tape freshness, NBBO coverage, pause controls, and filter popup","description":"Implement the tape fixes requested for synthetic options notional sizing, strict live freshness, live-mode pause/resume behavior, stronger NBBO snapshot coverage, and moving flow filters behind a popup. Includes server-side live cache changes, web terminal state/UI changes, and tests for synthetic pricing, live snapshot freshness/NBBO retention, and live pause/filter interactions.","status":"closed","priority":1,"issue_type":"task","assignee":"dirtydishes","owner":"dishes@dpdrm.com","created_at":"2026-04-28T21:02:52Z","created_by":"dirtydishes","updated_at":"2026-04-28T21:13:38Z","started_at":"2026-04-28T21:02:57Z","closed_at":"2026-04-28T21:13:38Z","close_reason":"Completed","dependency_count":0,"dependent_count":0,"comment_count":0}
 {"_type":"issue","id":"islandflow-e4r","title":"Implement smart-money flow filtering and synthetic firehose modes","description":"Implement the approved multi-surface plan for named synthetic market profiles, options raw-vs-signal filtering, live/API filter contracts, Tape page client-side flow filters, firehose-readiness improvements, tests, and README updates.","status":"closed","priority":1,"issue_type":"feature","assignee":"dirtydishes","owner":"dishes@dpdrm.com","created_at":"2026-04-28T20:10:49Z","created_by":"dirtydishes","updated_at":"2026-04-28T20:29:29Z","started_at":"2026-04-28T20:10:53Z","closed_at":"2026-04-28T20:29:29Z","close_reason":"Implemented synthetic market profiles, options signal-path filtering, signal-aware API/replay contracts, Tape page filters, tests, and README updates. Follow-up tracked in islandflow-biq.","dependency_count":0,"dependent_count":0,"comment_count":0}
+{"_type":"issue","id":"islandflow-4gj","title":"Clarify Docker-first deploy workflow and mark native runtime experimental","description":"After inspecting the live VPS, native deployment is not ready for routine use: Nginx Proxy Manager routes to Docker container names, Bun is not installed on the host, sudo systemctl is not passwordless, and no Islandflow units exist. Update deploy messaging and docs so Docker remains the clearly recommended deployment path and native runtime is labeled experimental/future-facing with server prerequisites called out.","notes":"Updated deploy messaging and docs after live VPS inspection. scripts/deploy.ts now marks Docker as the default and recommended runtime, labels native as experimental, switches native systemctl default to sudo -n systemctl, and prints explicit native precheck failures for missing Bun/systemctl access/units. Updated README.md, deployment/docker/README.md, and deployment/native/README.md to reflect the current Docker + Nginx Proxy Manager topology. Validation: ./deploy --help, ./deploy main --runtime native --no-build (fails fast with Bun-missing message), bun run check:docker-workspace.","status":"closed","priority":2,"issue_type":"task","assignee":"dirtydishes","owner":"dishes@dpdrm.com","created_at":"2026-05-16T01:10:11Z","created_by":"dirtydishes","updated_at":"2026-05-16T01:12:39Z","started_at":"2026-05-16T01:10:14Z","closed_at":"2026-05-16T01:12:39Z","close_reason":"Closed","dependency_count":0,"dependent_count":0,"comment_count":0}
 {"_type":"issue","id":"islandflow-7p2","title":"Fix deploy wrapper argument forwarding for runtime flags","description":"The repo-root deploy wrapper currently invokes bun run without a -- separator, so flags like --runtime native are treated as Bun CLI flags instead of script arguments. Update the wrapper so ./deploy main --runtime native forwards arguments correctly to scripts/deploy.ts.","notes":"Cherry-picked the dual-runtime deploy workflow onto main and fixed the repo-root deploy wrapper to call Bun with a -- separator so flags like --runtime native are forwarded to scripts/deploy.ts correctly. Validation: ./deploy --help, ./deploy main --runtime native --force-recreate guard, bun run check:docker-workspace.","status":"closed","priority":2,"issue_type":"bug","assignee":"dirtydishes","owner":"dishes@dpdrm.com","created_at":"2026-05-16T00:51:05Z","created_by":"dirtydishes","updated_at":"2026-05-16T00:52:34Z","started_at":"2026-05-16T00:51:10Z","closed_at":"2026-05-16T00:52:34Z","close_reason":"Closed","dependency_count":0,"dependent_count":0,"comment_count":0}
 {"_type":"issue","id":"islandflow-qh7","title":"Implement dual-runtime deploy workflow with partial deploys","description":"Implement the planned refactor of the root deploy script and scripts/deploy.ts so deployment can target Docker and host-native runtimes during a transition period. Preserve local dev as Docker infra plus native Bun services/web, add explicit runtime selection, runtime-specific prechecks/rollout/verification, and support partial deploy scopes such as web-only or services-only. Update operator documentation for the new workflow.","notes":"Implemented dual-runtime deploy workflow. scripts/deploy.ts now supports --runtime docker|native, scope flags (--web-only, --api-only, --services-only), and --no-build. Docker verification now uses docker compose exec instead of hardcoded container names. Added deployment/native/README.md and updated README.md plus deployment/docker/README.md for the new workflow. Validation: bun run scripts/deploy.ts --help, bun run check:docker-workspace, guard checks for invalid flag combinations.","status":"closed","priority":2,"issue_type":"feature","assignee":"dirtydishes","owner":"dishes@dpdrm.com","created_at":"2026-05-15T23:38:31Z","created_by":"dirtydishes","updated_at":"2026-05-15T23:46:17Z","started_at":"2026-05-15T23:40:13Z","closed_at":"2026-05-15T23:46:17Z","close_reason":"Closed","dependency_count":0,"dependent_count":0,"comment_count":0}
 {"_type":"issue","id":"islandflow-iiy","title":"Plan deploy workflow changes for Docker/native transition","description":"User requested a repo-specific plan for updating the root deploy script and deployment workflow to support Docker/native transition paths, faster local iteration, and partial deploy modes. This task covers confirming the target workflow, documenting current assumptions, and producing an implementation-ready plan without changing implementation files.","notes":"Confirmed transition strategy: local dev stays Docker-infra-only plus native Bun services/web; VPS deploy path should support both Docker and host-native runtimes during transition; partial deploys are desired; current main/current-branch modes may evolve. Produced an implementation-ready plan covering current assumptions, runtime split, CLI shape, prechecks, rollout, verification, rollback, docs, and validation scenarios. Follow-up implementation tracked in islandflow-qh7.","status":"closed","priority":2,"issue_type":"task","assignee":"dirtydishes","owner":"dishes@dpdrm.com","created_at":"2026-05-15T23:37:28Z","created_by":"dirtydishes","updated_at":"2026-05-15T23:38:41Z","started_at":"2026-05-15T23:37:30Z","closed_at":"2026-05-15T23:38:41Z","close_reason":"Closed","dependency_count":0,"dependent_count":0,"comment_count":0}

README.md

@@ -126,12 +126,12 @@ This keeps Docker in the local workflow where it helps most (NATS, ClickHouse, R
 
 ## Deployment Workflow
 
-- `./deploy main` keeps the current VPS Docker rollout path as the default.
+- `./deploy main` keeps the current VPS Docker rollout path as the default and recommended path.
-- `./deploy main --runtime native` targets a host-native Bun + systemd deployment.
+- `./deploy main --runtime native` targets an experimental host-native Bun + systemd deployment.
-- `./deploy current-branch` and `./deploy current-branch --runtime native` keep branch deploys available during the transition.
+- `./deploy current-branch` and `./deploy current-branch --runtime native` keep branch deploys available during the transition, but Docker remains the supported path for the current VPS.
 - Partial deploys are supported with `--web-only`, `--api-only`, `--services-only`, and `--no-build`.
 - Docker runtime details live in `deployment/docker/README.md`.
-- Native runtime expectations live in `deployment/native/README.md`.
+- Native runtime expectations and prerequisites live in `deployment/native/README.md`.
 
 ## Desktop Shell
 

deployment/docker/README.md

@@ -2,10 +2,10 @@
 
 This directory contains the Docker runtime for Islandflow VPS deployments.
 
-Docker remains the default server rollout path, but the repo-root `deploy` helper can now target either:
+Docker remains the default and recommended server rollout path, but the repo-root `deploy` helper can now target either:
 
 - `--runtime docker` for this Docker Compose stack
-- `--runtime native` for a host-native Bun + systemd rollout described in `deployment/native/README.md`
+- `--runtime native` for an experimental host-native Bun + systemd rollout described in `deployment/native/README.md`
 
 The repo no longer ships or supports a separate `deployment/npm` stack. If you want a reverse proxy, point it at the host ports published by this stack.
 
@@ -190,6 +190,8 @@ docker compose build web
 
 ## Safe rollouts on `152.53.80.229`
 
+The current live VPS uses Nginx Proxy Manager on the shared Docker network and routes public traffic to the Docker `web` and `api` containers by container name. Because of that, this Docker path remains the operationally correct default for the live server today.
+
 The checked-in deploy helper is meant to run from your local repo checkout, not from the VPS shell. It always targets:
 
 - SSH host: `delta@152.53.80.229`

deployment/native/README.md

@@ -1,13 +1,13 @@
 # Native Deployment
 
-This directory documents the host-native Islandflow rollout path used by:
+This directory documents the experimental host-native Islandflow rollout path used by:
 
 ```bash
 ./deploy main --runtime native
 ./deploy current-branch --runtime native
 ```
 
-This runtime is intended for faster server iteration during the transition away from Docker-only app rollouts. Local development should still prefer:
+This runtime is intended for faster server iteration during the transition away from Docker-only app rollouts. It is not the recommended path for the current production VPS, which still uses Nginx Proxy Manager to reach the Docker `web` and `api` containers by container name on the shared Docker network. Local development should still prefer:
 
 - Docker for infra (`bun run dev:infra`)
 - native Bun services (`bun run dev:services`)
@@ -57,7 +57,7 @@ Available overrides:
 By default the deploy helper uses:
 
 ```bash
-sudo systemctl
+sudo -n systemctl
 ```
 
 If the server uses user units or another wrapper, override it locally before invoking `./deploy`:
@@ -86,6 +86,23 @@ Scope behavior:
 - `--services-only`: restart API + backend units without touching the web unit
 - `--no-build`: skip `bun install --frozen-lockfile` and skip the web build step
 
+## Current status
+
+On the current live VPS, native deploys should be treated as opt-in infrastructure work, not the default rollout path. Before a native deploy can succeed there, all of the following must be true at the same time:
+
+- Bun is installed on the host.
+- The selected `systemctl` command works non-interactively.
+- Islandflow systemd units exist for the requested scope.
+- Host-native services can reach the intended NATS, ClickHouse, and Redis endpoints.
+- If `web` or `api` move native, the reverse proxy topology is updated deliberately.
+
+Until that is prepared intentionally, prefer:
+
+```bash
+./deploy main --runtime docker
+./deploy current-branch --runtime docker
+```
+
 ## Server preparation checklist
 
 Before the first native rollout, ensure the VPS has:
@@ -115,7 +132,7 @@ Rollback remains manual for now:
 2. rerun the appropriate native deploy command
 3. if needed, restart only the affected units with `systemctl`
 
-Docker remains available as the fallback runtime during the transition:
+Docker remains the fallback and currently recommended runtime during the transition:
 
 ```bash
 ./deploy main --runtime docker

docs/turns/2026-05-15-clarify-docker-first-deploy-workflow.html

@@ -0,0 +1,146 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>2026-05-15: Clarify Docker-first deploy workflow</title>
+    <style>
+      :root {
+        color-scheme: dark;
+        --bg: #0f1319;
+        --panel: #171d26;
+        --panel-2: #1d2531;
+        --text: #e7edf6;
+        --muted: #9db0c9;
+        --accent: #8cc6ff;
+        --border: #2a3646;
+        --good: #7bd8a6;
+        --warn: #f2c078;
+      }
+      * { box-sizing: border-box; }
+      body {
+        margin: 0;
+        font: 16px/1.6 Inter, ui-sans-serif, system-ui, sans-serif;
+        background: linear-gradient(180deg, #0b1015, var(--bg));
+        color: var(--text);
+      }
+      main { max-width: 920px; margin: 0 auto; padding: 40px 20px 72px; }
+      h1, h2 { line-height: 1.15; }
+      h1 { margin: 0 0 10px; font-size: 2rem; }
+      h2 { margin: 0 0 12px; font-size: 1.18rem; }
+      p.lede { color: var(--muted); max-width: 72ch; }
+      section {
+        margin-top: 22px;
+        padding: 22px 24px;
+        border: 1px solid var(--border);
+        border-radius: 18px;
+        background: linear-gradient(180deg, var(--panel), var(--panel-2));
+      }
+      code, pre {
+        font: 13px/1.5 ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+      }
+      code {
+        padding: 0.14rem 0.35rem;
+        border-radius: 8px;
+        background: rgba(140, 198, 255, 0.12);
+        color: var(--accent);
+      }
+      pre {
+        margin: 14px 0 0;
+        padding: 14px 16px;
+        overflow: auto;
+        border-radius: 14px;
+        border: 1px solid var(--border);
+        background: #0c1118;
+      }
+      ul { margin: 0; padding-left: 1.2rem; }
+      .meta { display: flex; gap: 10px; flex-wrap: wrap; margin-bottom: 20px; }
+      .chip {
+        padding: 0.3rem 0.65rem;
+        border-radius: 999px;
+        border: 1px solid var(--border);
+        color: var(--muted);
+        background: rgba(255,255,255,0.03);
+      }
+      .good { color: var(--good); }
+      .warn { color: var(--warn); }
+    </style>
+  </head>
+  <body>
+    <main>
+      <div class="meta">
+        <span class="chip">Turn document</span>
+        <span class="chip">2026-05-15</span>
+        <span class="chip">Issue: islandflow-4gj</span>
+      </div>
+      <h1>Clarify Docker-first deploy workflow</h1>
+      <p class="lede">
+        Updated deploy messaging and deployment docs so Docker is clearly the supported VPS path today, while the native runtime is labeled experimental and fails faster with clearer prerequisites.
+      </p>
+
+      <section>
+        <h2>Summary</h2>
+        <p>
+          The deploy helper now warns when <code>--runtime native</code> is used, defaults native systemctl invocations to <code>sudo -n systemctl</code> so they fail fast instead of hanging for a password, and prints explicit precheck errors when Bun or systemd readiness is missing. Docs now describe Docker as the default and recommended VPS rollout path.
+        </p>
+      </section>
+
+      <section>
+        <h2>Changes Made</h2>
+        <ul>
+          <li>Updated <code>scripts/deploy.ts</code> help text to mark Docker as default and recommended, and native as experimental.</li>
+          <li>Changed the native systemctl default from <code>sudo systemctl</code> to <code>sudo -n systemctl</code> to avoid interactive hangs.</li>
+          <li>Added a runtime advisory banner for native deploy attempts.</li>
+          <li>Improved native remote precheck failures for missing Bun, missing systemctl access, and missing systemd units.</li>
+          <li>Updated <code>README.md</code>, <code>deployment/docker/README.md</code>, and <code>deployment/native/README.md</code> to reflect the live VPS reality: Docker plus Nginx Proxy Manager remains the supported deployment path.</li>
+        </ul>
+      </section>
+
+      <section>
+        <h2>Context</h2>
+        <p>
+          Live inspection of the VPS showed that Nginx Proxy Manager routes <code>flow.deltaisland.io</code> and API traffic to the Docker <code>web</code> and <code>api</code> containers by container name on the shared Docker network. The host does not currently have Bun installed, passwordless <code>sudo systemctl</code> is not configured, and no Islandflow systemd units are present. Because of that, native deployment should be treated as future infrastructure work rather than the recommended day-to-day path.
+        </p>
+      </section>
+
+      <section>
+        <h2>Important Implementation Details</h2>
+        <ul>
+          <li>Native rollout prechecks now fail with actionable messages instead of a silent command failure or a hanging sudo prompt.</li>
+          <li>The native docs now explicitly say the current VPS is not prepared for routine native rollouts.</li>
+          <li>Docker deployment behavior itself was not changed. This was a clarity and guardrail pass, not a runtime migration.</li>
+        </ul>
+        <pre>[deploy] Native runtime is experimental. Use --runtime docker for the current supported VPS path unless Bun, systemd units, and proxy routing have been prepared intentionally.</pre>
+      </section>
+
+      <section>
+        <h2>Validation</h2>
+        <ul>
+          <li class="good">Passed: <code>./deploy --help</code></li>
+          <li class="good">Passed: <code>bun run check:docker-workspace</code></li>
+          <li class="good">Passed: <code>./deploy main --runtime native --no-build</code> now fails quickly with an explicit Bun-missing message on the live VPS</li>
+        </ul>
+        <pre>./deploy --help
+./deploy main --runtime native --no-build
+bun run check:docker-workspace</pre>
+      </section>
+
+      <section>
+        <h2>Issues, Limitations, and Mitigations</h2>
+        <ul>
+          <li><span class="warn">Native deploy remains experimental.</span> Mitigation: docs and CLI output now say so directly.</li>
+          <li><span class="warn">The live VPS still depends on Docker-name routing through Nginx Proxy Manager.</span> Mitigation: Docker remains the recommended deployment path.</li>
+          <li><span class="warn">No systemd units or Bun install were added in this change.</span> That work remains a separate follow-up.</li>
+        </ul>
+      </section>
+
+      <section>
+        <h2>Follow-up Work</h2>
+        <ul>
+          <li>Keep native deployment support available for future experimentation, but treat it as opt-in infrastructure work.</li>
+          <li>Open follow-up: <code>islandflow-38p</code>, add native deployment unit templates and rollback helpers if the host-native path is revived later.</li>
+        </ul>
+      </section>
+    </main>
+  </body>
+</html>

scripts/deploy.ts

@@ -38,7 +38,7 @@ const PUBLIC_APP_URL =
 const PUBLIC_API_HEALTH_URL =
   process.env.DEPLOY_PUBLIC_API_HEALTH_URL?.trim() || null;
 const NATIVE_SYSTEMCTL_PREFIX =
-  process.env.DEPLOY_NATIVE_SYSTEMCTL_PREFIX?.trim() || "sudo systemctl";
+  process.env.DEPLOY_NATIVE_SYSTEMCTL_PREFIX?.trim() || "sudo -n systemctl";
 const NATIVE_UNITS = {
   web: process.env.DEPLOY_NATIVE_WEB_UNIT?.trim() || "islandflow-web",
   api: process.env.DEPLOY_NATIVE_API_UNIT?.trim() || "islandflow-api",
@@ -79,8 +79,8 @@ Modes:
   current-branch  Push the current local branch, switch the server to it, and deploy it.
 
 Runtimes:
-  docker          Roll out from deployment/docker with Docker Compose (default).
+  docker          Roll out from deployment/docker with Docker Compose (default, recommended).
-  native          Roll out host-native Bun services managed by systemd.
+  native          Experimental host-native Bun services managed by systemd.
 
 Scopes:
   default         Full rollout (web + API + backend services).
@@ -97,7 +97,7 @@ Options:
 Environment:
   DEPLOY_PUBLIC_APP_URL             Override the public app URL (default: https://flow.deltaisland.io).
   DEPLOY_PUBLIC_API_HEALTH_URL      Optional separate public API health URL for two-origin deployments.
-  DEPLOY_NATIVE_SYSTEMCTL_PREFIX    Override systemctl invocation for native rollouts (default: sudo systemctl).
+  DEPLOY_NATIVE_SYSTEMCTL_PREFIX    Override systemctl invocation for native rollouts (default: sudo -n systemctl).
   DEPLOY_NATIVE_WEB_UNIT            Override native web systemd unit name.
   DEPLOY_NATIVE_API_UNIT            Override native api systemd unit name.
   DEPLOY_NATIVE_COMPUTE_UNIT        Override native compute systemd unit name.
@@ -277,7 +277,17 @@ function shellPattern(value: string): string {
 }
 
 function describeRuntime(runtime: DeployRuntime): string {
-  return runtime === "docker" ? "Docker Compose" : "native systemd/Bun";
+  return runtime === "docker" ? "Docker Compose" : "experimental native systemd/Bun";
+}
+
+function printRuntimeAdvisory(runtime: DeployRuntime): void {
+  if (runtime !== "native") {
+    return;
+  }
+
+  console.warn(
+    "[deploy] Native runtime is experimental. Use --runtime docker for the current supported VPS path unless Bun, systemd units, and proxy routing have been prepared intentionally."
+  );
 }
 
 function describeScope(scope: DeployScope): string {
@@ -497,8 +507,26 @@ docker compose version >/dev/null
 set -euo pipefail
 
 cd ${shellEscape(REMOTE_REPO)}
-command -v bun >/dev/null 2>&1
+
-command -v systemctl >/dev/null 2>&1
+if ! command -v bun >/dev/null 2>&1; then
+  echo "Refusing native rollout: bun is not installed on the server." >&2
+  echo "The current supported VPS path remains --runtime docker." >&2
+  echo "See deployment/native/README.md for native prerequisites." >&2
+  exit 1
+fi
+
+if ! command -v systemctl >/dev/null 2>&1; then
+  echo "Refusing native rollout: systemctl is not available on the server." >&2
+  echo "See deployment/native/README.md for native prerequisites." >&2
+  exit 1
+fi
+
+if ! ${NATIVE_SYSTEMCTL_PREFIX} --version >/dev/null 2>&1; then
+  echo "Refusing native rollout: cannot run ${NATIVE_SYSTEMCTL_PREFIX}." >&2
+  echo "If the server uses user units, try DEPLOY_NATIVE_SYSTEMCTL_PREFIX='systemctl --user'." >&2
+  echo "If the server uses system units, ensure passwordless sudo for this command or use --runtime docker." >&2
+  exit 1
+fi
 
 declare -a units=(${units})
 for unit in "\${units[@]}"; do
@@ -506,6 +534,7 @@ for unit in "\${units[@]}"; do
   if [[ -z "$load_state" || "$load_state" == "not-found" ]]; then
     echo "Refusing native rollout: missing systemd unit $unit" >&2
     echo "See deployment/native/README.md for expected unit names and overrides." >&2
+    echo "Use --runtime docker for the current supported VPS path." >&2
     exit 1
   fi
 done
@@ -696,6 +725,7 @@ function publicVerification(scope: DeployScope): void {
 function main(): void {
   const options = parseArgs(process.argv.slice(2));
   assertSshKeyExists();
+  printRuntimeAdvisory(options.runtime);
 
   console.log(
     `Deploying ${options.mode === "main" ? "origin/main" : "the current local branch"} ` +