ledgrab/INSTALLATION.md

Installation Guide

Complete installation guide for the LedGrab server.

Table of Contents

1. Docker Installation (recommended)
2. Manual Installation
3. First-Time Setup
4. Configuration Reference
5. Troubleshooting

Home Assistant integration has moved to a separate repository: ledgrab-haos-integration

---

Docker Installation

The fastest way to get running. Requires Docker with Compose.

1. Clone and start:

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

2. Verify:

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

3. Open the dashboard: http://localhost:8080

4. View logs:

   docker compose logs -f
   

5. Stop / restart:

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

Docker manual build (without Compose)

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:

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

2. Build the frontend bundle:

   npm ci
   npm run build
   

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

3. Create a virtual environment:

   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:

   pip install .
   

   Optional extras:

   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:

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

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

Option B -- set an environment variable:

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

Generate a random key:

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:

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

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

python --version  # must be 3.11+

Check the frontend bundle exists:

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

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

Check logs:

# 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 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
• Calibration Guide
• Repository Issues