Skip to content

Configuration

Jump to bottom
Griffen Fargo edited this page Jun 9, 2026 · 4 revisions

Configuration

All Lights Pi configuration is managed through environment variables in the .env file.

Environment Variables

Copy the example file to get started:

cp .env.example .env

Required Variables

Variable Description Example
PI_HOST Hostname or IP of your Pi lights.local
PI_USER SSH username pi
WIFI1_SSID Primary WiFi network name MyNetwork
WIFI1_PSK Primary WiFi password secret123

Optional Variables

Variable Description Default
PI_HOSTNAME mDNS hostname set on the Pi lights
QLC_PORT QLC+ web UI port 9999
SSH_KEY Path to SSH private key —
BACKUP_STORAGE Local backup directory ./backups
WIFI2_SSID Secondary WiFi network —
WIFI2_PSK Secondary WiFi password —
AI_PROVIDER AI backend: openai, anthropic, or ollama openai
AI_API_KEY API key for the chosen provider —
AI_MODEL Model name (e.g. gpt-4.1) gpt-4.1
AI_SCENE_STYLE Default scene style complete

MCP Server Variables (Optional)

Used by lighting-mcp.service when the MCP server is installed.

Variable Description Default
MCP_HOST Bind address for the MCP HTTP server 0.0.0.0
MCP_PORT Port the MCP endpoint listens on 5001
MCP_PATH Streamable HTTP mount path /mcp
CONTROL_URL Where the MCP server reaches the Flask control server http://localhost:5000
MCP_BEARER_TOKEN Reserved for bearer-token auth — scaffolded, not yet enforced —
MCP_HTTP_TIMEOUT Seconds for upstream Flask calls 30

Note: Use PI_HOSTNAME, not HOSTNAME — the latter is a macOS shell builtin.

QLC+ Configuration

QLC+ workspaces (.qxw files) define your fixture layout, scenes, and show sequences.

Deploying a Workspace

./lightsctl.sh deploy-workspace my-show.qxw

Pulling the Current Workspace

./lightsctl.sh pull-workspace

Network Configuration

Static IP

For production setups, assign a static IP:

./lightsctl.sh static-ip 192.168.1.100/24 192.168.1.1

Dual WiFi

Configure a backup WiFi network by setting WIFI2_SSID and WIFI2_PSK in your .env file. The Pi will automatically fall back to the secondary network if the primary is unavailable.

Security Hardening

The harden command applies security best practices:

./lightsctl.sh harden

This enables:

  • UFW firewall (allows SSH + QLC+ web UI). Additional ports are opened automatically when control-install and mcp-install run.
  • Hardware watchdog (auto-reboot on hang)
  • Unattended security upgrades
  • USB device permissions for ENTTEC

Branding & Customization

Customize the landing page text, add your own logo, and adjust the control server theme. See Customization for the full guide.

Quick reference:

# Landing page text — set in .env, then:
./lightsctl.sh landing-deploy

# Custom logo — drop into control-server/static/:
cp your-logo.webp control-server/static/logo.webp
bash scripts/deploy.sh

Remote Access (Tailscale)

For accessing your Pi from outside the local network, see Tailscale.

Getting Started

Usage

Advanced

Clone this wiki locally