Skip to content

Latest commit

 

History

History
515 lines (379 loc) · 10.1 KB

INSTALLATION.md

File metadata and controls

515 lines (379 loc) · 10.1 KB

Installation Guide

📚 Complete Documentation: See INDEX.md for full documentation index with learning paths.

Complete installation guide for Lightstack (OpenStack-compatible cloud platform).


Table of Contents


Prerequisites

System Requirements

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)

Required Software

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)

Installation Methods

Docker Compose (Recommended)

Docker Compose provides the easiest way to get Lightstack running with all dependencies.

Step 1: Clone Repository

git clone https://github.com/cobaltcore-dev/lightstack.git
cd lightstack

Step 2: Start Services

docker compose up -d

This starts:

  • PostgreSQL on port 5432
  • lightstack APIs on ports 5001, 8774, 9696, 8776, 9292, 8775

Step 3: Wait for Services

# Check status
docker compose ps

# Wait for healthy status
docker compose logs -f lightstack

First startup takes 30-60 seconds as migrations run automatically.

Step 4: Configure CLI Environment

# 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

Step 5: Install OpenStack CLI

# Using pipx (recommended)
brew install pipx  # macOS
# or: apt install pipx  # Ubuntu/Debian

pipx install python-openstackclient

✅ Installation Complete! Jump to Verification.


Binary Installation

For advanced users who want to run Lightstack directly without Docker.

Step 1: Install PostgreSQL

Ubuntu/Debian:

sudo apt update
sudo apt install postgresql-14 postgresql-client-14
sudo systemctl start postgresql
sudo systemctl enable postgresql

macOS:

brew install postgresql@14
brew services start postgresql@14

Step 2: Create Database

sudo -u postgres psql << EOF
CREATE DATABASE lightstack;
CREATE USER lightstack WITH PASSWORD 'secret';
GRANT ALL PRIVILEGES ON DATABASE lightstack TO lightstack;
EOF

Step 3: Build Lightstack

git 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/

Step 4: Configure Lightstack

# Create config directory
sudo mkdir -p /etc/lightstack

# Copy config
sudo cp config/lightstack.yaml /etc/lightstack/

# Edit config
sudo nano /etc/lightstack/lightstack.yaml

Update database URL:

database:
  url: "postgres://lightstack:secret@localhost/lightstack?sslmode=disable"

Step 5: Run Migrations

lightstack-migrate up

Step 6: Start Lightstack

# Run in foreground
lightstack --config /etc/lightstack/lightstack.yaml

# Or create systemd service (see docs/OPERATIONS.md)

✅ Installation Complete! Jump to Verification.


First Run

Default Credentials

Domain:   Default
Username: admin
Password: secret
Project:  default

⚠️ Change these in production!

Environment Setup

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=3

Save to ~/.lightstack-env and source it:

source ~/.lightstack-env

Verification

1. Check Services

Docker Compose:

docker compose ps

# Should show:
# lightstack            Up (healthy)
# lightstack-postgres   Up (healthy)

Binary:

curl http://localhost:35357/v3
# Should return JSON with version info

2. Test Authentication

source ~/.lightstack-env
openstack token issue

Expected output:

+------------+------------------+
| Field      | Value            |
+------------+------------------+
| expires    | 2026-03-08...    |
| id         | eyJhbGc...       |
| project_id | 00000000-...     |
| user_id    | 00000000-...     |
+------------+------------------+

3. List Resources

# List flavors
openstack flavor list

# List networks
openstack network list

# Show quotas
openstack quota show --compute

4. Create Test VM

# 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!


Troubleshooting

Issue: Authentication Fails (401)

Symptoms:

invalid credentials (HTTP 401)

Solutions:

  1. Check credentials match defaults (Domain: "Default" with capital D)
  2. Verify Lightstack is running: docker compose ps or curl http://localhost:35357/v3
  3. Check database has domain:
    docker exec lightstack-postgres psql -U lightstack -d lightstack \
      -c "SELECT * FROM domains;"

Issue: Port Already in Use

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.yml

Issue: Database Connection Failed

Symptoms:

failed to connect to postgres

Solutions:

  1. Verify PostgreSQL is running:

    docker compose ps postgres
    # or: sudo systemctl status postgresql
  2. Check database exists:

    docker exec lightstack-postgres psql -U lightstack -l
  3. Test connection:

    psql "postgres://lightstack:secret@localhost/lightstack?sslmode=disable"

Issue: Migrations Failed

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 up

Issue: Service Not Healthy

Symptoms:

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 syntax

Issue: OpenStack CLI Not Found

Symptoms:

command not found: openstack

Solutions:

# Install with pipx
pipx install python-openstackclient

# Or with pip
pip install python-openstackclient

# Verify
openstack --version

Getting Help

  1. Check logs:

    docker compose logs lightstack
  2. Check database:

    docker exec lightstack-postgres psql -U lightstack -d lightstack
  3. Test APIs directly:

    curl http://localhost:5001/v3
    curl http://localhost:8774/v2.1/
  4. GitHub Issues: Report bugs at repository issues page


Next Steps

Learn the Basics

Configure Your Installation

Advanced Topics

Production Deployment

See docs/OPERATIONS.md for:

  • Systemd service setup
  • Monitoring and logging
  • Backup strategies
  • Security hardening
  • High availability

Quick Reference

Common Commands

# 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

Default Ports

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

Support

  • Documentation: /docs directory
  • Examples: docs/OPERATIONS.md
  • Issues: GitHub Issues
  • Community: GitHub Discussions

Congratulations! Lightstack is now installed and ready to use! 🚀