111 lines
3.1 KiB
Markdown
111 lines
3.1 KiB
Markdown
# 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.
|