lacylights-go

module
v0.5.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 14, 2026 License: MIT

README

LacyLights Go Server

A high-performance Go implementation of the LacyLights lighting control system backend. This server provides a GraphQL API for managing theatrical lighting fixtures, scenes, cue lists, and real-time DMX output via Art-Net.

Features

  • GraphQL API: Full-featured API for lighting control operations
  • Art-Net Support: Real-time DMX output over UDP (Art-Net protocol)
  • SQLite Database: Lightweight, embedded database using Prisma-style schema
  • Cross-Platform: Builds for Linux (ARM/AMD64), macOS, and Windows
  • Raspberry Pi Ready: Optimized for deployment on Raspberry Pi hardware

Quick Start

Prerequisites
  • Go 1.25 or later
  • Make (optional, for convenience commands)
Build and Run
# Build the server
make build

# Run with default settings
./build/bin/server

# Run with custom settings
DATABASE_URL="file:./data.db" PORT=4000 ./build/bin/server
Environment Variables
Variable Default Description
PORT 4000 HTTP server port
DATABASE_URL file:./lacylights.db SQLite database path
ARTNET_ENABLED true Enable/disable Art-Net output
ARTNET_BROADCAST_ADDRESS 255.255.255.255 Art-Net broadcast address
EXPORT_MAX_ROWS unset (unlimited) Max data rows in one CSV/XLSX data export (a table, or a workbook's total)
EXPORT_MAX_CELLS unset (unlimited) Max cells in a dynamic-width LOOK_DETAILS grid
EXPORT_MAX_BYTES unset (unlimited) Max file size in bytes of any export (CSV/XLSX data exports and project JSON / Eos ASCII exports), measured before the base64 wrapping in the GraphQL response
EXPORT_MAX_CONCURRENT_PROJECT_EXPORTS unset (built-in 2) How many whole-project (JSON or Eos) exports may run at once
Export limits (opt-in)

Export limits are off by default. LacyLights is mainly used in-house, where large projects must always export quickly, so an unset, 0, negative or non-numeric EXPORT_MAX_ROWS / EXPORT_MAX_CELLS / EXPORT_MAX_BYTES value means "no limit". EXPORT_MAX_CONCURRENT_PROJECT_EXPORTS is a concurrency bound, not a size limit, and is never unlimited: an unset, 0, negative or non-numeric value keeps its built-in default of 2. A set but negative or non-numeric value logs a warning at startup. Only set these for a restricted deployment such as a public demo. Suggested demo values:

EXPORT_MAX_ROWS=100000        # 100k rows
EXPORT_MAX_CELLS=5000000      # 5M cells
EXPORT_MAX_BYTES=20971520     # 20 MiB file size; the base64 GraphQL response is ~1/3 larger
EXPORT_MAX_CONCURRENT_PROJECT_EXPORTS=1

An export over a configured limit fails with a GraphQL error such as export is too large: LOOKS has about 150000 rows, over this server's export limit of 100000 rows or export file is too large: project JSON export is 25000000 bytes, over this server's export limit of 20971520 bytes. EXPORT_MAX_BYTES takes a plain byte count (no MB suffix).

For whole-project JSON and Eos ASCII exports only EXPORT_MAX_BYTES applies (EXPORT_MAX_ROWS and EXPORT_MAX_CELLS cover CSV/XLSX data exports), and it is checked after the export is built: it limits what the server returns, not its peak memory use. EXPORT_MAX_CONCURRENT_PROJECT_EXPORTS is what bounds the memory those exports can use at once. The startup banner prints the active limits (Export caps: none (unlimited) by default).

Development

Project Structure
lacylights-go/
├── cmd/server/          # Main application entry point
├── internal/
│   ├── config/          # Configuration management
│   ├── database/        # Database layer and migrations
│   ├── graph/           # GraphQL resolvers and schema
│   ├── models/          # Domain models
│   └── artnet/          # Art-Net protocol implementation
├── pkg/                 # Public packages
├── test/                # Integration tests
├── go.mod
├── go.sum
└── Makefile
Common Commands
# Run tests
make test

# Run tests with coverage
make test-coverage

# Run linter
make lint

# Generate GraphQL code
make generate

# Build for all platforms
make build-all

# Clean build artifacts
make clean
GraphQL Schema

The GraphQL API is defined in internal/graph/schema.graphqls. After modifying the schema, regenerate the resolver code:

make generate

API Overview

Queries
  • projects - List all projects
  • project(id: ID!) - Get a specific project
  • fixtureDefinitions - List fixture definitions
  • systemInfo - Get system status and configuration
  • dmxOutput(universe: Int!) - Get current DMX channel values
Mutations
  • createProject / updateProject / deleteProject - Project management
  • createScene / updateScene / deleteScene - Scene management
  • createCueList / addCueToCueList - Cue list management
  • startCueList / nextCue / stopCueList - Playback control
  • setChannelValue - Direct DMX control
  • fadeToBlack - Emergency blackout
Subscriptions
  • dmxOutput - Real-time DMX value updates
  • playbackStatus - Cue list playback state changes

Building for Raspberry Pi

# Build for Raspberry Pi (ARM64)
GOOS=linux GOARCH=arm64 go build -o lacylights-arm64 ./cmd/server

# Build for older Raspberry Pi (ARM32)
GOOS=linux GOARCH=arm GOARM=7 go build -o lacylights-arm ./cmd/server

Testing

Run unit tests:

make test

Run with coverage report:

make test-coverage
open coverage.html

Project Documentation

For comprehensive implementation plans and architecture decisions, see the parent directory documentation:

License

MIT License - See LICENSE for details.

Directories

Path Synopsis
cmd
migrate-layout command
Package main provides a one-time migration tool to convert fixture layout coordinates from normalized 0-1 values to pixel-based coordinates.
Package main provides a one-time migration tool to convert fixture layout coordinates from normalized 0-1 values to pixel-based coordinates.
server command
Package main is the entry point for the LacyLights Go server.
Package main is the entry point for the LacyLights Go server.
internal
auth
Package auth provides authentication services for LacyLights.
Package auth provides authentication services for LacyLights.
auth/session
Package session provides session management for authentication.
Package session provides session management for authentication.
config
Package config provides configuration management for the LacyLights server.
Package config provides configuration management for the LacyLights server.
database
Package database provides database connection and management.
Package database provides database connection and management.
database/migrations
Package migrations contains one-shot, idempotent schema migrations invoked from the server's startup AutoMigrate flow.
Package migrations contains one-shot, idempotent schema migrations invoked from the server's startup AutoMigrate flow.
database/models
Package models contains the database model definitions.
Package models contains the database model definitions.
database/repositories
Package repositories provides data access layer implementations.
Package repositories provides data access layer implementations.
graphql/resolvers
Package resolvers contains GraphQL resolver implementations.
Package resolvers contains GraphQL resolver implementations.
middleware
Package middleware provides HTTP middleware for the LacyLights server.
Package middleware provides HTTP middleware for the LacyLights server.
services/dmx
Package dmx provides DMX output management and Art-Net communication.
Package dmx provides DMX output management and Art-Net communication.
services/export
Package export provides project export functionality.
Package export provides project export functionality.
services/export_eos
Package exporteos writes LacyLights project state to ETC Eos ASCII format.
Package exporteos writes LacyLights project state to ETC Eos ASCII format.
services/export_tables
Package exporttables turns LacyLights data lists (fixtures, looks, cue lists, ...) into spreadsheet-friendly tables and encodes them as CSV or XLSX files.
Package exporttables turns LacyLights data lists (fixtures, looks, cue lists, ...) into spreadsheet-friendly tables and encodes them as CSV or XLSX files.
services/fade
Package fade provides fade engine functionality for smooth DMX transitions.
Package fade provides fade engine functionality for smooth DMX transitions.
services/import
Package importservice provides project import functionality.
Package importservice provides project import functionality.
services/import_eos
Package importeos parses ETC Eos ASCII showfiles into LacyLights domain objects.
Package importeos parses ETC Eos ASCII showfiles into LacyLights domain objects.
services/modulator
Package modulator provides a unified modulation engine for DMX channel control.
Package modulator provides a unified modulation engine for DMX channel control.
services/network
Package network provides utilities for network interface enumeration
Package network provides utilities for network interface enumeration
services/ofl
Package ofl provides OFL (Open Fixture Library) import functionality
Package ofl provides OFL (Open Fixture Library) import functionality
services/playback
Package playback provides cue list playback functionality.
Package playback provides cue list playback functionality.
services/preview
Package preview provides preview session management.
Package preview provides preview session management.
services/pubsub
Package pubsub provides a simple publish-subscribe mechanism for GraphQL subscriptions.
Package pubsub provides a simple publish-subscribe mechanism for GraphQL subscriptions.
services/testutil
Package testutil provides shared test utilities for integration tests.
Package testutil provides shared test utilities for integration tests.
services/undo
Package undo provides undo/redo functionality for LacyLights operations.
Package undo provides undo/redo functionality for LacyLights operations.
services/version
Package version provides version management functionality for LacyLights.
Package version provides version management functionality for LacyLights.
services/wifi
Package wifi provides WiFi management and AP mode capabilities for LacyLights.
Package wifi provides WiFi management and AP mode capabilities for LacyLights.
pkg
artnet
Package artnet provides Art-Net protocol packet building and transmission.
Package artnet provides Art-Net protocol packet building and transmission.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL