first commit

2026-08-23 21:34:07 +02:00
commit 1d3dcba1a9
62 changed files with 12456 additions and 0 deletions
@@ -0,0 +1,110 @@
+# LXC installation and update
+
+This document describes the supported Debian/Ubuntu systemd deployment used for LXC testing.
+
+## First installation
+
+Unpack the source archive inside the container and run:
+
+```bash
+cd gree-controller
+chmod +x scripts/*.sh
+sudo ./scripts/install.sh
+```
+
+The installer:
+
+1. installs required build packages when missing,
+2. installs stable Rust with rustup when Cargo is unavailable,
+3. runs `cargo test --all-targets`,
+4. builds `target/release/gree-controller`,
+5. creates the `gree-controller` system user/group,
+6. creates `/var/lib/gree-controller`, `/opt/gree-controller` and `/var/backups/gree-controller`,
+7. installs the systemd unit,
+8. creates `/etc/gree-controller.env` only when it does not already exist,
+9. enables/restarts the service,
+10. verifies `GET /api/health`.
+
+Installed state is intentionally outside the extracted source directory:
+
+```text
+/opt/gree-controller/gree-controller       installed binary
+/etc/gree-controller.env                   persistent configuration/secrets
+/var/lib/gree-controller/gree-controller.db persistent SQLite database
+/var/backups/gree-controller/              update backups
+/etc/systemd/system/gree-controller.service systemd service
+```
+
+The default installation starts in simulator mode. Change `GREE_CONTROLLER_SIMULATE=false` and `GREE_CONTROLLER_AUTO_SEED=false` in `/etc/gree-controller.env` when moving to physical units, then restart the service.
+
+## Update
+
+Unpack a newer source archive and run from that new directory:
+
+```bash
+sudo ./scripts/update.sh
+```
+
+The update workflow is designed to minimize downtime and preserve the database:
+
+1. build dependencies/Rust are checked,
+2. tests run while the currently installed controller stays online,
+3. the new release binary is built while the old service stays online,
+4. the service is stopped,
+5. the installed binary, service unit, environment file and SQLite database are copied to `/var/backups/gree-controller/<UTC timestamp>/`,
+6. the new binary/unit is installed,
+7. systemd starts the new version,
+8. `/api/health` is checked,
+9. on failure the old binary, unit and database are restored automatically.
+
+The updater does not overwrite `/etc/gree-controller.env` during a successful update.
+
+Use `--skip-tests` only for deliberate fast testing:
+
+```bash
+sudo ./scripts/update.sh --skip-tests
+```
+
+## Service helper
+
+```bash
+./scripts/service.sh status
+./scripts/service.sh health
+./scripts/service.sh logs
+sudo ./scripts/service.sh restart
+sudo ./scripts/service.sh stop
+sudo ./scripts/service.sh start
+```
+
+Equivalent native commands remain available:
+
+```bash
+systemctl status gree-controller
+journalctl -u gree-controller -f
+```
+
+## Configuration
+
+Edit:
+
+```text
+/etc/gree-controller.env
+```
+
+and restart:
+
+```bash
+sudo ./scripts/service.sh restart
+```
+
+Do not store controller or Home Assistant secrets in the source tree.
+
+## Database and SQL layout
+
+Runtime persistence uses SQLite. All schema definitions and SQL statements in the Rust application are centralized in:
+
+```text
+src/queries.rs
+```
+
+`src/db.rs` contains connection/transaction logic and maps database rows to Rust domain models, but it does not embed SQL statements.