ha-deconz-bridge/docs/deployment.md

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. 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/. 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 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:

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:

systemctl --user daemon-reload
systemctl --user enable --now ha-deconz-bridge.service

Creating A Private Config

Start from the public example:

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:

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:

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.