strut

Generic, installable CLI tool for managing Docker stacks on VPS infrastructure. Deploy, monitor, and operate any number of stacks from a single command line.

📖 Full Documentation →

---

Install

curl -fsSL https://raw.githubusercontent.com/gfargo/strut/main/install.sh | bash

Or clone manually:

git clone https://github.com/gfargo/strut.git ~/.strut
export PATH="$HOME/.strut:$PATH"

See Installation for upgrade, uninstall, and configuration options.

Quick Start

strut init --registry ghcr --org my-org       # Initialize project
strut scaffold my-app                          # Create a stack
nano stacks/my-app/.env.template               # Configure (copy to .prod.env)
strut my-app release --env prod                # Deploy to VPS

See Quick Start for the full walkthrough.

---

CLI

strut <stack> <command> [--env <env>] [options]

Command	Description
release	Full VPS release (update + migrate + deploy + verify)
deploy	Deploy stack containers
stop	Stop running containers
health	Run health checks
logs	View service logs
backup / restore	Database backup and restore
db:pull / db:push	Sync databases between VPS and local
drift	Configuration drift detection and auto-fix
keys	Key and credential management
domain	Configure domain and SSL certificates
shell / exec	SSH access to VPS
ship	Commit, push, and remote rebuild in one step
remote:init	Bootstrap strut on a remote VPS
local	Local development environment
debug	Container debugging tools
list / scaffold / init	Stack and project management

See CLI Reference for the complete command list with flags and examples.

Examples

strut my-app release --env prod                              # Production release
strut my-app health --env prod --json                        # Health checks
strut my-app logs api --follow --env prod                    # Follow logs
strut my-app backup postgres --env prod                      # Backup database
strut my-app db:pull --env prod                              # Pull DB locally
strut my-app keys db:rotate postgres --env prod              # Rotate credentials
strut my-app domain api.example.com admin@example.com --env prod  # SSL setup

---

Key Concepts

• Two-tree architecture — engine at ~/.strut/, your config at project root (Architecture)
• Config-driven — no hardcoded service names, ports, or orgs in the engine (Configuration)
• release vs deploy — release runs on VPS via SSH, deploy runs locally
• --env prod reads .prod.env for secrets and VPS connection info
• --dry-run previews destructive operations without executing
• Dynamic health checks driven by services.conf

---

Documentation

Topic	Description
Installation	Install, upgrade, uninstall
Quick Start	First project walkthrough
Architecture	How strut works under the hood
Configuration	strut.conf, env files, per-stack config
CLI Reference	Full command reference
Deployment	Deploy, release, stop workflows
Database Backups	Backup, restore, pull, push
Key Rotation	SSH, API, DB, GitHub credential rotation
Drift Detection	Detect and fix config drift
Domain and SSL	Custom domains, Let's Encrypt
Monitoring	Prometheus, Grafana, Alertmanager
Volume Management	Dynamic volume management
VPS Audit & Migration	Audit and migrate existing setups
Stack Validation	Validate stack integrity
Debugging	Troubleshoot production issues
Local Development	Local stack management
Contributing	Setup, testing, linting
Code Conventions	Shell module standards
Adding a New Command	Extending the CLI
Project Structure	File layout and module map

---

Testing

bats tests/                    # Run all tests
bats tests/test_config.bats    # Run specific file

See Contributing for the full development setup.

License

See LICENSE file.