146 lines
6.5 KiB
HTML
146 lines
6.5 KiB
HTML
<!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>
|