First commit

SYSTEMD_SETUP.md

@@ -0,0 +1,78 @@
+# systemd Service Installation
+
+Quick setup to run system2mqtt as a systemd service on Linux.
+
+## Installation Steps
+
+1. **Create dedicated user:**
+   ```bash
+   sudo useradd -r -s /usr/sbin/nologin -d /opt/system2mqtt system2mqtt
+   ```
+
+2. **Install system to /opt/system2mqtt:**
+   ```bash
+   sudo mkdir -p /opt/system2mqtt
+   sudo cp -r system2mqtt.py collectors config.yaml.example run.sh /opt/system2mqtt/
+   sudo cp requirements.txt /opt/system2mqtt/
+   sudo chmod +x /opt/system2mqtt/run.sh
+   sudo chown -R system2mqtt:system2mqtt /opt/system2mqtt
+   ```
+
+3. **Configure:**
+   ```bash
+   # Copy and edit config (in user's home directory)
+   sudo -u system2mqtt mkdir -p ~system2mqtt/.config/system2mqtt
+   sudo -u system2mqtt cp /opt/system2mqtt/config.yaml.example ~system2mqtt/.config/system2mqtt/config.yaml
+   sudo nano ~system2mqtt/.config/system2mqtt/config.yaml
+   
+   # OR use environment variables in .env
+   sudo nano /opt/system2mqtt/.env
+   sudo chown system2mqtt:system2mqtt /opt/system2mqtt/.env
+   ```
+
+4. **Install systemd service:**
+   ```bash
+   sudo cp system2mqtt.service /etc/systemd/system/
+   sudo systemctl daemon-reload
+   sudo systemctl enable system2mqtt
+   sudo systemctl start system2mqtt
+   ```
+
+5. **Check status:**
+   ```bash
+   sudo systemctl status system2mqtt
+   sudo journalctl -u system2mqtt -f
+   ```
+
+## Service Management
+
+- **Start:** `sudo systemctl start system2mqtt`
+- **Stop:** `sudo systemctl stop system2mqtt`
+- **Restart:** `sudo systemctl restart system2mqtt`
+- **Logs:** `sudo journalctl -u system2mqtt -f`
+- **Enable on boot:** `sudo systemctl enable system2mqtt`
+- **Disable on boot:** `sudo systemctl disable system2mqtt`
+
+## Notes
+
+- Service runs as unprivileged `system2mqtt` user
+- User is member of `adm` and `systemd-journal` groups for system metrics access
+- ZFS (read-only): On many systems, read-only queries like `zpool status` and `zpool list` work without special privileges. If they fail on your host, consider one of these options:
+   - Add the user to a `zfs` group if present (Debian/Ubuntu with `zfsutils-linux` often provide it):
+      ```bash
+      sudo usermod -aG zfs system2mqtt
+      sudo systemctl restart system2mqtt
+      ```
+   - Allow read-only ZFS commands via sudoers without a password:
+      ```bash
+      echo "system2mqtt ALL=(ALL) NOPASSWD: /usr/sbin/zpool, /usr/sbin/zfs" | sudo tee /etc/sudoers.d/system2mqtt
+      sudo visudo -c
+      ```
+   - Use ZFS delegation (if supported in your setup) to grant specific permissions:
+      ```bash
+      sudo zfs allow system2mqtt snapshot,send,receive YOUR_POOL
+      ```
+- `run.sh` automatically creates venv, installs/updates dependencies on each start
+- Auto-restarts on failure (RestartSec=10)
+- Reads environment from `/opt/system2mqtt/.env` if present
+- Logs to systemd journal (view with `journalctl`)