Complete guide to Lightstack - OpenStack 3 Kubernetes-style
This documentation covers everything from getting started to production deployment, architecture deep-dives, and API compatibility.
Start here if you're new to Lightstack or want to quickly evaluate it.
- README - Project overview and quick links
- QUICKSTART - Get Lightstack running in 5 minutes
- UNIFIED_DEPLOYMENT - Deploy Lightstack + Horizon in one command
- QUICK_REFERENCE - Command cheat sheet
Recommended Path: README → QUICKSTART → UNIFIED_DEPLOYMENT
Choose your deployment strategy based on your use case.
- INSTALLATION - General installation guide (Docker + binary)
- DOCKER_DEPLOYMENT - Docker-specific deployment guide
- MULTIARCH - ARM64 and AMD64 platform support
- SINGLE_NODE_DEPLOYMENT ⭐ NEW
- Single Linux host with real KVM hypervisor
- Full Horizon dashboard with noVNC console
- Perfect for demos showing actual VM creation
- Hardware requirements and setup guide
- 6 demonstration scenarios included
- SCALING ⭐ NEW
- Multi-node production architecture (3-node to 10+ nodes)
- High availability (HAProxy + Keepalived + Patroni)
- Shared storage with Ceph (RBD pools)
- VXLAN multi-node networking
- Load balancing, monitoring, backup, disaster recovery
- Complete production operations guide
- UPGRADING - Upgrade an existing install (incl. nodes installed under the previous product name)
- KUBERNETES_DEPLOYMENT ⭐ NEW
- Manual manifests and Helm chart guide
- ConfigMap, Secret, Deployment, Service, Ingress
- Health checks, scaling, monitoring
- Production considerations
Decision Matrix:
| Use Case | Guide | Features | Hardware |
|---|---|---|---|
| Quick eval | QUICKSTART | Stub mode, no KVM | Laptop (any OS) |
| Development | DOCKER_DEPLOYMENT | Containers, easy setup | 8 GB RAM |
| Demo/POC | SINGLE_NODE_DEPLOYMENT | Real KVM, full features | 16-32 GB RAM (Linux) |
| Production | SCALING | HA, multi-node, Ceph | 8+ nodes |
| Kubernetes | KUBERNETES_DEPLOYMENT | Single binary, all services | K8s cluster |
Lightstack serves the OpenStack APIs Horizon consumes, and the dashboard is usable for resource management — networks, volumes and instances can be created from the UI in stub and real mode (#532, #533). The open UI gaps, starting with the noVNC console, are listed in the report (findings F1–F18).
- Horizon Compatibility Report ⭐ NEW - Browser-level verification: dashboard usable for resource management after #532/#533 (F1–F18)
- HORIZON_FULL_COMPATIBILITY_REPORT - SUPERSEDED (API-endpoint coverage only; see the report above for UI verdicts)
- API endpoint coverage (342/330), microversions, auth flow
- Per-page API dependency matrix
- Performance benchmarks and optimization
- Troubleshooting guide
- HORIZON_INTEGRATION - Integration overview and architecture
- HORIZON_DEPLOYMENT - Deploy Horizon separately to existing Lightstack
- HORIZON_SETUP - Configuration and troubleshooting
Related: See UNIFIED_DEPLOYMENT.md for combined Lightstack + Horizon deployment.
Detailed configuration guides for all Lightstack modes and backends.
- CONFIGURATION - Complete configuration reference
- OPERATIONS - Day-to-day operational tasks
- STORAGE_MODES - Local, Ceph RBD, S3, hybrid storage
- NETWORKING_MODES - Stub, iptables, eBPF networking
- REAL_LIBVIRT_MODE - Real KVM virtualization setup
- REAL_MODE_TESTING - Testing real mode deployments
- S3_CONFIGURATION - AWS S3 and MinIO storage setup
- VXLAN_IMPLEMENTATION - Multi-node VXLAN networking
- L3_ROUTER_IMPLEMENTATION - Router and floating IP details
Understand lightstack's design, implementation, and OpenStack compatibility.
- ARCHITECTURE - System design and component overview
- KEYSTONE_AUTH_FLOW - JWT authentication flow
- BLUEPRINT ⭐ AUTHORITATIVE - Lightstack ↔ OpenStack compatibility blueprint: service map, ~330 functional operations (counting rule stated), per-service matrix, storage backends, sync-architecture trade-offs, Terraform coverage, sci-in-a-box surface, and known gaps. Pinned to OpenStack 2025.2 (Flamingo).
- compatibility/OPENSTACK_COMPATIBILITY_REPORT - Deep per-endpoint analysis + contract-test results (BLUEPRINT's appendix)
- API - Quick-start auth / catalog examples
- API_COVERAGE_REPORT -
⚠️ Superseded: older "104% (342/330)" count; see BLUEPRINT for the reconciled figure - WHATS_LEFT - Optional enterprise features not implemented
- Architecture Decision Records - Formal decisions with context, alternatives, and consequences
Key Stats: Lightstack implements ~330 functional operations across the 5 core OpenStack services (Keystone, Nova, Neutron, Cinder, Glance). See BLUEPRINT for the counting rule and per-service breakdown.
Deep dives into specific features and experimental implementations.
- EBPF_STATUS - eBPF security groups (experimental)
- STUB_PLACEHOLDERS - Stub mode implementation details
Test reports, strategies, and code quality reviews.
- testing/TESTING_SUMMARY - Comprehensive testing summary with lifecycle coverage
- testing/E2E_CI_TESTING_STRATEGY - E2E and CI pipeline strategy
- testing/CONTRACT_TESTS_FINAL - Final results: 95.7% passing (223/233)
- testing/CONTRACT_TEST_RESULTS - Results snapshot: 90.2% (258/286)
- testing/CONTRACT_TESTS_FINAL_REPORT - Detailed execution report
- testing/TEST_FAILURES_ANALYSIS - Root cause analysis of remaining failures
- review/full-repo-review-report - Full codebase review (42 findings, April 2026)
- compatibility/OPENSTACK_COMPATIBILITY_REPORT - OpenStack 2025.2 compatibility analysis
- SPEC-006: v0.7.0 Foundation - Full specification for architecture and quality improvements
- v0.7.0 Implementation Plan - Task-level execution plan with phases and validation gates
- CONTRIBUTING - Development guidelines and contribution process
- TROUBLESHOOTING - Common issues and solutions
For additional help:
- GitHub Issues: https://github.com/cobaltcore-dev/lightstack/issues
- Project discussions: https://github.com/cobaltcore-dev/lightstack/discussions
Analysis of dashboard compatibility and integration options.
- ELEKTRA_INTEGRATION_ANALYSIS ⭐ NEW
- Comprehensive analysis of SAP Elektra dashboard
- Verdict: Not compatible with Lightstack (requires SAP infrastructure)
- Detailed comparison with Horizon
- Recommendation: Continue with Horizon (usable for resource management; open gaps in the compatibility report)
- QUICKSTART - Get Lightstack running
- QUICK_REFERENCE - Try basic commands
- API_COVERAGE_REPORT - Understand capabilities
- INSTALLATION - Understand installation options
- DOCKER_DEPLOYMENT - Set up dev environment
- CONFIGURATION - Configure services
- STORAGE_MODES - Choose storage backend
- NETWORKING_MODES - Configure networking
- ARCHITECTURE - Understand system design
- SINGLE_NODE_DEPLOYMENT - Test on single node first
- SCALING - Deploy multi-node cluster
- OPERATIONS - Learn operational tasks
- TROUBLESHOOTING - Handle common issues
- HORIZON_INTEGRATION - Understand integration
- UNIFIED_DEPLOYMENT - Deploy Lightstack + Horizon together
- HORIZON_DEPLOYMENT - Or deploy Horizon separately
- HORIZON_SETUP - Configure and troubleshoot
- VXLAN_IMPLEMENTATION - Multi-node networking
- L3_ROUTER_IMPLEMENTATION - Routing details
- S3_CONFIGURATION - Object storage backend
- EBPF_STATUS - Experimental features
- CONTRIBUTING - Contribute improvements
Beginner (Start Here):
- QUICKSTART, README, QUICK_REFERENCE, UNIFIED_DEPLOYMENT
Intermediate (Deployment):
- INSTALLATION, DOCKER_DEPLOYMENT, SINGLE_NODE_DEPLOYMENT, HORIZON_DEPLOYMENT, CONFIGURATION
Advanced (Production):
- SCALING, OPERATIONS, VXLAN_IMPLEMENTATION, L3_ROUTER_IMPLEMENTATION, REAL_LIBVIRT_MODE
Expert (Deep Dives):
- ARCHITECTURE, EBPF_STATUS, API, CONTRIBUTING
Deployment:
- QUICKSTART, INSTALLATION, DOCKER_DEPLOYMENT, UNIFIED_DEPLOYMENT, SINGLE_NODE_DEPLOYMENT, SCALING
Dashboard:
- HORIZON_INTEGRATION, HORIZON_DEPLOYMENT, HORIZON_SETUP, ELEKTRA_INTEGRATION_ANALYSIS
Configuration:
- CONFIGURATION, STORAGE_MODES, NETWORKING_MODES, S3_CONFIGURATION, REAL_LIBVIRT_MODE
Networking:
- NETWORKING_MODES, VXLAN_IMPLEMENTATION, L3_ROUTER_IMPLEMENTATION
API & Compatibility:
- API_COVERAGE_REPORT, API, WHATS_LEFT, ARCHITECTURE
Operations & Support:
- OPERATIONS, TROUBLESHOOTING, QUICK_REFERENCE
- KUBERNETES_DEPLOYMENT - Kubernetes deployment with manifests and Helm guide
- v0.6.0 Code Quality Release - 39 commits fixing 32 codebase review findings
- testing/ - Organized test reports directory
- review/ - Codebase review report directory
- ⭐ NEW - Recently added or significantly updated
- 🚀 RECOMMENDED - Start here for most users
- 🔧 TECHNICAL - Requires advanced knowledge
- 🧪 EXPERIMENTAL - Features in development
OpenStack Documentation:
- Horizon: https://docs.openstack.org/horizon/latest/
- Nova: https://docs.openstack.org/nova/latest/
- Neutron: https://docs.openstack.org/neutron/latest/
- Cinder: https://docs.openstack.org/cinder/latest/
- Glance: https://docs.openstack.org/glance/latest/
- Keystone: https://docs.openstack.org/keystone/latest/
lightstack Project:
- GitHub: https://github.com/cobaltcore-dev/lightstack
- License: Apache 2.0
- Current Version: v0.6.0 (Production Ready)
- API Coverage: ~329 functional operations across 5 core services (see BLUEPRINT)
Documentation Issues:
- Missing information? Open an issue: https://github.com/cobaltcore-dev/lightstack/issues/new
- Unclear documentation? Request clarification in discussions
Technical Support:
- Check TROUBLESHOOTING first
- Search existing issues: https://github.com/cobaltcore-dev/lightstack/issues
- Ask in discussions: https://github.com/cobaltcore-dev/lightstack/discussions
Contributing:
- Read CONTRIBUTING
- Submit documentation improvements via pull requests
- Help improve guides based on your deployment experience
Last Updated: April 2026 Total Documentation Files: 40 Coverage: Getting Started, Installation, Configuration, Operations, Architecture, API Reference, Testing, Code Quality