110 lines
3.5 KiB
Markdown
110 lines
3.5 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 intentionally does not track a real deployment script or real home config.
|
|
|
|
Keep these in ignored local files:
|
|
|
|
- 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 scripts
|
|
|
|
The sanitized example config is [`configs/example.py`](../configs/example.py). A real deployment can use an ignored config such as `configs/local/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/lights_config.py`: runtime light 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
|
|
|
|
## Service Units
|
|
|
|
The generic user service templates are tracked in [`deploy/`](../deploy/). They expect:
|
|
|
|
- `HA_DECONZ_BRIDGE_CONFIG` to point at the runtime config file
|
|
- `HA_DECONZ_BRIDGE_SERVICE_ENV` or an equivalent environment file to provide secrets and host-specific settings
|
|
- a virtualenv with the package installed
|
|
|
|
The environment file should not be committed. Use [`deploy/service.env.example`](../deploy/service.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 -e '<install-dir>/app[speed]'
|
|
```
|
|
|
|
4. Copy a real ignored config to `<install-dir>/config/lights_config.py`.
|
|
5. Copy and edit `deploy/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 configs/local
|
|
cp configs/example.py configs/local/lights_config.py
|
|
cp configs/example_*.py configs/local/
|
|
```
|
|
|
|
Edit the copied files for your real devices. If the entry point imports copied split files, make sure the imports point at `configs.local...` modules. For example:
|
|
|
|
```python
|
|
from configs.local.example_lights import LIGHTS
|
|
```
|
|
|
|
Then deploy or run with `configs/local/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.
|