141 lines
5.0 KiB
Markdown
141 lines
5.0 KiB
Markdown
# Deployment
|
|
|
|
This project is designed to run as a user-owned Python app on a small Linux host such as a Raspberry Pi.
|
|
|
|
## Public Repo Policy
|
|
|
|
The public repository tracks a generic deployment script and sanitized example config, but does not track real home-specific values. Keep these in ignored local files under `config/`:
|
|
|
|
- real SSH hostnames, domains, and usernames
|
|
- real remote install paths
|
|
- real room, light, group, and remote names
|
|
- real deCONZ IDs and API keys
|
|
- local deployment settings
|
|
|
|
The sanitized example config is [`config.example/lights_config.py`](../config.example/lights_config.py). A real deployment can use an ignored config such as `config/lights_config.py`.
|
|
|
|
## Target Layout
|
|
|
|
A typical target machine can use this layout:
|
|
|
|
- `<install-dir>/app`: synced application code
|
|
- `<install-dir>/.venv`: virtualenv used by the service
|
|
- `<install-dir>/config/*.py`: runtime light/group/remote definitions
|
|
- `<install-dir>/config/service.env`: runtime environment variables
|
|
- `~/.config/systemd/user/ha-deconz-bridge.service`: user service unit
|
|
- `~/.config/systemd/user/ha-deconz-bridge-debug.service`: optional web debugger service
|
|
|
|
## One Command Deployment
|
|
|
|
Start by copying the example config directory:
|
|
|
|
```bash
|
|
mkdir -p config
|
|
cp config.example/*.py config/
|
|
cp config.example/service.env.example config/service.env
|
|
cp config.example/deploy.env.example config/deploy.env
|
|
```
|
|
|
|
Then edit:
|
|
|
|
- `config/lights_config.py` and the sibling Python files for your real lights, groups, and remotes.
|
|
- `config/service.env` for runtime MQTT/deCONZ values.
|
|
- `config/deploy.env` for the SSH target and remote install path.
|
|
|
|
Deploy or redeploy with:
|
|
|
|
```bash
|
|
python deploy/deploy.py
|
|
```
|
|
|
|
The script copies the app to the target, copies all `.py` files next to the configured `lights_config.py` entry point, copies service environment values, creates or reuses the target virtualenv, installs the package, installs the user systemd units, runs `systemctl --user daemon-reload`, and enables/starts `ha-deconz-bridge.service`.
|
|
|
|
Useful options:
|
|
|
|
```bash
|
|
python deploy/deploy.py --config-only
|
|
python deploy/deploy.py --host pi@raspberrypi.local
|
|
python deploy/deploy.py --remote-dir ~/ha-deconz-bridge
|
|
python deploy/deploy.py --with-speed
|
|
python deploy/deploy.py --no-start
|
|
```
|
|
|
|
`--config-only` copies only config/service env changes and restarts the service. Use it for normal light/config edits after the app is already installed.
|
|
|
|
## Service Units
|
|
|
|
The generic user service templates are tracked in [`deploy/`](../deploy/). They expect:
|
|
|
|
- the deploy script to replace `__INSTALL_DIR__` with the target install path
|
|
- `<install-dir>/config/lights_config.py` and its imported sibling config files to exist
|
|
- `<install-dir>/config/service.env` to exist
|
|
- a virtualenv with the package installed
|
|
|
|
The environment file should not be committed. Use [`config.example/service.env.example`](../config.example/service.env.example) or [`config.example/deploy.env.example`](../config.example/deploy.env.example) as a template.
|
|
|
|
## Manual Deployment Outline
|
|
|
|
1. Copy the repository to the target machine, excluding `.git`, virtualenvs, caches, and local/private files.
|
|
2. Create a virtualenv on the target.
|
|
3. Install the package, optionally with the speed extra:
|
|
|
|
```bash
|
|
python3 -m venv <install-dir>/.venv
|
|
<install-dir>/.venv/bin/pip install --upgrade pip
|
|
<install-dir>/.venv/bin/pip install "<install-dir>/app[speed]"
|
|
```
|
|
|
|
4. Copy a real ignored config directory to `<install-dir>/config/`.
|
|
5. Copy and edit `config.example/service.env.example` to `<install-dir>/config/service.env`.
|
|
6. Install the systemd user units from `deploy/`.
|
|
7. Reload and start the service:
|
|
|
|
```bash
|
|
systemctl --user daemon-reload
|
|
systemctl --user enable --now ha-deconz-bridge.service
|
|
```
|
|
|
|
## Creating A Private Config
|
|
|
|
Start from the public example:
|
|
|
|
```bash
|
|
mkdir -p config
|
|
cp config.example/*.py config/
|
|
cp config.example/service.env.example config/service.env
|
|
cp config.example/deploy.env.example config/deploy.env
|
|
```
|
|
|
|
Edit the copied files for your real devices. The example entry point imports sibling files such as `actions.py`, `groups.py`, and `lights.py`, so the same imports continue to work after copying into `config/`. Then deploy or run with `config/lights_config.py`. Keep that path private and uncommitted.
|
|
|
|
## Required Runtime Values
|
|
|
|
These values must be real for hardware use:
|
|
|
|
- deCONZ API key
|
|
- deCONZ host/port
|
|
- MQTT host/port and credentials if needed
|
|
- physical controller IDs in `lights_config.py`
|
|
|
|
These can be approximate at first:
|
|
|
|
- channel chromaticities
|
|
- per-channel brightness/lumen values
|
|
- exact CT calibration
|
|
|
|
Approximate calibration is enough for integration testing. Exact calibration can come later.
|
|
|
|
## Debugger
|
|
|
|
The web debugger can run on the target machine against the same runtime config:
|
|
|
|
```bash
|
|
cd <install-dir>/app
|
|
set -a
|
|
. ../config/service.env
|
|
set +a
|
|
../.venv/bin/python -m ha_deconz_bridge.debugger.web_debugger ../config/lights_config.py --host 0.0.0.0 --port 8765
|
|
```
|
|
|
|
Open `http://<target-host>:8765` from a browser that can reach the target.
|