Modern Python-based CLI for DevStack Core with service profiles, colored output, and enhanced user experience.
Version: 1.3.0 | Last Updated: 2025-01-18
- Overview
- Getting Help
- Installation
- Quick Start
- Complete Command Reference
- Service Profiles
- Environment Variables
- Migration from Bash Script
- Troubleshooting
- Advanced Usage
devstack is a modern Python-based management CLI for DevStack Core with comprehensive service profile support. It provides a beautiful terminal experience with colored output, tables, and progress indicators powered by the Rich library.
Key Features:
- 🎯 Profile Management: minimal, standard, full, and reference profiles
- 🔐 Vault Integration: Complete HashiCorp Vault lifecycle management
- 🎨 Beautiful UI: Rich library with colored output, tables, progress bars
- 🏥 Health Checks: Monitor all services with color-coded status
- 📦 Backup/Restore: Complete data protection for all services
- 🔄 Auto-Detection: Automatic venv activation and environment loading
- 📚 Comprehensive Help: Built-in help for every command with examples
The script includes comprehensive help documentation accessible via standard help commands:
# Main help - shows all commands
./devstack --help
./devstack -h
# Help for specific command - shows all options and examples
./devstack start --help
./devstack logs --help
./devstack vault-show-password --help
# Version information
./devstack --versionEvery command includes:
- ARGUMENTS: Required and optional parameters
- OPTIONS: All available flags with defaults
- EXAMPLES: Real-world usage demonstrations
- NOTES: Important warnings, tips, and gotchas
Examples:
# See all available --profile options
./devstack start --help
# Learn about log viewing options (--follow, --tail)
./devstack logs --help
# Understand which services have stored passwords
./devstack vault-show-password --help- macOS: Apple Silicon (M1/M2/M3/M4) or Linux (x86_64/arm64)
- Python: 3.8 or higher (Python 3.14.0 confirmed working)
- Homebrew: Package manager (macOS)
# Install prerequisites
brew install colima docker docker-compose uv
# Clone repository
cd ~/devstack-core
# Setup Python virtual environment (one-time)
uv venv
uv pip install -r scripts/requirements.txt
# The wrapper script automatically activates the venv
./devstack --help# Create and activate virtual environment
python3 -m venv .venv
source .venv/bin/activate
# Install dependencies
pip3 install -r scripts/requirements.txt
# Deactivate when done
deactivate
# Note: The wrapper script handles activation automatically# Install Homebrew Python
brew install python@3
# Install dependencies system-wide (not recommended)
/opt/homebrew/bin/pip3 install click rich PyYAML python-dotenv# Test dependencies are available
python3 -c "import click, rich, yaml; print('✓ All dependencies installed!')"
# Test the script
./devstack --version
./devstack --helpThe script requires these packages (installed automatically):
- click >= 8.1.0 - CLI framework
- rich >= 13.0.0 - Beautiful terminal output
- PyYAML >= 6.0 - Configuration file parsing
- python-dotenv >= 1.0.0 - Environment variable loading
# 1. Install dependencies (see Installation section)
cd ~/devstack-core
uv venv && uv pip install -r scripts/requirements.txt
# 2. Configure environment
cp .env.example .env
# Edit .env if needed (optional - auto-generated by Vault)
# 3. Start with standard profile (recommended)
./devstack start --profile standard
# 4. Initialize Vault (one-time setup)
./devstack vault-init
# 5. Bootstrap Vault PKI and credentials
./devstack vault-bootstrap
# 6. Initialize Redis cluster (for standard/full profiles)
./devstack redis-cluster-init
# 7. Initialize Forgejo Git server (optional)
./devstack forgejo-init
# 8. Verify all services are healthy
./devstack health# Morning: Start development environment
./devstack start --profile standard
# Check status and health
./devstack status
./devstack health
# View service logs
./devstack logs postgres
# Get service credentials
./devstack vault-show-password postgres
# Evening: Stop environment
./devstack stopStart Minimal Stack (Git + Postgres + Redis):
./devstack start --profile minimalStart Full Stack with Reference Apps:
./devstack start --profile standard --profile referenceBackup Before Maintenance:
./devstack backupRestore from Backup:
./devstack restore
./devstack restore 20250118_143022Starts Colima VM and Docker services with specified profile(s).
Usage:
./devstack start [--profile PROFILE] [--detach/--no-detach]Options:
--profile, -p- Service profile to start (minimal/standard/full/reference)--detach, -d- Run in background (default: True)- Can specify multiple
--profileflags
Examples:
# Start with standard profile (recommended)
./devstack start --profile standard
# Start minimal profile (lightweight, 2GB RAM)
./devstack start --profile minimal
# Combine profiles (standard + reference apps)
./devstack start --profile standard --profile reference
# Start in foreground (see logs in real-time)
./devstack start --profile minimal --no-detachWhat it does:
- Checks if Colima is already running
- Starts Colima VM with configured resources
- Loads profile-specific environment variables
- Starts Docker Compose services for specified profiles
- Shows service status after startup
Stops Docker services and optionally Colima VM.
Usage:
./devstack stop [--profile PROFILE]Options:
--profile, -p- Stop specific profile services only (keeps VM running)
Examples:
# Stop everything (services + Colima VM)
./devstack stop
# Stop only reference profile services
./devstack stop --profile reference
# Stop only standard services (keeps minimal running)
./devstack stop --profile standardWhat it does:
- Stops Docker Compose services
- Stops Colima VM (if no
--profilespecified) - Releases system resources
Restarts Docker services without restarting Colima VM.
Usage:
./devstack restartWhat it does:
- Restarts all running Docker containers
- VM stays running (faster than stop + start)
- Useful for applying configuration changes
Displays status of Colima VM and all running services.
Usage:
./devstack statusOutput includes:
- Colima VM status and IP address
- Running services count
- CPU and memory allocation
- Disk usage
- Table of all containers with status
Performs health checks on all running services with color-coded output.
Usage:
./devstack healthOutput:
- ✅ Green: Service is healthy and running
⚠️ Yellow: Running but no health check or starting- ❌ Red: Stopped, unhealthy, or exited
Checks:
- Container running status
- Docker health check results
- Dependency availability
- Response times (where applicable)
View logs for all services or a specific service.
Usage:
./devstack logs [SERVICE] [--follow] [--tail N]Arguments:
SERVICE- Service name (optional, shows all if omitted)
Options:
--follow, -f- Follow log output in real-time--tail, -n- Number of lines to show (default: 100)
Examples:
# View all service logs (last 100 lines)
./devstack logs
# View PostgreSQL logs
./devstack logs postgres
# Follow Vault logs in real-time
./devstack logs vault -f
# Show last 500 lines
./devstack logs --tail 500 postgres
# Follow multiple services (use docker compose directly)
docker compose logs -f postgres vault redis-1Open an interactive shell in a running container.
Usage:
./devstack shell <SERVICE> [--shell SHELL]Arguments:
SERVICE- Service name (required)
Options:
--shell, -s- Shell to use (default: sh, can use bash if available)
Examples:
# Shell into PostgreSQL container
./devstack shell postgres
# Use bash instead of sh
./devstack shell vault --shell bash
# Shell into Redis node
./devstack shell redis-1
# Common commands after entering shell:
# PostgreSQL: psql -U $POSTGRES_USER -d $POSTGRES_DB
# Redis: redis-cli -a $REDIS_PASSWORD
# MongoDB: mongosh -u $MONGODB_USER -p $MONGODB_PASSWORD
# Vault: vault statusDisplay Colima VM IP address.
Usage:
./devstack ipOutput:
- VM IP address (e.g., 192.168.106.2)
- Network interface information
Use cases:
- Accessing services from libvirt VMs
- Configuring network clients
- Debugging network connectivity
Initialize Vault and generate unseal keys (first-time setup).
Usage:
./devstack vault-initWhat it does:
- Initializes Vault with Shamir's Secret Sharing
- Generates 5 unseal keys (3 required to unseal)
- Generates root token
- Saves keys to
~/.config/vault/keys.json - Saves root token to
~/.config/vault/root-token - Automatically unseals Vault
~/.config/vault/ immediately!
One-time command: Run only after first start.
Manually unseal Vault using stored unseal keys.
Usage:
./devstack vault-unsealWhen to use:
- Vault is sealed after unexpected shutdown
- Auto-unseal mechanism failed
- Manual intervention required
- After Colima VM restart
What it does:
- Reads unseal keys from
~/.config/vault/keys.json - Unseals Vault using first 3 of 5 keys
- Displays seal status
Display Vault seal status and root token information.
Usage:
./devstack vault-statusOutput:
- Sealed status (true/false)
- Initialized status (true/false)
- Vault version
- Root token location
- Instructions to set VAULT_TOKEN environment variable
Print Vault root token to stdout (for scripting).
Usage:
./devstack vault-token
# Use in scripts
export VAULT_TOKEN=$(./devstack vault-token)
vault statusOutput:
- Raw token (no formatting) suitable for automation
Bootstrap Vault with PKI infrastructure and service credentials.
Usage:
./devstack vault-bootstrapPrerequisites:
- Vault must be initialized and unsealed
- Run
vault-initfirst
What it does:
- Enables PKI secrets engine at
pki/ - Generates Root CA (10-year validity)
- Generates Intermediate CA (5-year validity)
- Configures certificate roles for all services
- Enables KV v2 secrets engine at
secret/ - Generates random passwords for all services:
- PostgreSQL (admin user)
- MySQL (root user)
- Redis (AUTH password for all 3 nodes)
- RabbitMQ (admin user)
- MongoDB (root user)
- Forgejo (admin user)
- Exports CA certificate chain to
~/.config/vault/ca/ - Creates Forgejo database in PostgreSQL
- Configures AppRole authentication for all services
One-time setup command: Run after vault-init.
Export Vault CA certificate chain to stdout.
Usage:
./devstack vault-ca-cert > ca.pem
# Install on macOS keychain
./devstack vault-ca-cert | \
sudo security add-trusted-cert -d -r trustRoot \
-k /Library/Keychains/System.keychain /dev/stdin
# Install on Linux
./devstack vault-ca-cert | sudo tee /usr/local/share/ca-certificates/devstack-ca.crt
sudo update-ca-certificatesOutput:
- PEM-encoded CA certificate chain (stdout)
- Certificate location information (stderr)
Retrieve and display service credentials from Vault.
Usage:
./devstack vault-show-password <SERVICE>Arguments:
SERVICE- Service name (required)
Available services:
postgres- PostgreSQL admin passwordmysql- MySQL root passwordredis-1,redis-2,redis-3- Redis AUTH passwordsrabbitmq- RabbitMQ admin passwordmongodb- MongoDB root passwordforgejo- Admin username, email, and password
Examples:
# Get PostgreSQL password
./devstack vault-show-password postgres
# Get Forgejo admin credentials
./devstack vault-show-password forgejo
# Get Redis password for scripting
REDIS_PASSWORD=$(./devstack vault-show-password redis-1 | grep password | awk '{print $2}')Initialize Forgejo Git server via automated bootstrap.
Usage:
./devstack forgejo-initPrerequisites:
- Colima and services running
- Vault initialized and bootstrapped
- PostgreSQL database created (vault-bootstrap does this)
What it does:
- Checks Forgejo container is running
- Checks PostgreSQL is accessible
- Runs automated installation script
- Configures Forgejo with Vault-generated credentials
- Creates admin user account
- Sets up PostgreSQL database connection
After completion:
- Access Forgejo at http://localhost:3000
- Get admin credentials:
./devstack vault-show-password forgejo - Clone repos via SSH:
ssh://git@localhost:2222/username/repo.git
Initialize 3-node Redis cluster (required for standard/full profiles).
Usage:
./devstack redis-cluster-initPrerequisites:
- Started with
--profile standardor--profile full - All 3 Redis nodes running (redis-1, redis-2, redis-3)
What it does:
- Checks Redis containers are running
- Fetches Redis password from Vault
- Creates 3-node cluster with automatic slot distribution:
- redis-1: slots 0-5460
- redis-2: slots 5461-10922
- redis-3: slots 10923-16383
- Verifies cluster formation
- Displays cluster nodes
Verify cluster:
# Connect to cluster
redis-cli -c -h localhost -p 6379
# Check cluster nodes
redis-cli -h localhost -p 6379 cluster nodes
# Check cluster info
redis-cli -h localhost -p 6379 cluster infoBackup all service data to timestamped directory.
Usage:
./devstack backupWhat it backs up:
- PostgreSQL: Complete pg_dumpall of all databases
- MySQL: Complete mysqldump of all databases
- MongoDB: Binary mongodump archive
- Forgejo: Tarball of /data directory (repos + config)
- .env: Configuration file
Backup location:
./backups/YYYYMMDD_HHMMSS/- Example:
./backups/20250118_143022/
Output:
- Progress indicators for each service
- Final backup size
- Backup directory path
- Running
resetcommand - Major upgrades
- Configuration changes
- Database migrations
Restore service data from a timestamped backup directory.
Usage:
# List available backups
./devstack restore
# Restore specific backup
./devstack restore 20250118_143022Arguments:
BACKUP_NAME- Backup directory name (optional)
- All PostgreSQL databases
- All MySQL databases
- All MongoDB databases
- Forgejo data directory
.envconfiguration file
What it does:
- Lists available backups (if no backup specified)
- Validates backup directory exists
- Prompts for confirmation
- Restores PostgreSQL databases
- Restores MySQL databases (with Vault password)
- Restores MongoDB databases
- Restores Forgejo data
- Restores .env configuration
- Recommends restarting services
After restore:
# Restart services to apply changes
./devstack restart
# Verify restoration
./devstack healthCompletely destroy and delete Colima VM - DESTRUCTIVE OPERATION.
Usage:
./devstack resetThis command DESTROYS:
- All Docker containers and images
- All Docker volumes (databases, Git repos, files)
- Colima VM disk and configuration
- ALL service data
This command PRESERVES:
- Vault keys/tokens in
~/.config/vault/(on host) - Backups in
./backups/(on host) .envconfiguration (on host)
Confirmation required: Yes (interactive prompt)
backup FIRST!
Use cases:
- Complete environment corruption
- Starting fresh after major changes
- Cleaning up before deleting project
List all available service profiles with details.
Usage:
./devstack profilesOutput includes:
- Profile name
- Number of services
- RAM estimate
- Description and use case
- Custom profiles (from profiles.yaml)
| Profile | Services | RAM | Startup Time | Use Case |
|---|---|---|---|---|
| minimal | 5 | 2GB | ~20s | Git + essential dev |
| standard | 10 | 4GB | ~45s | Full dev stack + Redis cluster |
| full | 18 | 6GB | ~60s | Everything + observability |
| reference | +5 | +1GB | +15s | Educational API examples |
Services: vault, postgres, pgbouncer, forgejo, redis-1 (standalone)
Use Cases:
- Personal Git repository hosting
- Simple CRUD application development
- Learning DevStack Core
- CI/CD pipelines (lightweight testing)
Start:
./devstack start --profile minimalRedis: Single standalone instance (no cluster)
Services: All minimal + mysql, mongodb, redis-2, redis-3, rabbitmq
Use Cases:
- Multi-database application development
- Redis cluster testing and development
- Message queue integration
- Full-featured local development
Start:
./devstack start --profile standard
# Initialize Redis cluster (first time)
./devstack redis-cluster-initRedis: 3-node cluster with 16,384 slots distributed
Services: All standard + prometheus, grafana, loki, vector, cadvisor, redis-exporters
Use Cases:
- Performance testing and optimization
- Production troubleshooting simulation
- Observability pattern learning
- Load testing with metrics collection
Start:
./devstack start --profile full
# Initialize Redis cluster (first time)
./devstack redis-cluster-initObservability Stack:
- Prometheus: http://localhost:9090
- Grafana: http://localhost:3001 (admin/admin)
- Loki: http://localhost:3100
Services: reference-api, api-first, golang-api, nodejs-api, rust-api (~40%)
Use Cases:
- Learning API design patterns
- Comparing language implementations
- Testing integration patterns
- Code-first vs API-first comparison
Start:
# Must combine with standard or full
./devstack start --profile standard --profile referenceAccess:
- Python (code-first): http://localhost:8000/docs
- Python (API-first): http://localhost:8001/docs
- Go: http://localhost:8002/health
- Node.js: http://localhost:8003/health
- Rust: http://localhost:8004/health (~40% complete)
# Colima profile name (default: default)
export COLIMA_PROFILE=default
# CPU cores (default: 4)
export COLIMA_CPU=4
# Memory in GB (default: 8)
export COLIMA_MEMORY=8
# Disk size in GB (default: 60)
export COLIMA_DISK=60The script loads environment variables in this order (highest to lowest priority):
- Shell environment (highest priority)
configs/profiles/<profile>.env(profile-specific overrides)- Root
.envfile (project defaults) docker-compose.ymldefaults (lowest priority)
Example:
# Profile-specific variables take precedence
./devstack start --profile standard
# Loads configs/profiles/standard.env automatically| Bash Script | Python CLI | Status | Notes |
|---|---|---|---|
start |
start |
✅ Enhanced | Added profile support |
stop |
stop |
✅ Enhanced | Added profile filtering |
restart |
restart |
✅ Identical | Same functionality |
status |
status |
✅ Enhanced | Rich tables, better formatting |
logs |
logs |
✅ Identical | Same functionality |
shell |
shell |
✅ Identical | Same functionality |
ip |
ip |
✅ Identical | Same functionality |
health |
health |
✅ Enhanced | Color-coded output |
backup |
backup |
✅ Enhanced | Progress bars |
| N/A | restore |
✅ NEW | Restore from backups |
vault-* |
vault-* |
✅ Identical | All Vault commands |
forgejo-init |
forgejo-init |
✅ Identical | Same functionality |
redis-cluster-init |
redis-cluster-init |
✅ Identical | Same functionality |
help |
--help |
✅ Enhanced | Click framework help |
| N/A | profiles |
✅ NEW | List all profiles |
reset |
reset |
✅ Enhanced | Added confirmation |
-
Better UI:
- Rich library for beautiful tables
- Colored output with semantic meaning
- Progress bars for long operations
- Spinners for waiting operations
-
Profile Support:
- Native
--profileflag - Automatic environment loading
- Multiple profiles can be combined
- Native
-
Improved Safety:
- Confirmation prompts for destructive ops
- Better error messages
- Validation before operations
- Helpful suggestions
-
Automation Friendly:
- Proper exit codes for CI/CD
- Raw output modes for scripting
- Better error handling
For existing bash script users:
-
Install Python dependencies:
cd ~/devstack-core uv venv uv pip install -r scripts/requirements.txt
-
Test basic commands:
./devstack --help ./devstack status ./devstack health
-
Update aliases/scripts:
- Old:
./devstack.sh start - New:
./devstack start
- Old:
-
All data preserved: The Python CLI uses the same Docker Compose files and configurations.
Problem: ModuleNotFoundError: No module named 'click'
Solution:
# Install dependencies
uv venv
uv pip install -r scripts/requirements.txt
# Or use pip directly
pip3 install --user click rich PyYAML python-dotenvProblem: Permission denied: ./devstack
Solution:
chmod +x devstackProblem: Command not found: colima
Solution:
# Install Colima
brew install colimaProblem: Environment variables from profile not taking effect
Diagnosis:
# Check if profile .env file exists
ls -la configs/profiles/standard.env
# Manually load to debug
set -a
source configs/profiles/standard.env
set +a
env | grep REDISSolution:
- Verify profile .env file exists
- Check for syntax errors in .env file
- Ensure no conflicting environment variables
Problem: Error initializing Redis cluster
Diagnosis:
# Check redis containers are running
docker ps | grep redis
# Check if already initialized
redis-cli -h localhost -p 6379 cluster nodesSolution:
# Reset if needed (WARNING: destroys data)
docker compose down
docker volume rm devstack-core_redis_1_data devstack-core_redis_2_data devstack-core_redis_3_data
./devstack start --profile standard
./devstack redis-cluster-initProblem: Services can't connect to Vault after Colima restart
Solution:
# Check Vault status
./devstack vault-status
# Unseal if needed
./devstack vault-unseal
# Restart services that depend on Vault
./devstack restartCreate a custom profile environment file:
# Create custom profile
cat > configs/profiles/my-custom.env << 'EOF'
# Custom Redis configuration
REDIS_MAX_MEMORY=1024mb
REDIS_MAXMEMORY_POLICY=allkeys-lfu
# Custom PostgreSQL configuration
POSTGRES_MAX_CONNECTIONS=200
POSTGRES_SHARED_BUFFERS=512MB
# Enable observability
ENABLE_METRICS=true
ENABLE_LOGS=true
EOF
# Load and start
set -a
source configs/profiles/my-custom.env
set +a
docker compose --profile standard up -dUse the Python CLI in CI/CD pipelines:
#!/bin/bash
# CI/CD integration example
set -e # Exit on error
# Start minimal profile for testing
./devstack start --profile minimal
# Wait for services to be healthy
sleep 30
if ! ./devstack health; then
echo "Services not healthy"
exit 1
fi
# Run tests
pytest tests/
# Cleanup
./devstack stopContinuous health monitoring:
# Watch status in real-time
watch -n 5 './devstack status'
# Continuous health monitoring
while true; do
./devstack health
sleep 60
done
# Alert on unhealthy services
if ! ./devstack health | grep -q "All services healthy"; then
echo "ALERT: Services unhealthy" | mail -s "DevStack Alert" admin@example.com
fi- SERVICE_PROFILES.md - Detailed profile documentation
- INSTALLATION.md - Complete installation guide
- VAULT.md - Vault operations and PKI
- TROUBLESHOOTING.md - General troubleshooting
- MANAGEMENT.md - Management operations reference
Last Updated: 2025-01-18 Version: 1.3.0