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