Restructure public config and deployment

README.md

@@ -15,53 +15,116 @@ New code lives under [`src/ha_deconz_bridge`](./src/ha_deconz_bridge/). Local/pr
 
 This started as a personal hobby project, was put on ice for a while after motivation ran out, and was later picked up again as a clean rewrite with substantial help from AI. The current public codebase is the rewritten version; old experiments are kept out of the repository history.
 
-## Project Layout
+## What You Need
 
-- [`docs/semantics.md`](./docs/semantics.md): runtime behavior and mapping rules
-- [`docs/architecture.md`](./docs/architecture.md): package structure and data flow
-- [`docs/configuration.md`](./docs/configuration.md): typed light definitions
-- [`docs/deployment.md`](./docs/deployment.md): Raspberry Pi deploy and service flow
-- [`docs/debugger.md`](./docs/debugger.md): shared-core simulator
-- [`docs/plan.md`](./docs/plan.md): implementation plan that drove this reboot
+- Python 3.11 or newer.
+- Home Assistant with MQTT discovery enabled.
+- deCONZ/Phoscon already controlling the physical lights.
+- SSH access to the Raspberry Pi or other Linux host if you want to deploy it as a service.
 
-## Quick Start
+## Configuration Files
 
-Install in editable mode:
+The project is meant to be self-contained. Public example files live in [`config.example/`](./config.example/), and your real private files live in ignored `config/`.
+
+Create your private config:
 
 ```bash
-python3 -m pip install -e '.[dev]'
+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
 ```
 
-Run the test suite:
+Then edit:
+
+- `config/lights_config.py`: loads the other config files.
+- `config/lights.py`: virtual lights and physical controller/channel definitions.
+- `config/groups.py`: room/group definitions.
+- `config/remotes.py` and `config/actions.py`: optional remote button automation.
+- `config/service.env`: MQTT and deCONZ connection settings.
+- `config/deploy.env`: SSH target and deploy settings for the Pi.
+
+Files under `config/` are ignored by Git.
+
+## Run Locally
+
+This runs the bridge on the current machine. It is useful for testing the config or running the web debugger before deploying to a Pi.
+
+1. Create a Python environment:
 
 ```bash
-pytest
+python3 -m venv .venv
 ```
 
-Create a private config from the public example:
+2. Install the program into that environment:
 
 ```bash
-mkdir -p configs/local
-cp configs/example.py configs/local/lights_config.py
-cp configs/example_*.py configs/local/
+.venv/bin/pip install .
 ```
 
-Edit `configs/local/lights_config.py` and the copied split files for your real controller IDs, light names, groups, and calibration values. Files under `configs/local/` are ignored by Git.
-
-Run the service with a Python config path that exports `SETTINGS` and `LIGHTS`:
+3. Load the connection settings and run the service:
 
 ```bash
-ha-deconz-bridge-service configs/local/lights_config.py
+set -a
+. config/service.env
+set +a
+.venv/bin/ha-deconz-bridge-service config/lights_config.py
 ```
 
-Run the browser debugger against the same config:
+4. In another terminal, run the browser debugger if you want to inspect solver behavior:
 
 ```bash
-ha-deconz-bridge-debug-web configs/local/lights_config.py "Example Mixed North" --host 127.0.0.1 --port 8765
+set -a
+. config/service.env
+set +a
+.venv/bin/ha-deconz-bridge-debug-web config/lights_config.py "Living Room Ceiling" --host 127.0.0.1 --port 8765
 ```
 
-## Configuration And Deployment
+Then open `http://127.0.0.1:8765`.
 
-The public repository includes sanitized example configs under [`configs/example.py`](./configs/example.py). Keep real room names, controller IDs, hostnames, user names, and deployment scripts in ignored local files such as `configs/local/`.
+On Windows, use `.venv\Scripts\pip` and `.venv\Scripts\ha-deconz-bridge-service` instead of the `.venv/bin/...` paths.
 
-See [`docs/deployment.md`](./docs/deployment.md) for the generic service layout and deployment expectations.
+## Deploy To A Pi
+
+This is the normal always-on setup. The deploy script copies the app and config to the target, creates or updates a virtualenv there, installs the package, installs systemd user services, and starts the bridge.
+
+1. Make sure `config/deploy.env` contains your SSH target:
+
+```bash
+DEPLOY_HOST=pi@raspberrypi.local
+DEPLOY_REMOTE_DIR=~/ha-deconz-bridge
+```
+
+2. Deploy:
+
+```bash
+python deploy/deploy.py
+```
+
+3. For later config-only changes, redeploy just the config:
+
+```bash
+python deploy/deploy.py --config-only
+```
+
+4. Check the service on the Pi:
+
+```bash
+ssh pi@raspberrypi.local 'systemctl --user status ha-deconz-bridge.service --no-pager'
+```
+
+The optional web debugger service can be started on the Pi with:
+
+```bash
+ssh pi@raspberrypi.local 'systemctl --user start ha-deconz-bridge-debug.service'
+```
+
+It listens on port `8766` by default.
+
+## More Documentation
+
+- [`docs/configuration.md`](./docs/configuration.md): config format and examples.
+- [`docs/deployment.md`](./docs/deployment.md): deployment details and service layout.
+- [`docs/debugger.md`](./docs/debugger.md): web debugger behavior.
+- [`docs/semantics.md`](./docs/semantics.md): solver and Home Assistant behavior.
+- [`docs/architecture.md`](./docs/architecture.md): package structure and data flow.