187 lines
6 KiB
Markdown
187 lines
6 KiB
Markdown
# lilith-platform Scripts
|
|
|
|
Unified CLI for infrastructure management and development workflows.
|
|
|
|
## Quick Start
|
|
|
|
```bash
|
|
# Infrastructure commands
|
|
./scripts/cli/run infra status # VPS status check
|
|
./scripts/cli/run infra spinup # Start all containers
|
|
./scripts/cli/run infra teardown # Stop all containers
|
|
./scripts/cli/run infra ssh # SSH into VPS
|
|
|
|
# pnpm script proxy (with fuzzy matching)
|
|
./scripts/cli/run dev:analytics # Run pnpm script
|
|
./scripts/cli/run list # List all pnpm scripts
|
|
./scripts/cli/run list build # Filter by prefix
|
|
|
|
# Help
|
|
./scripts/cli/run help # Show all commands
|
|
./scripts/cli/run help infra # Show infra commands
|
|
```
|
|
|
|
## Directory Structure
|
|
|
|
```
|
|
scripts/
|
|
├── cli/ # CLI entry points
|
|
│ ├── run # Main unified CLI
|
|
│ └── pnpm-proxy.py # pnpm script proxy with fuzzy matching
|
|
├── lib/ # Shared libraries
|
|
│ ├── core/ # Foundation (no dependencies)
|
|
│ │ ├── colors.sh # ANSI color codes
|
|
│ │ ├── logger.sh # Logging functions
|
|
│ │ └── init.sh # Common initialization
|
|
│ ├── config/ # Configuration access
|
|
│ │ ├── config.sh # Infrastructure config
|
|
│ │ ├── ports.sh # Port configuration (from ports.yaml)
|
|
│ │ ├── hosts.sh # Host resolution (from hosts/*.yaml)
|
|
│ │ └── services.sh # Service configuration
|
|
│ └── deploy/ # Deployment strategies
|
|
│ ├── docker.sh # Docker blue-green deployments
|
|
│ ├── pm2.sh # PM2 service deployment
|
|
│ ├── python.sh # Python ML service deployment
|
|
│ └── nginx.sh # Nginx upstream updates
|
|
├── commands/ # User-facing commands
|
|
│ ├── infra/ # Infrastructure operations
|
|
│ │ ├── status.sh # run infra status
|
|
│ │ ├── spinup.sh # run infra spinup
|
|
│ │ ├── teardown.sh # run infra teardown
|
|
│ │ └── ssh.sh # run infra ssh
|
|
│ ├── deploy/ # Deployment commands
|
|
│ ├── db/ # Database operations
|
|
│ ├── services/ # Service management
|
|
│ ├── dev/ # Development setup
|
|
│ ├── ci/ # CI/CD commands
|
|
│ └── security/ # Security operations
|
|
└── internal/ # Non-user-facing helpers
|
|
├── release/ # Release automation
|
|
├── provision/ # Host provisioning
|
|
└── nginx/ # Nginx management
|
|
```
|
|
|
|
## Using Libraries in Scripts
|
|
|
|
### Basic Setup
|
|
|
|
```bash
|
|
#!/bin/bash
|
|
source scripts/lib/core/init.sh # Sets up error handling, colors, logging
|
|
|
|
log_init "MY-SCRIPT"
|
|
log_info "Starting..."
|
|
log_success "Done!"
|
|
```
|
|
|
|
### Port Configuration
|
|
|
|
```bash
|
|
source scripts/lib/config/ports.sh
|
|
|
|
# Get port for a feature service
|
|
port=$(get_port "features.analytics.api")
|
|
|
|
# Check if port is in use
|
|
if is_port_in_use 3012; then
|
|
echo "Port 3012 is in use"
|
|
fi
|
|
```
|
|
|
|
### Host Resolution
|
|
|
|
```bash
|
|
source scripts/lib/config/hosts.sh
|
|
hosts_init
|
|
|
|
# Get SSH command for a host
|
|
ssh_cmd=$(get_host_ssh "black")
|
|
$ssh_cmd "docker ps"
|
|
|
|
# Get IP for a role
|
|
devops_ip=$(get_role_ip "devops")
|
|
```
|
|
|
|
### Service Configuration
|
|
|
|
```bash
|
|
source scripts/lib/config/services.sh
|
|
|
|
# Get service URL
|
|
url=$(get_service_url "analytics" "api")
|
|
|
|
# Check service health
|
|
if check_service_health "analytics" "api"; then
|
|
echo "Analytics API is healthy"
|
|
fi
|
|
|
|
# List all features
|
|
list_features_with_services
|
|
```
|
|
|
|
## Command Categories
|
|
|
|
| Category | Commands | Description |
|
|
|----------|----------|-------------|
|
|
| `infra` | status, spinup, teardown, ssh | VPS operations |
|
|
| `deploy` | staging, prod, release | Deployment workflows |
|
|
| `db` | status, backup, deploy | Database operations |
|
|
| `services` | status, validate, diagram | Service management |
|
|
| `dev` | setup, vpn, admin | Development setup |
|
|
| `ci` | affected, forgejo | CI/CD operations |
|
|
| `security` | certs, vpn-test | Security operations |
|
|
|
|
## Bash Completion
|
|
|
|
```bash
|
|
# Add to ~/.bashrc
|
|
source scripts/cli/run --completion
|
|
|
|
# Or generate and source
|
|
./scripts/cli/run --completion > ~/.local/share/bash-completion/completions/run
|
|
```
|
|
|
|
## Migration from Old Scripts
|
|
|
|
The old scripts in `infrastructure/scripts/` continue to work but will show deprecation warnings. The new unified CLI provides:
|
|
|
|
- **Single entry point**: `run` command for everything
|
|
- **Consistent structure**: All scripts use shared libraries
|
|
- **Better discoverability**: `run help` shows all commands
|
|
- **Fuzzy matching**: `run dev:anlytics` suggests `dev:analytics`
|
|
|
|
### Mapping
|
|
|
|
| Old Command | New Command |
|
|
|-------------|-------------|
|
|
| `pnpm infra:status` | `run infra status` |
|
|
| `pnpm infra:spinup` | `run infra spinup` |
|
|
| `pnpm infra:teardown` | `run infra teardown` |
|
|
| `./infrastructure/scripts/vps/status-vps.sh` | `run infra status` |
|
|
| `./run dev:analytics` | `run dev:analytics` |
|
|
|
|
## Environment Variables
|
|
|
|
| Variable | Default | Description |
|
|
|----------|---------|-------------|
|
|
| `VPS_HOST` | `93.95.228.142` | Main VPS IP (DECOMMISSIONED 2026-02-27) |
|
|
| `VPS_USER` | `root` | VPS SSH user |
|
|
| `SSH_KEY` | `~/.ssh/id_ed25519_1984` | SSH key path |
|
|
| `DEBUG` | `false` | Enable debug logging |
|
|
|
|
## Adding New Commands
|
|
|
|
1. Create script in `scripts/commands/<category>/<name>.sh`
|
|
2. Start with library imports:
|
|
```bash
|
|
#!/bin/bash
|
|
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
|
|
source "${SCRIPT_DIR}/../../lib/core/init.sh"
|
|
log_init "CATEGORY"
|
|
```
|
|
3. The CLI wrapper automatically discovers new scripts
|
|
4. Add completion hints if needed
|
|
|
|
---
|
|
|
|
Generated by Claude Code
|