From 0ea5b5f8f68612c03a713e594580db1c09e40ead Mon Sep 17 00:00:00 2001 From: weishu Date: Thu, 22 Jan 2026 20:43:16 +0800 Subject: [PATCH] docs: add background service deployment section with nohup, pm2, launchd, and systemd examples --- docs/guide/installation.md | 199 +++++++++++++++++++++++++++++++++++++ 1 file changed, 199 insertions(+) diff --git a/docs/guide/installation.md b/docs/guide/installation.md index 8ec9f0db..6e9091e6 100644 --- a/docs/guide/installation.md +++ b/docs/guide/installation.md @@ -319,6 +319,205 @@ pm2 save ``` +### Background service deployment + +Keep HAPI running persistently so it survives terminal closes, system restarts, and continues running in the background. + +
+Quick: nohup + +Simple one-liner for quick background runs: + +```bash +# Server +nohup hapi server --relay > ~/.hapi/logs/server.log 2>&1 & + +# Runner +nohup hapi runner start --foreground > ~/.hapi/logs/runner.log 2>&1 & +``` + +View logs: + +```bash +tail -f ~/.hapi/logs/server.log +tail -f ~/.hapi/logs/runner.log +``` + +Stop processes: + +```bash +pkill -f "hapi server" +pkill -f "hapi runner" +``` +
+ +
+pm2 (recommended for Node.js users) + +pm2 provides process management with auto-restart on crashes and system reboot. + +```bash +# Install pm2 +npm install -g pm2 + +# Start server and runner +pm2 start "hapi server --relay" --name hapi-server +pm2 start "hapi runner start --foreground" --name hapi-runner + +# View status and logs +pm2 status +pm2 logs hapi-server +pm2 logs hapi-runner + +# Auto-restart on system reboot +pm2 startup # Follow the printed instructions +pm2 save # Save current process list +``` +
+ +
+macOS: launchd + +Create plist files for automatic startup on macOS. + +**Server** (`~/Library/LaunchAgents/com.hapi.server.plist`): + +```xml + + + + + Label + com.hapi.server + ProgramArguments + + /usr/local/bin/hapi + server + --relay + + RunAtLoad + + KeepAlive + + StandardOutPath + /Users/YOUR_USERNAME/.hapi/logs/server.log + StandardErrorPath + /Users/YOUR_USERNAME/.hapi/logs/server.log + + +``` + +**Runner** (`~/Library/LaunchAgents/com.hapi.runner.plist`): + +```xml + + + + + Label + com.hapi.runner + ProgramArguments + + /usr/local/bin/hapi + runner + start + --foreground + + RunAtLoad + + KeepAlive + + StandardOutPath + /Users/YOUR_USERNAME/.hapi/logs/runner.log + StandardErrorPath + /Users/YOUR_USERNAME/.hapi/logs/runner.log + + +``` + +Load/unload services: + +```bash +# Load (start) +launchctl load ~/Library/LaunchAgents/com.hapi.server.plist +launchctl load ~/Library/LaunchAgents/com.hapi.runner.plist + +# Unload (stop) +launchctl unload ~/Library/LaunchAgents/com.hapi.server.plist +launchctl unload ~/Library/LaunchAgents/com.hapi.runner.plist +``` + +> **macOS sleep note:** macOS may suspend background processes when the display sleeps. Use `caffeinate` to prevent this: +> ```bash +> caffeinate -dimsu hapi server --relay +> ``` +> Or run `caffeinate -dimsu` in a separate terminal while HAPI is running. +
+ +
+Linux: systemd + +Create user-level systemd services for automatic startup. + +**Server** (`~/.config/systemd/user/hapi-server.service`): + +```ini +[Unit] +Description=HAPI Server +After=network.target + +[Service] +Type=simple +ExecStart=/usr/local/bin/hapi server --relay +Restart=always +RestartSec=5 + +[Install] +WantedBy=default.target +``` + +**Runner** (`~/.config/systemd/user/hapi-runner.service`): + +```ini +[Unit] +Description=HAPI Runner +After=network.target hapi-server.service + +[Service] +Type=simple +ExecStart=/usr/local/bin/hapi runner start --foreground +Restart=always +RestartSec=5 + +[Install] +WantedBy=default.target +``` + +Enable and start: + +```bash +# Reload systemd +systemctl --user daemon-reload + +# Enable (auto-start on login) +systemctl --user enable hapi-server +systemctl --user enable hapi-runner + +# Start now +systemctl --user start hapi-server +systemctl --user start hapi-runner + +# View status/logs +systemctl --user status hapi-server +journalctl --user -u hapi-server -f +``` + +> **Persist after logout:** To keep services running even when not logged in: +> ```bash +> loginctl enable-linger $USER +> ``` +
+ ### Voice assistant setup Enable voice control: