Iris

A self-hosted WLED holiday lighting system. Maintains a year-round calendar of events, generates progressive lighting schemes, and pushes approved schemes to a WLED controller on a sunrise/sunset schedule.

Full specification: docs/iris-spec.md
Changelog: CHANGELOG.md · Planned work: Forgejo Issues

---

60-second quickstart

Prerequisites: Docker and Docker Compose.

# 1. Clone and configure
git clone https://git.rhoving.com/rbrooks/Iris-WLED.git
cd Iris-WLED
cp .env.example .env

# 2. Edit .env — at minimum set:
#    LATITUDE, LONGITUDE, TZ, and your OIDC credentials
#    (or set DISABLE_AUTH=true for local testing)
$EDITOR .env

# 3. Start
docker compose up -d

# 4. Open http://localhost:7842

The data directory (./data/) is created automatically on first run and mounted as a volume. The SQLite database lives at ./data/iris.db.

Changing the port

Set HOST_PORT in .env to use a different host port:

HOST_PORT=8042

The container always listens on 7842 internally; only the host-side port changes.

---

Configuration

All settings are documented in .env.example. WLED, location, schedule, AI provider, and backup values can be changed from the Settings page after first boot. Key bootstrap variables:

Variable	Default	Description
HOST_PORT	7842	Host port exposed by Docker
WLED_HOST	(none)	Startup default; editable in Settings
LATITUDE / LONGITUDE	(required for solar mode)	Startup default; editable in Settings
TZ	UTC	Startup default; editable in Settings
OIDC_ISSUER_URL	(required)	OIDC provider discovery URL
DISABLE_AUTH	false	Bypass auth for local testing

See .env.example for the full reference.

---

Authentication

Iris uses standard OIDC. Any compliant provider works (Authentik, Keycloak, Google, etc.).
Set the OIDC_* variables in .env. The redirect URI must be registered in your provider:

https://<your-iris-host>/auth/callback

For local development with no IdP available, set DISABLE_AUTH=true. A warning banner will be displayed in the UI.

---

Development

See CONTRIBUTING.md for the full development setup.

Quick start:

# Backend
cd backend && uv sync --group dev
uv run uvicorn app.main:app --reload

# Frontend (separate terminal)
cd frontend && npm install && npm run dev

---

Status

Approaching the v1.0.0 release: the full feature set (events, schemes, WLED integration, scheduler, auth, review UI, AI suggestions, notifications, import/export) is implemented. Remaining release-validation work is tracked in Forgejo Issues under the v1.0.0 label; shipped work is recorded in the CHANGELOG.

Authoritative container images are published to the Forgejo registry at git.rhoving.com/rbrooks/iris-wled for linux/amd64 and linux/arm64.

---

License

MIT