feat: publish dbussmsforward refactor

2026-05-08 23:54:03 +08:00
commit 9f1ee9ffe6
77 changed files with 15585 additions and 0 deletions
@@ -0,0 +1,172 @@
+# Deployment Guide
+
+This document covers the Python refactor deployment layout for Debian/systemd and OpenWRT/procd.
+
+## Runtime assumptions
+
+- Python 3.11+ is available on the target machine.
+- The project is deployed as source code under `/opt/dbussmsforward`.
+- Runtime config lives at `/etc/dbussmsforward/appsettings.json`.
+- For real modem integration, `sms_source.kind` should be `modemmanager` and the host must expose the system D-Bus socket.
+
+Recommended target layout:
+
+```text
+/opt/dbussmsforward/
+  src/
+  wwwroot/
+  pyproject.toml
+  README.md
+/etc/dbussmsforward/
+  appsettings.json
+```
+
+A starter production-like config is provided at `deploy/common/appsettings.deploy.json`.
+
+---
+
+## Debian / systemd
+
+### Install dependencies
+
+```bash
+sudo apt update
+sudo apt install -y python3 python3-venv python3-pip dbus modemmanager
+sudo systemctl enable --now dbus ModemManager
+```
+
+### Copy project files
+
+```bash
+sudo mkdir -p /opt/dbussmsforward /etc/dbussmsforward
+sudo cp -R src wwwroot pyproject.toml README.md /opt/dbussmsforward/
+sudo cp deploy/common/appsettings.deploy.json /etc/dbussmsforward/appsettings.json
+sudo cp deploy/debian/dbussmsforward.service /etc/systemd/system/dbussmsforward.service
+```
+
+### Start service
+
+```bash
+sudo systemctl daemon-reload
+sudo systemctl enable --now dbussmsforward
+sudo systemctl status dbussmsforward
+```
+
+### Logs
+
+```bash
+journalctl -u dbussmsforward -f
+```
+
+### One-shot installer
+
+```bash
+sudo sh deploy/debian/install.sh
+```
+
+The installer now runs `env-check --format json` before enabling the service.
+If the check fails, installation stops and writes a machine-readable report to:
+
+```text
+/etc/dbussmsforward/install-env-check.json
+```
+
+---
+
+## OpenWRT / procd
+
+### Install dependencies
+
+```sh
+opkg update
+opkg install python3 python3-light dbus modemmanager
+/etc/init.d/dbus enable && /etc/init.d/dbus start
+/etc/init.d/modemmanager enable && /etc/init.d/modemmanager start
+```
+
+> Depending on firmware, you may need extra Python packages or to bundle a venv/site-packages tree yourself.
+
+### Copy project files
+
+```sh
+mkdir -p /opt/dbussmsforward /etc/dbussmsforward
+cp -R src wwwroot pyproject.toml README.md /opt/dbussmsforward/
+cp deploy/common/appsettings.deploy.json /etc/dbussmsforward/appsettings.json
+cp deploy/openwrt/dbussmsforward.init /etc/init.d/dbussmsforward
+chmod +x /etc/init.d/dbussmsforward
+```
+
+### Start service
+
+```sh
+/etc/init.d/dbussmsforward enable
+/etc/init.d/dbussmsforward start
+/etc/init.d/dbussmsforward status
+```
+
+### Logs
+
+```sh
+logread -e dbussmsforward
+```
+
+### One-shot installer
+
+```sh
+sh deploy/openwrt/install.sh
+```
+
+The installer now runs `env-check --format json` before enabling the init script.
+If the check fails, installation stops and writes a machine-readable report to:
+
+```text
+/etc/dbussmsforward/install-env-check.json
+```
+
+---
+
+## Config notes
+
+The deploy template defaults to:
+
+- `forwarding.enabled_channels = ["autman_push"]`
+- `notifications.autman_push.enabled = true`
+- `sms_source.kind = "modemmanager"`
+- `sms_source.modem_object_path = "auto"`
+
+You should replace:
+
+- `forwarding.device_name`
+- `notifications.autman_push.api_url`
+- `notifications.autman_push.access_token`
+
+If you want a safer smoke test before connecting to ModemManager, switch to:
+
+```json
+"notifications": { "console": { "enabled": true } },
+"sms_source": {
+  "kind": "file",
+  "path": "tests/fixtures/messages.json"
+}
+```
+
+---
+
+## Verification checklist
+
+Before enabling the service permanently:
+
+```bash
+PYTHONPATH=src python3 -m dbussmsforward.cli validate-config --config deploy/common/appsettings.deploy.json
+PYTHONPATH=src python3 -m dbussmsforward.cli env-check --config deploy/common/appsettings.deploy.json --format json
+```
+
+The JSON output contains a `results` array plus a `summary` object, making it suitable for CI, installers, and deployment health probes.
+
+For a local foreground smoke test:
+
+```bash
+PYTHONPATH=src python3 -m dbussmsforward.cli run --config /etc/dbussmsforward/appsettings.json --iterations 1
+```
+
+For actual daemon/service mode, the service files use `--iterations 0`, which means keep polling forever.