ledgrab/INSTALLATION.md

# Installation Guide

Complete installation guide for the LedGrab server.

## Table of Contents

1. [Docker Installation (recommended)](#docker-installation)
2. [Manual Installation](#manual-installation)
3. [First-Time Setup](#first-time-setup)
4. [Configuration Reference](#configuration-reference)
5. [Troubleshooting](#troubleshooting)

> **Home Assistant integration** has moved to a separate repository:
> [ledgrab-haos-integration](https://git.dolgolyov-family.by/alexei.dolgolyov/ledgrab-haos-integration)

---

## Docker Installation

The fastest way to get running. Requires [Docker](https://docs.docker.com/get-docker/) with Compose.

1. **Clone and start:**

   ```bash
   git clone https://git.dolgolyov-family.by/alexei.dolgolyov/ledgrab.git
   cd ledgrab/server
   docker compose up -d
   ```

2. **Verify:**

   ```bash
   curl http://localhost:8080/health
   # → {"status":"healthy", ...}
   ```

3. **Open the dashboard:** <http://localhost:8080>

4. **View logs:**

   ```bash
   docker compose logs -f
   ```

5. **Stop / restart:**

   ```bash
   docker compose down          # stop
   docker compose up -d         # start again (data is persisted)
   ```

### Docker manual build (without Compose)

```bash
cd server
docker build -t ledgrab .

docker run -d \
  --name ledgrab \
  -p 8080:8080 \
  -v $(pwd)/data:/app/data \
  -v $(pwd)/logs:/app/logs \
  -v $(pwd)/config:/app/config:ro \
  ledgrab
```

### Linux screen capture in Docker

Screen capture from inside a container requires X11 access. Uncomment `network_mode: host` in `docker-compose.yml` and ensure the `DISPLAY` variable is set. Wayland is not currently supported for in-container capture.

---

## Manual Installation

### Requirements

| Dependency | Version | Purpose |
| ---------- | ------- | ------- |
| Python | 3.11+ | Backend server |
| Node.js | 18+ | Frontend build (esbuild) |
| pip | latest | Python package installer |
| npm | latest | Node package manager |

### Steps

1. **Clone the repository:**

   ```bash
   git clone https://git.dolgolyov-family.by/alexei.dolgolyov/ledgrab.git
   cd ledgrab/server
   ```

2. **Build the frontend bundle:**

   ```bash
   npm ci
   npm run build
   ```

   This compiles TypeScript and bundles JS/CSS into `src/ledgrab/static/dist/`.

3. **Create a virtual environment:**

   ```bash
   python -m venv venv

   # Linux / macOS
   source venv/bin/activate

   # Windows (cmd)
   venv\Scripts\activate

   # Windows (PowerShell)
   venv\Scripts\Activate.ps1
   ```

4. **Install Python dependencies:**

   ```bash
   pip install .
   ```

   Optional extras:

   ```bash
   pip install ".[perf]"            # DXCam, BetterCam, WGC (Windows only)
   pip install ".[notifications]"   # OS notification capture
   pip install ".[dev]"             # pytest, black, ruff (development)
   ```

5. **Set PYTHONPATH and start the server:**

   ```bash
   # Linux / macOS
   export PYTHONPATH=$(pwd)/src
   uvicorn ledgrab.main:app --host 0.0.0.0 --port 8080

   # Windows (cmd)
   set PYTHONPATH=%CD%\src
   uvicorn ledgrab.main:app --host 0.0.0.0 --port 8080
   ```

6. **Verify:** open <http://localhost:8080> in your browser.

---

## First-Time Setup

### Change the default API key

The server ships with a development API key (`development-key-change-in-production`). **Change it before exposing the server on your network.**

Option A -- edit the config file:

```yaml
# server/config/default_config.yaml
auth:
  api_keys:
    dev: "your-secure-key-here"   # replace the dev key
```

Option B -- set an environment variable:

```bash
export LEDGRAB_AUTH__API_KEYS__dev="your-secure-key-here"
```

Generate a random key:

```bash
openssl rand -hex 32
```

### Configure CORS for LAN access

By default the server only allows requests from `http://localhost:8080`. To access the dashboard from another machine on your LAN, add its origin:

```yaml
# server/config/default_config.yaml
server:
  cors_origins:
    - "http://localhost:8080"
    - "http://192.168.1.100:8080"   # your server's LAN IP
```

Or via environment variable:

```bash
LEDGRAB_SERVER__CORS_ORIGINS='["http://localhost:8080","http://192.168.1.100:8080"]'
```

### Discover devices

Open the dashboard and go to the **Devices** tab. Click **Discover** to find WLED devices on your network via mDNS. You can also add devices manually by IP address.

---

## Configuration Reference

The server reads configuration from three sources (in order of priority):

1. **Environment variables** -- prefix `LEDGRAB_`, double underscore as nesting delimiter (e.g., `LEDGRAB_SERVER__PORT=9090`)
2. **YAML config file** -- `server/config/default_config.yaml` (or set `LEDGRAB_CONFIG_PATH` to override)
3. **Built-in defaults**

See [`server/.env.example`](server/.env.example) for every available variable with descriptions.

### Key settings

| Variable | Default | Description |
| -------- | ------- | ----------- |
| `LEDGRAB_SERVER__PORT` | `8080` | HTTP listen port |
| `LEDGRAB_SERVER__LOG_LEVEL` | `INFO` | `DEBUG`, `INFO`, `WARNING`, `ERROR` |
| `LEDGRAB_SERVER__CORS_ORIGINS` | `["http://localhost:8080"]` | Allowed CORS origins (JSON array) |
| `LEDGRAB_AUTH__API_KEYS` | `{"dev":"development-key..."}` | API keys (JSON object) |
| `LEDGRAB_STORAGE__DATABASE_FILE` | `data/ledgrab.db` | SQLite database path |
| `LEDGRAB_MQTT__ENABLED` | `false` | Enable MQTT for HA auto-discovery |
| `LEDGRAB_MQTT__BROKER_HOST` | `localhost` | MQTT broker address |
| `LEDGRAB_DEMO` | `false` | Enable demo mode (sandbox with virtual devices) |

---

## Troubleshooting

### Server will not start

**Check Python version:**

```bash
python --version  # must be 3.11+
```

**Check the frontend bundle exists:**

```bash
ls server/src/ledgrab/static/dist/app.bundle.js
```

If missing, run `cd server && npm ci && npm run build`.

**Check logs:**

```bash
# Docker
docker compose logs -f

# Manual install
tail -f logs/ledgrab.log
```

### Cannot access the dashboard from another machine

1. Verify the server is reachable: `curl http://SERVER_IP:8080/health`
2. Check your firewall allows inbound traffic on port 8080.
3. Add your server's LAN IP to `cors_origins` (see [Configure CORS](#configure-cors-for-lan-access) above).

### WLED device not responding

1. Confirm the device is powered on and connected to Wi-Fi.
2. Test it directly: `curl http://DEVICE_IP/json/info`
3. Check that the server and the device are on the same subnet.
4. Try restarting the WLED device.

### Low FPS or high latency

1. Lower the target FPS in the stream settings.
2. Reduce `border_width` to decrease the number of sampled pixels.
3. Check CPU usage on the server (`htop` or Task Manager).
4. On Windows, install the `perf` extra for GPU-accelerated capture: `pip install ".[perf]"`

---

## Next Steps

- [API Documentation](docs/API.md)
- [Calibration Guide](docs/CALIBRATION.md)
- [Repository Issues](https://git.dolgolyov-family.by/alexei.dolgolyov/ledgrab/issues)