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