snowspeeder/pi-web
Archived
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: clarify networking and cleanup guidance

Browse Source
This commit is contained in:
Federico Jaramillo Martinez
2026-05-15 23:53:15 +02:00
parent c66d834c88
commit 1dae5cd9ab
2 changed files with 70 additions and 15 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/faq.html
+20 -6
View File
@@ -91,7 +91,11 @@
<li><strong>zsh:</strong> put PATH setup in <code>~/.zprofile</code>, not only <code>~/.zshrc</code>.</li>
<li><strong>fish:</strong> prefer universal PATH setup, for example <code>fish_add_path -U ...</code>.</li>
</ul>
<p>Avoid relying only on prompt hooks or interactive-only shell files for tools needed by services.</p>
<p>
Avoid relying only on prompt hooks, shell integrations that rewrite PATH while rendering a prompt, or
interactive-only shell files for tools needed by services. Version-manager shims are usually the most
reliable option for service environments.
</p>
</article>
<article id="doctor-fails" class="faq-item">
@@ -109,11 +113,13 @@
<article id="nvm-fnm-asdf" class="faq-item">
<h2>I installed Node with nvm, fnm, asdf, or another version manager</h2>
<p>
Version managers often initialize in interactive shells only. Pi Web needs Node and npm to be available to
login shells and systemd user services.
Version managers often initialize in interactive shells only. Some tools, including <code>fnm</code> and
<code>mise</code> when used through shell activation instead of shims, depend on shell hooks or prompt-time
PATH updates that are unreliable in non-interactive login shells.
</p>
<ul>
<li>Move the version manager initialization to your login shell file.</li>
<li>Prefer version-manager shims when available; for <code>mise</code>, use shims or enable its shim setup rather than relying only on shell activation.</li>
<li>Move any required version-manager initialization to your login shell file.</li>
<li>Make sure <code>node --version</code> is at least <code>v22</code> from <code>bash -lc</code>, <code>zsh -lc</code>, or your detected shell.</li>
<li>Run <code>pi-web doctor</code> again after changing shell files.</li>
</ul>
@@ -149,8 +155,16 @@
<article id="public-internet" class="faq-item">
<h2>Can I expose Pi Web to the public internet?</h2>
<p>
Do not expose it directly. Pi Web assumes trusted users and trusted server paths. Keep the default
localhost bind and use SSH tunneling, a VPN, or a reverse proxy with authentication and network policy.
Do not expose it directly to the public internet. Pi Web assumes trusted users and trusted server paths.
For remote access, bind only to an interface that is already private and controlled: for example the
server's VPN IP, a private LAN IP, or localhost behind an SSH tunnel.
</p>
<p>
When you connect over a VPN, <code>127.0.0.1</code> usually means your own device, not the server, so the
server must listen on its VPN/private-network address or sit behind a tunnel/proxy.
</p>
<p>
Avoid <code>0.0.0.0</code> unless a firewall, VPN, or reverse proxy strictly limits who can reach the port.
</p>
</article>
docs/install.html
+50 -9
View File
@@ -150,8 +150,8 @@
<section id="remote-access">
<h2>Remote access</h2>
<p>
Pi Web binds to <code>127.0.0.1:8504</code> by default. For a remote server, keep that safe default and use an
SSH tunnel:
Pi Web binds to <code>127.0.0.1:8504</code> by default. For a remote server, the safest option is an SSH
tunnel:
</p>
<div class="code-card">
<div class="copy-row">
@@ -163,7 +163,9 @@
</div>
<div class="callout danger">
Pi Web is designed for trusted users and trusted server paths. Do not expose it directly to the public
internet without adding your own network controls, authentication, or reverse proxy policy.
internet. If you use a VPN or private network, bind Pi Web to the server's VPN/private IP, such as a
Tailscale/WireGuard/LAN address, and make sure that network policy limits access. Avoid
<code>0.0.0.0</code> unless a firewall, VPN, or authenticated reverse proxy strictly controls the port.
</div>
</section>
@@ -186,12 +188,29 @@
<section id="configure">
<h2>Configure</h2>
<p>
The installer writes a config file under your user config directory. The web server defaults to
<code>127.0.0.1:8504</code> and stores Pi Web state in <code>~/.pi-web</code>.
The installer writes a config file to <code>~/.config/pi-web/config.json</code>, or to
<code>$XDG_CONFIG_HOME/pi-web/config.json</code> when <code>XDG_CONFIG_HOME</code> is set. You can choose a
different config file during install with <code>pi-web install --config /path/to/config.json</code>, or at
runtime with <code>PI_WEB_CONFIG=/path/to/config.json</code>.
</p>
<div class="code-card">
<div class="copy-row">
<strong>Default config</strong>
<button class="copy-button" data-copy="#config-example">Copy</button>
</div>
<pre id="config-example"><code>{
"host": "127.0.0.1",
"port": 8504,
"allowedHosts": []
}</code></pre>
</div>
<p>
The web server defaults to <code>127.0.0.1:8504</code> and stores Pi Web state in <code>~/.pi-web</code>.
</p>
<ul>
<li><code>PI_WEB_PORT</code> or <code>PORT</code>: web server port.</li>
<li><code>PI_WEB_HOST</code>: web server bind host. Keep <code>127.0.0.1</code> unless you know why not.</li>
<li><code>PI_WEB_CONFIG</code>: path to a config JSON file. Defaults to <code>~/.config/pi-web/config.json</code>.</li>
<li><code>PI_WEB_PORT</code> or <code>PORT</code>: web server port. Overrides the config file.</li>
<li><code>PI_WEB_HOST</code>: web server bind host. Overrides the config file. Use <code>127.0.0.1</code> for local/tunnel-only access, or a specific VPN/private-network IP for trusted remote access.</li>
<li><code>PI_WEB_DATA_DIR</code>: data directory, default <code>~/.pi-web</code>.</li>
<li><code>PI_WEB_SESSIOND_SOCKET</code>: Unix socket path for daemon communication.</li>
</ul>
@@ -199,15 +218,37 @@
<section id="uninstall">
<h2>Uninstall</h2>
<p>Remove the user services, then remove the npm package if you installed it globally.</p>
<p>
<code>pi-web uninstall</code> stops, disables, and removes the systemd user services. It does not remove
the npm package, config file, or data directory.
</p>
<div class="code-card">
<div class="copy-row">
<strong>Uninstall</strong>
<strong>Uninstall services and package</strong>
<button class="copy-button" data-copy="#uninstall-commands">Copy</button>
</div>
<pre id="uninstall-commands"><code><span class="prompt">$</span> pi-web uninstall
<span class="prompt">$</span> npm uninstall -g @jmfederico/pi-web</code></pre>
</div>
<p>Optional cleanup, if you also want to delete Pi Web config and state:</p>
<div class="code-card">
<div class="copy-row">
<strong>Delete config and data</strong>
<button class="copy-button" data-copy="#delete-data-commands">Copy</button>
</div>
<pre id="delete-data-commands"><code><span class="prompt">$</span> CONFIG_FILE="${PI_WEB_CONFIG:-${XDG_CONFIG_HOME:-$HOME/.config}/pi-web/config.json}"
<span class="prompt">$</span> DATA_DIR="${PI_WEB_DATA_DIR:-$HOME/.pi-web}"
<span class="prompt">$</span> rm -f "$CONFIG_FILE"
<span class="prompt">$</span> rmdir "$(dirname "$CONFIG_FILE")" 2&gt;/dev/null || true
<span class="prompt">$</span> rm -rf "$DATA_DIR"
<span class="comment"># If you configured a socket outside PI_WEB_DATA_DIR, remove it too:</span>
<span class="prompt">$</span> [ -z "${PI_WEB_SESSIOND_SOCKET:-}" ] || rm -f "$PI_WEB_SESSIOND_SOCKET"</code></pre>
</div>
<p>
If you installed with <code>pi-web install --config /custom/path.json</code>, delete that custom file instead
of the default config path.
</p>
</section>
</div>
</div>