Configuration reference, server deployment, and twcore upgrade

[fylorn]

Phase P6 of the remote-core plan: the configuration manual, what it takes to run core on a Linux server, and a way to upgrade it there.

Configuration reference (docs/config.md, docs/config.zh-CN.md)

Every section and field of config.yaml, with defaults, allowed values and examples, plus how a change takes effect: the reload stages, a rejected version keeping the previous one in service, history and rollback, twcore check / config show|set|history|rollback, and the environment variables core reads.

The field tables and built-in rule lists are generated and checked. Everything between <!-- generated: … --> and <!-- /generated --> is rendered from crates/tw-config/tests/manual/schema.rs; cargo test -p tw-config --test manual fails when manual and code disagree. The declaration is verified against the code rather than trusted:

• field names come from serde (a probe Deserializer records the names a derived Deserialize asks for), so a new field without a row fails with its name;
• a declared default is written into a minimal section and must parse to the same value as omitting it; a required field must fail without it;
• enum values (protocol, mode, group type, …) are read from serde;
• YAML examples in the manuals are parsed as configuration.

Regenerate: UPDATE_CONFIG_DOCS=1 cargo test -p tw-config --test manual. CONTRIBUTING describes it.

Fields documented ahead of the code

Rebased onto #184: listen.control.key is now checked against ControlListen like every other field.

listen.control.remote {enabled, bind, port, allow_from} (P4) is declared Ty::Pending: documented under listen.control, and the test fails as soon as ControlListen reads remote, asking for the pending declaration in crates/tw-config/tests/manual/schema.rs to be replaced with checked!(RemoteType, "{}"); its rows and defaults are then verified. Declared defaults to confirm then: enabled: false, bind: all, allow_from: the private ranges, port generated. The server guide assumes twcore init may or may not write a disabled remote section with a random port (it covers both).

Server deployment

• docs/server.md (+ zh-CN): install → twcore init → the three config edits → systemd → twcore control-key → add the connection in the desktop app; upgrading; uninstalling.
• packaging/systemd/twcore.service: user thinkwatch, THINKWATCH_HOME=/var/lib/thinkwatch (StateDirectory, 0700), EnvironmentFile=-/etc/thinkwatch/env for ${VAR}, Restart=on-failure, hardening that leaves only the data directory writable (systemd-analyze security: 1.4 OK), AF_NETLINK kept so an interface name in bind resolves.
• scripts/install.sh (POSIX sh, shellcheck-clean): arch detection, latest or --version, SHA-256 check, runs the binary once, atomic install to /usr/local/bin, user + data dir + env file + unit, twcore init when there is no config, next steps. Idempotent; never starts or restarts the service. --archive FILE installs from a downloaded tarball.

Release assets

release.yml keeps every existing file and adds, for Linux x86_64 and aarch64:

• twcore-<target>.tar.gz containing twcore-<target>/{twcore, twcore.service, LICENSE}
• twcore-<target>.tar.gz.sha256

The workflow also unpacks the tarball the way the installer does. Not triggered here; a workflow_dispatch rehearsal would exercise it without publishing.

twcore upgrade

twcore upgrade [--check] [--restart] [--version X.Y.Z]: GitHub release lookup, version comparison (a pinned version installs even if older, since the server has to match the app), download of the bare twcore-<target> asset, SHA-256 check, a --version run of the new file, atomic rename over the current executable (move-aside on Windows). --restart restarts twcore.service when systemd runs it; otherwise it prints the command. The copy inside the desktop app (.app, AppImage, ThinkWatch Lite install dir) is refused. No new dependencies (reqwest, sha2 already in the tree). Tests cover version comparison, asset selection, checksum verification, the full flow against a local fake GitHub, replacing a running binary, and that release.yml publishes the names upgrade looks for.

Verified

• cargo fmt, clippy --workspace --all-targets -D warnings, cargo test --workspace.
• Under systemd on Ubuntu 22.04 aarch64 (Docker): install.sh from a tarball, twcore check as the service user, enable --now, gateway and control socket up under the hardening, live reload of a hand edit, bind: eth0 resolving, reinstall while running, and twcore upgrade --version 0.45.0 with and without --restart against the real GitHub releases (and refusing without root).
• On macOS: twcore upgrade --check and a real downgrade of a copied binary.

🤖 Generated with Claude Code