Stack Validation

Stack Validation

Validate and check the integrity of strut stacks — whether creating a new one or verifying an existing one is healthy.

Config Validation

strut my-stack validate --env prod

Checks all config files against expected schemas:

• strut.conf — registry type, reverse proxy, branch name
• services.conf — port ranges (1-65535), boolean DB flags, health paths
• volume.conf — absolute paths, VOLUME_OWNERS format
• backup.conf — boolean flags, numeric retention, cron expressions
• required_vars — all listed vars present in env file
• Secret scanning (since v0.9.0) — flags known credential patterns in env files and errors if an env file is tracked by git

Returns exit code 0 for valid, 1 for errors. validate is also run automatically before each deploy unless --skip-validation is passed.

Secret Scanning

Env values are matched against these patterns:

Pattern	Detects
ghp_[A-Za-z0-9]{36}	GitHub Personal Access Token
github_pat_*	GitHub fine-grained PAT
AKIA[0-9A-Z]{16}	AWS access key
sk-[A-Za-z0-9]{20,}	OpenAI / Stripe-style API key
https://hooks.slack.com/	Slack webhook URL

Keys named *PASSWORD* / *SECRET* / *TOKEN* / *KEY* are additionally checked for weak values (password, changeme, secret, admin, 12345*, qwerty, etc.). Findings are warnings — they don't block deploy by themselves, but serve as a signal that the env file must be gitignored.

For a cross-stack audit with strict CI gating, see Security Posture.

Quick Validation (Existing Stack)

strut my-stack health --env prod                  # Runtime health
strut my-stack drift detect --env prod            # Config drift vs git
strut my-stack schema verify --env prod           # Postgres schema matches SQL init
strut my-stack keys env:validate --env prod       # Env vars against template
strut my-stack backup health --env prod           # Backup health scores

New Stack Checklist

Required Files

Every stack lives under stacks/<stack-name>/:

stacks/<stack-name>/
├── docker-compose.yml          # required
├── docker-compose.local.yml    # required
├── .env.template               # required
├── .drift-ignore               # recommended
├── backup.conf                 # recommended
├── repos.conf                  # recommended
├── nginx/                      # if using reverse proxy
├── sql/init/                   # Postgres DDL
└── config/                     # runtime config files

docker-compose.yml Validation

# Syntax check
docker compose -f stacks/<stack>/docker-compose.yml config --quiet

# Full resolved config
docker compose -f stacks/<stack>/docker-compose.yml --env-file .prod.env config

Verify:

• All services have restart: unless-stopped and healthcheck
• Database-dependent services use condition: service_healthy
• Optional services use profiles:
• No hardcoded secrets — use ${VAR} substitution

Environment Variable Validation

# Compare template vs actual
diff \
  <(grep -E '^[A-Z_]+=?' stacks/<stack>/.env.template | cut -d= -f1 | sort) \
  <(grep -E '^[A-Z_]+=?' .prod.env | cut -d= -f1 | sort)

# Check for unfilled placeholders
grep -E '(your-|change-me|xxxx|placeholder|TODO)' .prod.env

Required Variables

Variable	Purpose
VPS_HOST	SSH target
VPS_USER	SSH user
VPS_DEPLOY_DIR	strut path on VPS
GH_PAT	GitHub PAT for private images
COMPOSE_PROJECT_NAME	Docker project name

Full Integrity Audit

strut my-stack health --env prod --json
strut my-stack status --env prod
strut my-stack drift detect --env prod
strut my-stack schema verify --env prod
strut my-stack backup health --env prod
strut my-stack keys inventory

Stack Structure Tiers

Tier	Files
Minimal	docker-compose.yml + docker-compose.local.yml + .env.template + .drift-ignore
Standard	+ backup.conf + repos.conf + nginx/ + sql/init/
Full	+ volume.conf + config/ + keys/ + drift-history/

Common Validation Failures

Failure	Cause
docker-compose.yml syntax error	Tabs vs spaces, missing quotes, undefined ${VAR}
Missing required env vars	Template has vars not in .prod.env
Service fails healthcheck	Missing env vars, DB connection issues, port conflicts
Drift detected after first deploy	Add runtime files to .drift-ignore