From 1dae5cd9ab4d72fcd8c8ac6058cea7a107a180a4 Mon Sep 17 00:00:00 2001 From: Federico Jaramillo Martinez Date: Fri, 15 May 2026 23:53:15 +0200 Subject: [PATCH] docs: clarify networking and cleanup guidance --- docs/faq.html | 26 ++++++++++++++++----- docs/install.html | 59 +++++++++++++++++++++++++++++++++++++++-------- 2 files changed, 70 insertions(+), 15 deletions(-) diff --git a/docs/faq.html b/docs/faq.html index 83e685a..ca7b05b 100644 --- a/docs/faq.html +++ b/docs/faq.html @@ -91,7 +91,11 @@
  • zsh: put PATH setup in ~/.zprofile, not only ~/.zshrc.
  • fish: prefer universal PATH setup, for example fish_add_path -U ....
    • -

    Avoid relying only on prompt hooks or interactive-only shell files for tools needed by services.

    +

    + 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. +

    @@ -109,11 +113,13 @@

    I installed Node with nvm, fnm, asdf, or another version manager

    - 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 fnm and + mise 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.

      -
    • Move the version manager initialization to your login shell file.
      • +
    • Prefer version-manager shims when available; for mise, use shims or enable its shim setup rather than relying only on shell activation.
      • +
    • Move any required version-manager initialization to your login shell file.
    • Make sure node --version is at least v22 from bash -lc, zsh -lc, or your detected shell.
    • Run pi-web doctor again after changing shell files.
    @@ -149,8 +155,16 @@

    Can I expose Pi Web to the public internet?

    - 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. +

    +

    + When you connect over a VPN, 127.0.0.1 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. +

    +

    + Avoid 0.0.0.0 unless a firewall, VPN, or reverse proxy strictly limits who can reach the port.

    diff --git a/docs/install.html b/docs/install.html index d4d74c0..dcc8a8b 100644 --- a/docs/install.html +++ b/docs/install.html @@ -150,8 +150,8 @@

    Remote access

    - Pi Web binds to 127.0.0.1:8504 by default. For a remote server, keep that safe default and use an - SSH tunnel: + Pi Web binds to 127.0.0.1:8504 by default. For a remote server, the safest option is an SSH + tunnel:

    @@ -163,7 +163,9 @@
    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 + 0.0.0.0 unless a firewall, VPN, or authenticated reverse proxy strictly controls the port.
    @@ -186,12 +188,29 @@

    Configure

    - The installer writes a config file under your user config directory. The web server defaults to - 127.0.0.1:8504 and stores Pi Web state in ~/.pi-web. + The installer writes a config file to ~/.config/pi-web/config.json, or to + $XDG_CONFIG_HOME/pi-web/config.json when XDG_CONFIG_HOME is set. You can choose a + different config file during install with pi-web install --config /path/to/config.json, or at + runtime with PI_WEB_CONFIG=/path/to/config.json. +

    +
    +
    + Default config + +
    + 
    {
+  "host": "127.0.0.1",
+  "port": 8504,
+  "allowedHosts": []
+}
    +
    +

    + The web server defaults to 127.0.0.1:8504 and stores Pi Web state in ~/.pi-web.

      -
    • PI_WEB_PORT or PORT: web server port.
      • -
    • PI_WEB_HOST: web server bind host. Keep 127.0.0.1 unless you know why not.
      • +
    • PI_WEB_CONFIG: path to a config JSON file. Defaults to ~/.config/pi-web/config.json.
      • +
    • PI_WEB_PORT or PORT: web server port. Overrides the config file.
      • +
    • PI_WEB_HOST: web server bind host. Overrides the config file. Use 127.0.0.1 for local/tunnel-only access, or a specific VPN/private-network IP for trusted remote access.
    • PI_WEB_DATA_DIR: data directory, default ~/.pi-web.
    • PI_WEB_SESSIOND_SOCKET: Unix socket path for daemon communication.
    @@ -199,15 +218,37 @@

    Uninstall

    -

    Remove the user services, then remove the npm package if you installed it globally.

    +

    + pi-web uninstall stops, disables, and removes the systemd user services. It does not remove + the npm package, config file, or data directory. +

    - Uninstall + Uninstall services and package 
    $ pi-web uninstall
 $ npm uninstall -g @jmfederico/pi-web
    +

    Optional cleanup, if you also want to delete Pi Web config and state:

    +
    +
    + Delete config and data + +
    + 
    $ CONFIG_FILE="${PI_WEB_CONFIG:-${XDG_CONFIG_HOME:-$HOME/.config}/pi-web/config.json}"
+$ DATA_DIR="${PI_WEB_DATA_DIR:-$HOME/.pi-web}"
+$ rm -f "$CONFIG_FILE"
+$ rmdir "$(dirname "$CONFIG_FILE")" 2>/dev/null || true
+$ rm -rf "$DATA_DIR"
+
+# If you configured a socket outside PI_WEB_DATA_DIR, remove it too:
+$ [ -z "${PI_WEB_SESSIOND_SOCKET:-}" ] || rm -f "$PI_WEB_SESSIOND_SOCKET"
    +
    +

    + If you installed with pi-web install --config /custom/path.json, delete that custom file instead + of the default config path. +