# LumaOps

<p align="center"><strong>Local control for the RGB devices you own.</strong></p>
<p align="center"><a href="#interface-tour">Interface tour</a> · <a href="#what-it-does">Capabilities</a> · <a href="#quick-start">Quick start</a> · <a href="#architecture">Architecture</a> · <a href="#deployment-and-hardware">Deployment</a></p>

LumaOps brings supported RGB hardware into one self-hosted web interface. Manage devices, rooms, groups, scenes, schedules, backups and diagnostics from a browser while the application, SQLite database and hardware engine stay on your Linux or Unraid server. No cloud account is required.

> **Release stage:** 0.1.0 is a release candidate. Start with one device and a low-brightness static colour. Some RGB protocols are reverse engineered; direct hardware control carries a bounded hardware risk.

## Interface tour

![LumaOps device inventory populated with synthetic RGB hardware](docs/screenshots/devices-demo.png)

*Devices: inspect the inventory and control options before connecting hardware.*

![LumaOps scenes view populated with synthetic lighting scenes](docs/screenshots/scenes-demo.png)

*Scenes: organise reusable lighting presets for the devices and rooms you control.*

Both images show the actual frontend in test mode with synthetic API responses. They contain no real devices, accounts or operational data; they do not demonstrate hardware compatibility. Some interface labels currently remain in Dutch even when English is selected.

## What it does

| Area | Capability |
| --- | --- |
| Device inventory | Discover supported hardware and organise devices by room or group. |
| Lighting control | Apply colours, scenes and schedules through a responsive local UI. |
| Operations | Inspect diagnostics and audit records; create and restore local backups. |
| Hardware boundary | Map only required USB, HID and I²C devices into a non-privileged container. |

LumaOps embeds **OpenRGB 1.0rc3** as the hardware engine. Its SDK connection stays on `127.0.0.1:6742` inside the container. Native WLED and Home Assistant connectors are not included in 0.1.0.

## Quick start

Requirements: Docker Compose v2, Linux or Unraid x86_64, and the device nodes needed by your actual hardware. Inspect `docker-compose.yml` before starting; remove or replace example `/dev/hidraw0` and `/dev/i2c-0` mappings if your host uses different devices.

```sh
cp .env.example .env
openssl rand -base64 32  # put the result in LUMAOPS_ADMIN_TOKEN in .env
docker compose build
docker compose up -d
```

Open `http://SERVER-IP:1223`, sign in with the token you configured, and complete the setup wizard. Authentication is required because the web interface listens on the LAN by default. Keep `SECURE_COOKIES=false` for direct HTTP on a trusted LAN; set it to `true` behind HTTPS.

## First hardware session

Discover the explicitly mapped device, confirm its identity and select a low-brightness static colour. Verify the result on the physical device before saving a scene or enabling a schedule. Expand to additional devices only after the first controller behaves as expected.

If nothing appears, inspect device-node permissions and OpenRGB detection before changing container privileges. The screenshots use synthetic responses; they are an interface preview, not a compatibility list. Keep port `6742` private and use the authenticated LumaOps interface for remote control.

## Architecture

```mermaid
flowchart LR
    Browser[Browser UI] --> API[LumaOps application]
    API --> DB[(SQLite and app data)]
    API --> SDK[Loopback OpenRGB SDK]
    SDK --> Hardware[Explicitly mapped devices]
```

The container has a read-only root filesystem, only bounded writable data and configuration paths, and no privileged mode. The OpenRGB SDK is **not authenticated or encrypted**: never publish port `6742`. Only map hardware nodes the application needs.

## Deployment and hardware

Persist `appdata/openrgb/`, `appdata/lumaops/`, `data/` and `logs/`, back up the application state, and test restore before relying on schedules. Use an HTTPS reverse proxy for access beyond a trusted LAN. Hardware that requires broadcast, multicast or mDNS can use the documented host-network override:

```sh
docker compose -f docker-compose.yml -f docker/compose.host-network.yml up -d
```

For device permissions, supported controllers and Unraid setup, see [hardware access](docs/HARDWARE_ACCESS.md) and [Unraid deployment](docs/UNRAID_DEPLOYMENT.md). Operational references include [backup and restore](docs/BACKUP_AND_RESTORE.md), [security](docs/SECURITY.md), [troubleshooting](docs/TROUBLESHOOTING.md) and [testing](docs/TESTING.md).

The product application is in `lumaops/`; container integration is in `docker/`; the imported OpenRGB source and changes remain identifiable. LumaOps builds on [OpenRGB](https://openrgb.org) and is distributed under **GPL-2.0-or-later**; see [LICENSE](LICENSE) and [CONTRIBUTING.md](CONTRIBUTING.md).