📚 Complete Documentation: See INDEX.md for full documentation index with learning paths.
Complete installation guide for Lightstack (OpenStack-compatible cloud platform).
Minimum:
- CPU: 2 cores
- RAM: 4GB
- Disk: 10GB free space
- OS: Linux (Ubuntu 20.04+, Debian 11+, RHEL 8+)
Recommended:
- CPU: 4+ cores
- RAM: 8GB+
- Disk: 50GB+ free space
- OS: Ubuntu 22.04 LTS or macOS (ARM64/AMD64)
For Docker Compose Installation:
- Docker 20.10+ (install guide)
- Docker Compose V2 (included with Docker Desktop)
For Binary Installation:
- PostgreSQL 18+ (install guide)
- Go 1.26+ (for building from source)
Docker Compose provides the easiest way to get Lightstack running with all dependencies.
git clone https://github.com/cobaltcore-dev/lightstack.git
cd lightstackdocker compose up -dThis starts:
- PostgreSQL on port 5432
- lightstack APIs on ports 5001, 8774, 9696, 8776, 9292, 8775
# Check status
docker compose ps
# Wait for healthy status
docker compose logs -f lightstackFirst startup takes 30-60 seconds as migrations run automatically.
# Create environment file
cat > ~/.lightstack-env << 'EOF'
export OS_AUTH_URL=http://localhost:5001/v3
export OS_PROJECT_NAME=default
export OS_PROJECT_DOMAIN_NAME=Default
export OS_USERNAME=admin
export OS_PASSWORD=secret
export OS_USER_DOMAIN_NAME=Default
export OS_IDENTITY_API_VERSION=3
EOF
# Load environment
source ~/.lightstack-env# Using pipx (recommended)
brew install pipx # macOS
# or: apt install pipx # Ubuntu/Debian
pipx install python-openstackclient✅ Installation Complete! Jump to Verification.
For advanced users who want to run Lightstack directly without Docker.
Ubuntu/Debian:
sudo apt update
sudo apt install postgresql-14 postgresql-client-14
sudo systemctl start postgresql
sudo systemctl enable postgresqlmacOS:
brew install postgresql@14
brew services start postgresql@14sudo -u postgres psql << EOF
CREATE DATABASE lightstack;
CREATE USER lightstack WITH PASSWORD 'secret';
GRANT ALL PRIVILEGES ON DATABASE lightstack TO lightstack;
EOFgit clone https://github.com/cobaltcore-dev/lightstack.git
cd lightstack
# Build
go build -o lightstack ./cmd/lightstack
go build -o lightstack-migrate ./cmd/lightstack-migrate
# Move binaries
sudo mv lightstack /usr/local/bin/
sudo mv lightstack-migrate /usr/local/bin/# Create config directory
sudo mkdir -p /etc/lightstack
# Copy config
sudo cp config/lightstack.yaml /etc/lightstack/
# Edit config
sudo nano /etc/lightstack/lightstack.yamlUpdate database URL:
database:
url: "postgres://lightstack:secret@localhost/lightstack?sslmode=disable"lightstack-migrate up# Run in foreground
lightstack --config /etc/lightstack/lightstack.yaml
# Or create systemd service (see docs/OPERATIONS.md)✅ Installation Complete! Jump to Verification.
Domain: Default
Username: admin
Password: secret
Project: default
All OpenStack CLI commands need these environment variables:
export OS_AUTH_URL=http://localhost:5001/v3 # or :35357 for binary
export OS_PROJECT_NAME=default
export OS_PROJECT_DOMAIN_NAME=Default
export OS_USERNAME=admin
export OS_PASSWORD=secret
export OS_USER_DOMAIN_NAME=Default
export OS_IDENTITY_API_VERSION=3Save to ~/.lightstack-env and source it:
source ~/.lightstack-envDocker Compose:
docker compose ps
# Should show:
# lightstack Up (healthy)
# lightstack-postgres Up (healthy)Binary:
curl http://localhost:35357/v3
# Should return JSON with version infosource ~/.lightstack-env
openstack token issueExpected output:
+------------+------------------+
| Field | Value |
+------------+------------------+
| expires | 2026-03-08... |
| id | eyJhbGc... |
| project_id | 00000000-... |
| user_id | 00000000-... |
+------------+------------------+
# List flavors
openstack flavor list
# List networks
openstack network list
# Show quotas
openstack quota show --compute# Create network
openstack network create test-net
# Create VM
openstack server create \
--flavor m1.small \
--image cirros \
--network test-net \
test-vm
# Verify
openstack server list✅ If all commands succeed, Lightstack is working correctly!
Symptoms:
invalid credentials (HTTP 401)
Solutions:
- Check credentials match defaults (Domain: "Default" with capital D)
- Verify Lightstack is running:
docker compose psorcurl http://localhost:35357/v3 - Check database has domain:
docker exec lightstack-postgres psql -U lightstack -d lightstack \ -c "SELECT * FROM domains;"
Symptoms:
Bind for 0.0.0.0:5001 failed: port is already allocated
Solutions:
# Find what's using the port
lsof -i:5001
# Kill the process or change port in docker-compose.ymlSymptoms:
failed to connect to postgres
Solutions:
-
Verify PostgreSQL is running:
docker compose ps postgres # or: sudo systemctl status postgresql -
Check database exists:
docker exec lightstack-postgres psql -U lightstack -l -
Test connection:
psql "postgres://lightstack:secret@localhost/lightstack?sslmode=disable"
Symptoms:
migration failed: relation "users" does not exist
Solutions:
# Check migration status
docker exec lightstack /app/lightstack-migrate status
# Run migrations manually
docker exec lightstack /app/lightstack-migrate up
# Reset and rerun (⚠️ deletes all data)
docker exec lightstack /app/lightstack-migrate reset
docker exec lightstack /app/lightstack-migrate upSymptoms:
lightstack Up 2 minutes (unhealthy)
Solutions:
# Check logs
docker compose logs lightstack --tail=50
# Common issues:
# - Database not ready: wait 10 more seconds
# - Port conflict: check lsof output
# - Config error: check lightstack.yaml syntaxSymptoms:
command not found: openstack
Solutions:
# Install with pipx
pipx install python-openstackclient
# Or with pip
pip install python-openstackclient
# Verify
openstack --version-
Check logs:
docker compose logs lightstack
-
Check database:
docker exec lightstack-postgres psql -U lightstack -d lightstack -
Test APIs directly:
curl http://localhost:5001/v3 curl http://localhost:8774/v2.1/
-
GitHub Issues: Report bugs at repository issues page
- Quickstart Guide - Create your first VM in 5 minutes
- Operations Guide - Day-to-day management tasks
- Configuration Guide - Networking, storage, security
- Docker Deployment - Docker-specific configuration
- Multi-Architecture - Building for ARM/AMD64
- Architecture - System design and components
- API Reference - OpenStack API compatibility
See docs/OPERATIONS.md for:
- Systemd service setup
- Monitoring and logging
- Backup strategies
- Security hardening
- High availability
# Docker Compose
docker compose up -d # Start services
docker compose down # Stop services
docker compose ps # Check status
docker compose logs -f lightstack # View logs
# OpenStack CLI
source ~/.lightstack-env # Load environment
openstack server list # List VMs
openstack network list # List networks
openstack volume list # List volumes
openstack quota show # Show quotas
# Database
docker exec lightstack-postgres psql -U lightstack -d lightstack # Connect
docker exec lightstack /app/lightstack-migrate status # Migration status| Service | Port | Description |
|---|---|---|
| Keystone | 5001 | Identity/Auth (Docker) |
| Keystone | 35357 | Identity/Auth (Binary) |
| Nova | 8774 | Compute |
| Neutron | 9696 | Network |
| Cinder | 8776 | Block Storage |
| Glance | 9292 | Images |
| Metadata | 8775 | VM Metadata |
| PostgreSQL | 5432 | Database |
- Documentation:
/docsdirectory - Examples:
docs/OPERATIONS.md - Issues: GitHub Issues
- Community: GitHub Discussions
Congratulations! Lightstack is now installed and ready to use! 🚀