# 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:

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

## 2. Prepare The Host

Run as root:

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

The six-stage prepare flow:

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

## 3. Configure

Edit:

```text
/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:

```sh
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

```sh
./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

```sh
./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

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

```sh
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:

```text
@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.