Zero To Running

This runbook prepares a new apt-based Linux host without embedding any private host, account, group, or provider value in the repository.

JWeBot does not install desktop WeChat itself. Install a compatible client, create an X11/VNC desktop on display :1, sign in manually, and keep the main window visible before deployment.

1. Obtain A Clean Snapshot

Clone or unpack the public repository. Before using a fork:

./tools/check-secrets.py --history

2. Prepare The Host

Run as root:

./deploy/scripts/bootstrap-jwebot.sh \
  prepare \
  /path/to/JWeBot \
  jwebot \
  default

The six-stage prepare flow:

installs OS packages for Python, X11 interaction, screenshots, clipboard, and OCR fallback;
creates the runtime account when absent;
creates /opt/jwebot/venv;
installs runtime Python dependencies and JWeBot packages;
generates a private config profile;
creates private state directories.

3. Configure

Edit:

/home/jwebot/.config/jwebot/profiles/default/

At minimum:

set the bot mention and provider URLs in component TOML;
put API keys only in secrets/runtime.env;
configure Steam owner ID and loopback proxy when using /steam;
put person aliases only in context/people.json;
configure a notification argv adapter or leave it disabled;
verify deployment paths.

Activate as the runtime user:

sudo -u jwebot -H /opt/jwebot/venv/bin/python \
  -m jwebot_config activate default

4. Prepare The Desktop

The runtime expects:

an X11 desktop at DISPLAY=:1;
the runtime user's .Xauthority;
a visible WeChat main window named Weixin;
a maximized window large enough for the adaptive layout gate;
loopback VNC on port 5901 for guarded input;
no second process controlling the same GUI.

VNC/noVNC must remain loopback-only or be reached through an authenticated SSH tunnel. Never expose it directly.

5. Verify

./deploy/scripts/bootstrap-jwebot.sh \
  verify \
  /path/to/JWeBot \
  jwebot \
  default

Verify checks runtime imports, required executables, profile validation, repository config/privacy gates, and the visible WeChat window.

6. Deploy

./deploy/scripts/bootstrap-jwebot.sh \
  deploy \
  /path/to/JWeBot \
  jwebot \
  default

This invokes the coordinated production deployer. It does not bypass queue, ready-window, health, SQLite, or restart-stability gates.

7. Acceptance

systemctl --user is-active jwebot-edge.service
systemctl --user is-active wechat-ocr-adaptive-recorder.service

printf '%s\n' '{"op":"health"}' |
  /opt/jwebot/venv/bin/python \
  ~/.local/lib/wechat-health-watch/jwebot_edge.py respond

Send synthetic messages in the configured group:

@JWeBot /version
@JWeBot /steam
@JWeBot /steam时长Dota2

Confirm one ACK, one final reply, no duplicate delivery, empty queues, stable restart counts, and SQLite quick_check=ok.

Non-Apt Hosts

Use prepare as a dependency manifest:

install equivalent X11, OCR, Python, and clipboard packages;
create the same runtime user and virtualenv;
run jwebot_config init/activate;
run the verify and coordinated deployment gates manually.

Do not translate package names into an unreviewed installer and run it directly on production.

3.3 KiB Raw Blame History