📚 Complete Documentation: See INDEX.md for full documentation index with learning paths.
Get Lightstack running and create your first VM in 5 minutes.
- Docker and Docker Compose V2 installed
- 4GB+ RAM available
- Basic familiarity with terminal/CLI
cd /path/to/lightstack
docker compose up -dExpected output:
[+] Running 2/2
✔ Container lightstack-postgres Started
✔ Container lightstack Started
Wait for services to be healthy (~30 seconds):
docker compose psShould show:
NAME STATUS
lightstack Up (healthy)
lightstack-postgres Up (healthy)
# macOS
brew install pipx
pipx install python-openstackclient
# Ubuntu/Debian
apt install pipx
pipx install python-openstackclient
# Verify
openstack --version# 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 it
source ~/.lightstack-env# Test authentication
openstack token issueExpected output:
+------------+------------------+
| Field | Value |
+------------+------------------+
| expires | 2026-03-08... |
| id | eyJhbGc... |
| project_id | 00000000-... |
| user_id | 00000000-... |
+------------+------------------+
# List available flavors
openstack flavor listExpected output:
+--------------------------------------+-----------+-------+------+-----------+-------+
| ID | Name | RAM | Disk | Ephemeral | VCPUs |
+--------------------------------------+-----------+-------+------+-----------+-------+
| 00000000-0000-0000-0000-000000000010 | m1.tiny | 512 | 1 | 0 | 1 |
| 00000000-0000-0000-0000-000000000011 | m1.small | 2048 | 20 | 0 | 1 |
| 00000000-0000-0000-0000-000000000012 | m1.medium | 4096 | 40 | 0 | 2 |
| 00000000-0000-0000-0000-000000000013 | m1.large | 8192 | 80 | 0 | 4 |
| 00000000-0000-0000-0000-000000000014 | m1.xlarge | 16384 | 160 | 0 | 8 |
+--------------------------------------+-----------+-------+------+-----------+-------+
# Create a private network
openstack network create my-network
# Create a subnet
openstack subnet create \
--network my-network \
--subnet-range 192.168.1.0/24 \
my-subnet
# Verify
openstack network listLightstack ships with no images, so upload the tiny CirrOS test image before booting a VM.
# Download CirrOS (~20 MB cloud test image)
curl -L -o /tmp/cirros-0.6.2-x86_64-disk.img \
https://download.cirros-cloud.net/0.6.2/cirros-0.6.2-x86_64-disk.img
# Upload it to Glance
openstack image create \
--disk-format qcow2 \
--container-format bare \
--public \
--file /tmp/cirros-0.6.2-x86_64-disk.img \
cirros
# Verify the image is ACTIVE
openstack image listExpected output:
+--------------------------------------+--------+--------+
| ID | Name | Status |
+--------------------------------------+--------+--------+
| 67224b52-ed49-4b2f-8e59-13911e420948 | cirros | active |
+--------------------------------------+--------+--------+
# Create a VM
openstack server create \
--flavor m1.small \
--image cirros \
--network my-network \
my-first-vmExpected output:
+-----------------------------+--------------------------------------------------+
| Field | Value |
+-----------------------------+--------------------------------------------------+
| id | d5490d6d-a79c-4f37-9f9b-c926c3e66c6f |
| name | my-first-vm |
| status | ACTIVE |
| OS-EXT-STS:power_state | Running |
| flavor | m1.small (1 vCPU, 2048 MB RAM, 20 GB Disk) |
| image | cirros |
| created | 2026-03-07T21:47:31Z |
+-----------------------------+--------------------------------------------------+
# List all VMs
openstack server listExpected output:
+--------------------------------------+-------------+--------+----------+--------+-----------+
| ID | Name | Status | Networks | Image | Flavor |
+--------------------------------------+-------------+--------+----------+--------+-----------+
| d5490d6d-a79c-4f37-9f9b-c926c3e66c6f | my-first-vm | ACTIVE | N/A | cirros | m1.small |
+--------------------------------------+-------------+--------+----------+--------+-----------+
# Get detailed VM information
openstack server show my-first-vm
# Check resource quotas
openstack quota show --computeQuota output:
+-----------------------------+-------+
| Resource | Limit |
+-----------------------------+-------+
| instances | 10 |
| instances_used | 1 |
| cores | 20 |
| cores_used | 1 |
| ram | 51200 |
| ram_used | 2048 |
+-----------------------------+-------+
# Create a web server tier (2 small VMs)
openstack server create \
--flavor m1.small \
--image cirros \
--network my-network \
web-server-1
openstack server create \
--flavor m1.small \
--image cirros \
--network my-network \
web-server-2
# Create a database server (larger flavor)
openstack server create \
--flavor m1.medium \
--image cirros \
--network my-network \
db-server
# List all servers
openstack server list# Create a 10GB volume
openstack volume create --size 10 data-volume
# List volumes
openstack volume list
# Attach volume to VM
openstack server add volume my-first-vm data-volume# Stop a VM
openstack server stop my-first-vm
# Start a VM
openstack server start my-first-vm
# Reboot a VM
openstack server reboot my-first-vm
# Delete a VM
openstack server delete my-first-vm# List all resources
openstack server list # VMs
openstack network list # Networks
openstack volume list # Volumes
openstack flavor list # Available VM sizes
openstack image list # Available images
# Show details
openstack server show <vm-name>
openstack network show <network-name>
openstack volume show <volume-name># View container logs
docker compose logs lightstack --tail=50
# Check health
docker compose ps
# View database
docker exec lightstack-postgres psql -U lightstack -d lightstack -c "SELECT COUNT(*) FROM instances;"docker compose downNote: This preserves all data (VMs, networks, volumes) in the PostgreSQL database.
docker compose up -dAll your resources will still be there:
source ~/.lightstack-env
openstack server list# WARNING: This deletes everything!
docker compose down -v
docker compose up -dSymptom: invalid credentials (HTTP 401)
Solution:
# Verify environment is loaded
echo $OS_AUTH_URL
# Reload environment
source ~/.lightstack-env
# Check lightstack is running
docker compose psSymptom: Bind for 0.0.0.0:5001 failed: port is already allocated
Solution:
# Find what's using the port
lsof -i:5001
# Stop the conflicting service or change lightstack port in docker-compose.ymlSymptom: lightstack Up 2 minutes (unhealthy)
Solution:
# Check logs
docker compose logs lightstack --tail=50
# Common fix: Wait 10 more seconds for database
docker compose ps
# Restart if needed
docker compose restart lightstackSymptom: command not found: openstack
Solution:
# Install with pipx
pipx install python-openstackclient
# Ensure pipx bin is in PATH
pipx ensurepath
# Restart terminal or run:
source ~/.bashrc # or ~/.zshrc# Environment
source ~/.lightstack-env # Load credentials
# Authentication
openstack token issue # Get auth token
# VMs
openstack server create --flavor m1.small --image cirros --network <net> <name>
openstack server list # List VMs
openstack server show <name> # VM details
openstack server delete <name> # Delete VM
# Networks
openstack network create <name> # Create network
openstack network list # List networks
# Volumes
openstack volume create --size 10 <name> # Create volume
openstack volume list # List volumes
openstack server add volume <vm> <vol> # Attach volume
# Quotas
openstack quota show --compute # Show resource limits| Service | Port | URL |
|---|---|---|
| Keystone (Identity) | 5001 | http://localhost:5001/v3 |
| Nova (Compute) | 8774 | http://localhost:8774/v2.1 |
| Neutron (Network) | 9696 | http://localhost:9696/v2.0 |
| Cinder (Volumes) | 8776 | http://localhost:8776/v3 |
| Glance (Images) | 9292 | http://localhost:9292 |
| Metadata | 8775 | http://localhost:8775 |
Domain: Default
Username: admin
Password: secret
Project: default
- Installation Guide - Detailed setup options (Docker, binary)
- Configuration Guide - Customize your deployment
- Operations Guide - Production deployment and management
- API Reference - Complete API documentation
# Create a 3-tier application
openstack network create app-network
# Web tier (2 instances)
openstack server create --flavor m1.small --image cirros --network app-network web-1
openstack server create --flavor m1.small --image cirros --network app-network web-2
# App tier (2 instances)
openstack server create --flavor m1.medium --image cirros --network app-network app-1
openstack server create --flavor m1.medium --image cirros --network app-network app-2
# Database tier (with storage)
openstack volume create --size 50 db-volume
openstack server create --flavor m1.large --image cirros --network app-network --volume db-volume db-1
# View deployment
openstack server list
openstack network list
openstack volume listYou now have a fully functional OpenStack-compatible cloud running locally! 🎉
What you've accomplished:
- ✅ Deployed Lightstack in Docker containers
- ✅ Configured OpenStack CLI
- ✅ Created virtual machines
- ✅ Created networks and volumes
- ✅ Managed resource quotas
Your Lightstack cloud can:
- Create and manage virtual machines
- Provision isolated networks
- Attach persistent block storage
- Track resource usage and quotas
- Support multiple tenants (projects)
Ready for production? See OPERATIONS.md for deployment best practices.