# 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`](../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:

```bash
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:

```bash
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:

```bash
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/`](../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`](../config.example/service.env.example) or [`config.example/deploy.env.example`](../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:

```bash
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:

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

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