docs: align CloudNode docs with foreground-TUI + system-FFmpeg reality

Sbussiso · claude · Sbussiso · commit c2f9a85bc46c · 2026-04-28T15:34:33.000-07:00
Reality drift since v0.1.31 / v0.1.35: the Windows Service is no longer
the recommended runtime (the Start menu shortcut launches a foreground
TUI dashboard), and FFmpeg is not bundled (the wizard offers winget /
brew / apt install). The docs site still described the old world,
which made the install saga we just lived through harder than it
needed to be.

Fixes:
  - CloudNodeSetup.jsx — primary path = Start menu shortcut /
    foreground TUI; service section reframed as optional 24/7 path.
    FFmpeg description now points to system package managers, not a
    150 MB auto-download. Data-dir resolution clarified for Windows.
  - Troubleshooting.jsx — FFmpeg recovery references winget / brew /
    apt instead of the deleted ./ffmpeg/bin/ auto-download path.
  - Faq.jsx — replaces "MSI vs PowerShell installer" question (the
    PowerShell installer was retired in v0.1.31) with "How do I
    install on Windows?" pointing at the actual current flow.
  - Deployment.jsx — systemd unit now matches what install.sh
    actually writes (~/.sourcebox-sentry/, sourcebox-sentry-cloudnode
    run, SupplementaryGroups=video, NO_COLOR/TERM env). Adds note
    that the install script offers to write the unit automatically.
  - GettingStarted.jsx — drops "installer downloads FFmpeg
    automatically on Windows" line.
  - context.jsx — fixes the OsTabs MSI blurb claiming the service
    auto-starts; updates the comment about why PowerShell installer
    was retired.

Frontend build is clean (vite dist generated, 492ms).

Co-Authored-By: Claude Opus 4.7 (1M context) &lt;noreply@anthropic.com&gt;
diff --git a/frontend/src/pages/docs/CloudNodeSetup.jsx b/frontend/src/pages/docs/CloudNodeSetup.jsx
@@ -17,13 +17,15 @@ function CloudNodeSetup() {
       <OsTabs id="cn" />
       <p style={{ marginTop: '0.75rem', fontSize: '0.9rem', color: 'var(--text-muted)' }}>
         {os === 'windows'
-          ? 'After the MSI finishes, open PowerShell as Administrator to run setup.'
-          : 'Run in your terminal.'}
+          ? 'After the MSI finishes, click the SourceBox Sentry CloudNode shortcut from the Start menu — first launch runs the setup wizard, every launch after streams cameras directly.'
+          : 'Run in your terminal. The script downloads the binary, runs setup, and (on Linux + systemd) optionally installs a service unit so the node restarts on boot.'}
       </p>
 
       <h3>Setup Wizard</h3>
       <p>
-        After installation, run the wizard to enrol the node and detect cameras:
+        On Windows the Start menu shortcut launches the wizard automatically the first time.
+        On Linux/macOS the install script invokes it inline. To re-run the wizard later
+        (e.g. to re-enrol or change the API URL):
       </p>
       <div className="docs-code-block">
         <code>{os === 'windows' ? 'sourcebox-sentry-cloudnode.exe setup' : 'sourcebox-sentry-cloudnode setup'}</code>
@@ -33,29 +35,33 @@ function CloudNodeSetup() {
       <ol>
         <li>
           <strong>Prerequisites</strong> — detects platform, finds your USB cameras, verifies FFmpeg.
-          On Windows, if FFmpeg isn't installed the wizard offers to{' '}
-          <strong>download it for you</strong> (~150 MB, lands under{' '}
-          <code>C:\ProgramData\SourceBoxSentry\ffmpeg\</code>). Linux/macOS users get pointed
-          at <code>apt install ffmpeg</code> / <code>brew install ffmpeg</code>.
+          If FFmpeg isn't on PATH the wizard offers to install it via the OS package manager:{' '}
+          <code>winget install Gyan.FFmpeg</code> on Windows, <code>brew install ffmpeg</code> on
+          macOS, the matching <code>apt</code> / <code>dnf</code> / <code>pacman</code> command
+          on Linux. CloudNode always uses the system FFmpeg — there is no bundled copy.
         </li>
         <li><strong>Configuration</strong> — prompts for your Node ID + API key (from Command Center → Settings → Add Node).</li>
         <li><strong>Install</strong> — saves the encrypted config and detects the best video encoder (NVENC / QSV / AMF, or libx264 fallback).</li>
         <li><strong>Verify</strong> — round-trips a credential check against Command Center.</li>
         <li><strong>Launch</strong> — optionally auto-starts the node.</li>
       </ol>
-      <p style={{ fontSize: '0.9rem', color: 'var(--text-muted)' }}>
-        On a fresh Windows machine with no FFmpeg, the whole flow takes about
-        2 minutes including the FFmpeg download (depends on your connection).
-      </p>
 
       {os === 'windows' && (
         <>
-          <h3>Running as a Windows Service (MSI install)</h3>
+          <h3>Running on Windows</h3>
+          <p>
+            The Start menu shortcut launches CloudNode as a foreground app — a terminal window
+            opens with the live dashboard, FFmpeg starts pushing segments, and the node stays
+            online for as long as the window is open. This is the recommended path for everyday
+            use: you can see what's happening, hit a slash command, and close it cleanly.
+          </p>
+
+          <h4>Auto-start on boot (optional)</h4>
           <p>
-            If you installed via the MSI, CloudNode is registered as the{' '}
-            <code>SourceBoxSentryCloudNode</code> service but is set to manual start so the first
-            run can't fail before you've completed setup. After running setup, start it once
-            and then flip it to auto-start so it survives reboots:
+            For 24/7 unattended operation, the MSI also registers a Windows Service named{' '}
+            <code>SourceBoxSentryCloudNode</code> set to <strong>manual start</strong>. Flip it
+            to automatic if you want CloudNode to come up after a reboot without anyone logging
+            in:
           </p>
           <div className="docs-code-block">
             <code>{`Start-Service SourceBoxSentryCloudNode
@@ -68,26 +74,26 @@ Set-Service -Name SourceBoxSentryCloudNode -StartupType Automatic`}</code>
             <li><code>Stop-Service SourceBoxSentryCloudNode</code> / <code>Restart-Service SourceBoxSentryCloudNode</code></li>
             <li><code>Get-Content -Wait C:\ProgramData\SourceBoxSentry\logs\cloudnode-service.<i>YYYY-MM-DD</i></code> — tail today's service log</li>
           </ul>
+          <p style={{ fontSize: '0.9rem', color: 'var(--text-muted)' }}>
+            Don't run the foreground TUI and the service at the same time — only one process
+            should hold the cameras.
+          </p>
 
           <h3>Uninstalling</h3>
           <p>
             Use <strong>Settings → Apps → Installed apps → SourceBox Sentry CloudNode → Uninstall</strong>.
-            That stops the service, removes the binary, removes the Windows Service
-            registration, and removes everything under{' '}
-            <code>C:\ProgramData\SourceBoxSentry\</code> — including your encrypted config,
-            recordings, and the auto-installed FFmpeg. After uninstall the machine is
-            in a true "never installed" state.
+            That stops the service (if running), removes the binary, removes the Windows Service
+            registration, and wipes <code>C:\ProgramData\SourceBoxSentry\</code> — including your
+            encrypted config and recordings. FFmpeg installed via <code>winget</code> stays put
+            because it's a separate package owned by the OS package manager.
           </p>
           <p style={{ fontSize: '0.9rem', color: 'var(--text-muted)' }}>
-            Upgrades (re-running a newer MSI) preserve everything under ProgramData;
-            only an explicit uninstall wipes it. The CLI{' '}
-            <code>sourcebox-sentry-cloudnode uninstall</code> subcommand is for source-built
-            installs and redirects MSI users to Settings → Apps if you accidentally
-            run it on an MSI machine.
+            Upgrades (re-running a newer MSI) preserve everything under ProgramData; only an
+            explicit uninstall wipes it.
           </p>
 
           <p>
-            See the CloudNode <a href="https://github.com/SourceBox-LLC/opensentry-cloud-node#running-as-a-windows-service" target="_blank" rel="noopener noreferrer">README</a> for the full reference.
+            See the CloudNode <a href="https://github.com/SourceBox-LLC/opensentry-cloud-node#quick-start" target="_blank" rel="noopener noreferrer">README</a> for the full reference.
           </p>
         </>
       )}
@@ -98,8 +104,8 @@ Set-Service -Name SourceBoxSentryCloudNode -StartupType Automatic`}</code>
       </p>
       <ul>
         <li><code>$SOURCEBOX_SENTRY_DATA_DIR/node.db</code> if the env var is set (Docker)</li>
-        <li><code>./data/node.db</code> if it already exists (legacy / <code>cargo build</code> installs)</li>
-        <li><code>C:\ProgramData\SourceBoxSentry\node.db</code> on Windows MSI installs</li>
+        <li><code>./data/node.db</code> if it already exists — Linux/macOS only, for legacy <code>cargo build</code> installs (Windows always uses the platform default below)</li>
+        <li><code>C:\ProgramData\SourceBoxSentry\node.db</code> on Windows</li>
         <li><code>./data/node.db</code> otherwise (fresh manual install on Linux/macOS)</li>
       </ul>
       <p>The API key is encrypted at rest. Key settings:</p>
diff --git a/frontend/src/pages/docs/Deployment.jsx b/frontend/src/pages/docs/Deployment.jsx
@@ -83,37 +83,70 @@ cargo build --release
       </div>
 
       <h3>systemd service (Linux)</h3>
-      <p>To run CloudNode as a background service on boot, create <code>/etc/systemd/system/sourcebox-sentry-cloudnode.service</code>:</p>
+      <p>
+        The easiest path is the install script — after the wizard finishes, it offers to write
+        the systemd unit and enable it for you. If you'd rather wire it up manually, the unit
+        below mirrors what the script would have written. It assumes the binary lives at{' '}
+        <code>~/.sourcebox-sentry/sourcebox-sentry-cloudnode</code> (the install script's
+        default <code>INSTALL_DIR</code>) and the wizard wrote <code>node.db</code> under{' '}
+        <code>$HOME</code>; substitute your own paths if you installed elsewhere.
+      </p>
+      <p>Drop into <code>/etc/systemd/system/sourcebox-sentry-cloudnode.service</code>:</p>
       <div className="docs-code-block">
         <code>{`[Unit]
 Description=SourceBox Sentry CloudNode
+Documentation=https://opensentry-command.fly.dev
 After=network-online.target
 Wants=network-online.target
 
 [Service]
 Type=simple
-User=sentry
-WorkingDirectory=/opt/sourcebox-sentry
-ExecStart=/opt/sourcebox-sentry/sourcebox-sentry-cloudnode
-Restart=on-failure
-RestartSec=5
+User=YOUR_USER
+# 'video' is the standard group that owns /dev/video* on Debian / Ubuntu /
+# Raspberry Pi OS — needed to open USB cameras.
+SupplementaryGroups=video
+# Inherit a sane PATH so ffmpeg (system-installed) is found even when
+# systemd's default PATH skips /usr/local/bin.
+Environment=PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
+# Suppress the TUI's ANSI cursor escapes so journalctl entries stay
+# line-oriented instead of full-screen redraws.
+Environment=NO_COLOR=1
+Environment=TERM=dumb
 Environment=RUST_LOG=info
+WorkingDirectory=/home/YOUR_USER
+ExecStart=/home/YOUR_USER/.sourcebox-sentry/sourcebox-sentry-cloudnode run
+StandardOutput=journal
+StandardError=journal
+Restart=on-failure
+RestartSec=5s
+# Stop retrying after 5 failures in a minute so logs stay readable.
+StartLimitIntervalSec=60
+StartLimitBurst=5
 
 [Install]
 WantedBy=multi-user.target`}</code>
         <button className="docs-copy-btn" onClick={() => copyToClipboard(`[Unit]
 Description=SourceBox Sentry CloudNode
+Documentation=https://opensentry-command.fly.dev
 After=network-online.target
 Wants=network-online.target
 
 [Service]
 Type=simple
-User=sentry
-WorkingDirectory=/opt/sourcebox-sentry
-ExecStart=/opt/sourcebox-sentry/sourcebox-sentry-cloudnode
-Restart=on-failure
-RestartSec=5
+User=YOUR_USER
+SupplementaryGroups=video
+Environment=PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
+Environment=NO_COLOR=1
+Environment=TERM=dumb
 Environment=RUST_LOG=info
+WorkingDirectory=/home/YOUR_USER
+ExecStart=/home/YOUR_USER/.sourcebox-sentry/sourcebox-sentry-cloudnode run
+StandardOutput=journal
+StandardError=journal
+Restart=on-failure
+RestartSec=5s
+StartLimitIntervalSec=60
+StartLimitBurst=5
 
 [Install]
 WantedBy=multi-user.target`)}>Copy</button>
diff --git a/frontend/src/pages/docs/Faq.jsx b/frontend/src/pages/docs/Faq.jsx
@@ -11,17 +11,19 @@ function Faq() {
         "mute" toggle yet — remove or mute the input source if you need silent-only.
       </p>
 
-      <h3>Should I use the Windows MSI or the PowerShell installer?</h3>
+      <h3>How do I install CloudNode on Windows?</h3>
       <p>
-        Use the MSI for any node you want running 24/7 — it registers CloudNode as a
-        Windows Service that auto-starts on boot, runs as <code>LocalSystem</code> (so
-        it works without you being logged in), and lives under <code>C:\Program Files</code> /{" "}
-        <code>C:\ProgramData</code> like a proper system service. The PowerShell one-liner
-        installer is fine for a quick test or a personal-use foreground install, but
-        once you log out the cameras stop streaming. The MSI is currently unsigned —
-        SmartScreen warns "Windows protected your PC" on first run; click{" "}
-        <strong>More info → Run anyway</strong>. See the{" "}
-        <a href="#cloudnode-setup">CloudNode Setup</a> section for the full service flow.
+        Download <code>sourcebox-sentry-cloudnode-windows-x86_64.msi</code> from the{" "}
+        <a href="https://github.com/SourceBox-LLC/opensentry-cloud-node/releases/latest" target="_blank" rel="noopener noreferrer">latest GitHub release</a>{" "}
+        and run it. The MSI is unsigned today, so SmartScreen will warn "Windows protected
+        your PC" on first run — click <strong>More info → Run anyway</strong>. After install,
+        click the <strong>SourceBox Sentry CloudNode</strong> shortcut from the Start menu —
+        first launch runs the setup wizard, every launch after streams cameras directly. For
+        24/7 unattended operation, the MSI also registers an optional Windows Service named{" "}
+        <code>SourceBoxSentryCloudNode</code> that you can flip to auto-start; see the{" "}
+        <a href="#cloudnode-setup">CloudNode Setup</a> section for details. There is no
+        PowerShell one-liner installer — that path was retired in v0.1.31 because the MSI
+        is the only Windows install that handles upgrades and Add/Remove Programs cleanly.
       </p>
 
       <h3>Can I use IP cameras (RTSP) instead of USB?</h3>
diff --git a/frontend/src/pages/docs/GettingStarted.jsx b/frontend/src/pages/docs/GettingStarted.jsx
@@ -70,7 +70,7 @@ function GettingStarted() {
         <li>A USB webcam (built-in laptop cameras work too)</li>
         <li>A SourceBox Sentry account (free tier covers up to 5 cameras across 2 nodes, with 30 viewer-hours/month of live playback)</li>
         <li>A Linux, Windows, or macOS machine for CloudNode</li>
-        <li>FFmpeg installed (or Docker) — the installer downloads it automatically on Windows</li>
+        <li>FFmpeg installed (or Docker) — the setup wizard offers to install it via your OS package manager (<code>winget</code> on Windows, <code>brew</code> on macOS, <code>apt</code>/<code>dnf</code>/<code>pacman</code> on Linux)</li>
         <li>Outbound HTTPS access from the CloudNode machine to the internet</li>
       </ul>
 
@@ -95,7 +95,7 @@ function GettingStarted() {
           <div className="docs-step-content">
             <h4>Install CloudNode</h4>
             <OsTabs id="qs" />
-            <p>The installer downloads CloudNode, checks for FFmpeg, and walks you through setup.</p>
+            <p>The installer downloads CloudNode and walks you through setup. If FFmpeg isn't already on the system, the wizard offers to install it via your OS package manager.</p>
           </div>
         </div>
         <div className="docs-step">
diff --git a/frontend/src/pages/docs/Troubleshooting.jsx b/frontend/src/pages/docs/Troubleshooting.jsx
@@ -24,15 +24,20 @@ sudo usermod -a -G video $USER
       <p><strong>macOS:</strong> grant camera access in <strong>System Settings &gt; Privacy & Security &gt; Camera</strong> — you'll need to approve the terminal app running CloudNode.</p>
 
       <h3>FFmpeg not found</h3>
-      <p><strong>Windows:</strong> re-run <code>sourcebox-sentry-cloudnode setup</code>. The wizard downloads a portable FFmpeg into <code>./ffmpeg/bin/</code> if it's missing.</p>
-      <p><strong>Linux / macOS:</strong> install via your package manager:</p>
+      <p>CloudNode looks for FFmpeg on PATH. Install it via your OS package manager:</p>
       <div className="docs-code-block">
-        <code>{`sudo apt install ffmpeg        # Ubuntu / Debian
+        <code>{`winget install Gyan.FFmpeg     # Windows
+brew install ffmpeg            # macOS
+sudo apt install ffmpeg        # Ubuntu / Debian
 sudo dnf install ffmpeg        # Fedora
-sudo pacman -S ffmpeg          # Arch
-brew install ffmpeg            # macOS`}</code>
-        <button className="docs-copy-btn" onClick={() => copyToClipboard('sudo apt install ffmpeg')}>Copy</button>
+sudo pacman -S ffmpeg          # Arch`}</code>
+        <button className="docs-copy-btn" onClick={() => copyToClipboard('winget install Gyan.FFmpeg')}>Copy</button>
       </div>
+      <p>
+        Re-run <code>sourcebox-sentry-cloudnode setup</code> — the wizard offers to run the right
+        command for your platform if FFmpeg still isn't on PATH. After a Windows winget install,
+        open a new terminal so the updated PATH is picked up.
+      </p>
 
       <h3>Stream won't play in the dashboard</h3>
       <ol>
diff --git a/frontend/src/pages/docs/context.jsx b/frontend/src/pages/docs/context.jsx
@@ -49,9 +49,10 @@ export function DocsProvider({ children }) {
   const base = window.location.origin
   // Windows is intentionally absent — that platform installs via the MSI
   // from GitHub Releases (rendered as a download button in OsTabs) rather
-  // than a curl-style one-liner. The PowerShell installer was retired
-  // when the MSI shipped: the MSI registers a Windows Service, which is
-  // the right execution model for an always-on camera node.
+  // than a curl-style one-liner. There used to be a PowerShell installer
+  // alongside the MSI; it was retired in v0.1.31 because the MSI is the
+  // only Windows install path that handles upgrades + Add/Remove Programs
+  // cleanly.
   const installCommands = {
     linux: `curl -fsSL ${base}/install.sh | bash`,
     macos: `curl -fsSL ${base}/install.sh | bash`,
@@ -146,9 +147,9 @@ export function OsTabs({ id }) {
             </a>
             <p style={{ marginTop: "0.75rem", fontSize: "0.9rem", color: "var(--text-muted)" }}>
               Run the MSI (UAC prompt; SmartScreen → <strong>More info → Run anyway</strong>),
-              then open PowerShell as Administrator and run{" "}
-              <code>sourcebox-sentry-cloudnode setup</code>. The MSI registers
-              a Windows Service that auto-starts on boot.
+              then open the <strong>SourceBox Sentry CloudNode</strong> shortcut from the
+              Start menu. First launch runs the setup wizard; every launch after streams
+              cameras directly.
             </p>
           </div>
         )}
