Quick Start

Quick Start

Get from zero to a deployed stack in four commands. This guide walks through initializing a project, scaffolding a stack, configuring it, and deploying to a VPS.

1. Initialize a Project

strut init --registry ghcr --org my-org

This creates a strut.conf at your project root with registry type, organization, and default branch settings.

2. Scaffold Your First Stack

strut scaffold my-app

This creates the stack directory structure from templates:

stacks/my-app/
├── docker-compose.yml
├── docker-compose.dev.yml
├── .env.template
├── services.conf
└── ...

3. Configure Your Stack

# Copy the env template and fill in your secrets
cp stacks/my-app/.env.template .prod.env
nano .prod.env

# Configure services and health check paths
nano stacks/my-app/services.conf

# Edit your compose file
nano stacks/my-app/docker-compose.yml

Key env vars to set in .prod.env:

Variable	Purpose
VPS_HOST	SSH target IP or hostname
VPS_USER	SSH user (usually ubuntu)
VPS_DEPLOY_DIR	Path to strut on VPS
GH_PAT	GitHub PAT for private container images
COMPOSE_PROJECT_NAME	Docker project name

4. Deploy

# Preview what will happen
strut my-app release --env prod --dry-run

# Full VPS release (update repo + deploy + verify health)
strut my-app release --env prod

5. Verify

# Health checks
strut my-app health --env prod --json

# Container status
strut my-app status --env prod

# View logs
strut my-app logs my-service --follow --env prod

What's Next?

• CLI Reference — Full command list
• Configuration — Deep dive into config files
• Deployment — Deploy workflows and service profiles
• Database Backups — Set up backup schedules
• Monitoring — Deploy Prometheus + Grafana