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

---

GitHub Action / CI Deploys

Deploy a strut-managed stack from GitHub Actions in one step:

- uses: actions/checkout@v4

- uses: gfargo/strut-action@v1
  with:
    stack: my-app
    command: release          # release | ship (see security note in wiki)
    env: prod
    host: ${{ secrets.STRUT_HOST }}
    ssh-key: ${{ secrets.STRUT_SSH_KEY }}

The action installs a pinned strut, writes the SSH key to a 600-permissions file, materializes the env file from inputs/secrets, and runs the requested command. SSH key and env values are never echoed to logs.

See GitHub Action for the full input reference, pinning instructions, and examples. A starter workflow is available in templates/.github/workflows/strut-deploy.yml.

Known Limitations

Project paths must not contain spaces. strut's compose and SSH command builders use word-split path expansion. A project root like /Users/me/My Projects/infra will cause truncated, confusing errors.

Workarounds:

• Create a space-free symlink: ln -s "/path/with spaces/infra" ~/strut-project
• Or set STRUT_PROJECT to the symlink: STRUT_PROJECT=~/strut-project strut <stack> <cmd>

macOS SSH ControlPath — if you hit unix_listener: path "..." too long for Unix domain socket, the installed build may predate the /tmp/%C fix. Run strut upgrade to get the current build. As an escape hatch:

STRUT_SSH_NO_MUX=1 strut <stack> <cmd>          # disable mux entirely
STRUT_SSH_CONTROL_DIR=/tmp strut <stack> <cmd>   # explicit short socket dir

---

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.