75 lines
4.9 KiB
Markdown
75 lines
4.9 KiB
Markdown
# 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
|
|
|
|
|
|
|
|
*Devices: inspect the inventory and control options before connecting hardware.*
|
|
|
|
|
|
|
|
*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).
|