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

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:

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:

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

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:

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

Creating A Private Config

Start from the public example:

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:

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.