Initial public release

2026-05-30 15:44:40 +00:00
commit cc4e0c2c0f
56 changed files with 11840 additions and 0 deletions
@@ -0,0 +1,109 @@
+# 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.