Project Structure

Project Structure

How strut is organized on disk — the engine installation at ~/.strut/, the user project layout, and what each module is responsible for.

Engine (~/.strut/)

strut                  CLI entrypoint — command dispatch, usage, argument parsing
VERSION                Semver version (read by strut --version)
install.sh             One-liner installer (clone + symlink + upgrade + uninstall)

lib/
├── config.sh          Project config discovery (find_project_root, load_strut_config)
├── registry.sh        Pluggable registry auth (ghcr/dockerhub/ecr/none)
├── utils.sh           Colors, logging, SSH helpers, compose builders
├── deploy.sh          Deploy orchestration, VPS release, repo sync
├── deploy_blue_green.sh Blue-green deploy: dual-project, health-gated proxy swap
├── health.sh          Dynamic health checks from services.conf
├── docker.sh          Docker pull, prune helpers
├── schema.sh          Database schema management
├── topology.sh        Multi-host topology resolution
├── volumes.sh         Dynamic volume management from volume.conf
├── logs.sh            Log viewing and management
├── local.sh           Local development environment
├── debug.sh           Container debugging tools
├── audit.sh           VPS audit system
├── anonymize.sh       Data anonymization (PII protection)
├── migrate.sh         VPS migration wizard orchestration
├── monitor.sh         Monitoring stack management
├── github-token.sh    GitHub token helpers
│
├── cmd_deploy.sh      Deploy/release/update command handler
├── cmd_stop.sh        Stop command handler
├── cmd_backup.sh      Backup command handler
├── cmd_db.sh          Database operations (schema, pull, push)
├── cmd_drift.sh       Drift detection command handler
├── cmd_logs.sh        Logs command handler
├── cmd_debug.sh       Debug command handler
├── cmd_local.sh       Local development command handler
├── cmd_domain.sh      Domain/SSL command handler
├── cmd_volumes.sh     Volume management command handler
├── cmd_keys.sh        Key management command handler
├── cmd_remote.sh      Shell/exec/status command handler
├── cmd_remote_init.sh Remote VPS bootstrap command handler
├── cmd_ship.sh        Commit/push/deploy in one step
├── cmd_rebuild.sh     Build images on target + deploy
├── cmd_secrets.sh     Secrets push/pull/diff/validate/hydrate/lock/unlock/rotate/template/export
├── cmd_init_secrets.sh Generate .env from template
├── cmd_ssh_keygen.sh  Deploy keypair generation
├── cmd_ci_init.sh     CI/CD secrets bootstrap
├── cmd_provision.sh   Host provisioning via scripts
├── cmd_cert.sh        Tailscale cert renewal and status
├── cmd_gateway.sh     Caddy gateway management
├── cmd_rollback.sh    Deploy rollback handler
├── cmd_diff.sh        Diff local vs VPS state
├── cmd_lock.sh        Deploy concurrency locks
├── cmd_tui.sh         Interactive TUI for stack/command navigation
├── cmd_init.sh        Init command handler
├── cmd_scaffold.sh    Scaffold command handler
├── cmd_skills.sh      AI agent skills command handler
├── cmd_posture.sh     Security posture audit
├── cmd_status_all.sh  Cross-stack status dashboard
├── cmd_group.sh       Stack group dispatcher
├── cmd_doctor.sh      Diagnostic environment check
├── cmd_validate.sh    Config validation + secret scanning
│
├── backup/            Database-specific backup implementations
│   ├── cmd.sh         Backup command dispatch
│   ├── mysql.sh       MySQL backup/restore
│   ├── sqlite.sh      SQLite backup/restore
│   ├── alerts.sh      Backup alerting
│   ├── compare.sh     Backup comparison
│   ├── health.sh      Backup health scoring
│   ├── offsite.sh     Offsite backup sync (S3/R2/B2)
│   ├── retention.sh   Backup retention management
│   ├── schedule.sh    Backup scheduling
│   └── verify.sh      Backup verification
│
├── drift/             Drift detection modules
│   ├── alerts.sh      Drift alerting
│   ├── autofix.sh     Auto-fix logic
│   ├── metrics.sh     Drift metrics
│   └── schedule.sh    Drift scheduling
│
├── keys/              Key management modules
│   ├── api.sh         API key management
│   ├── audit.sh       Key audit logging
│   ├── db.sh          Database password rotation
│   ├── discovery.sh   Secret discovery
│   ├── env.sh         Env var management
│   ├── github.sh      GitHub secrets sync
│   ├── pull.sh        Key pull operations
│   ├── ssh.sh         SSH key management
│   ├── status.sh      Key status reporting
│   └── test.sh        Key testing
│
└── migrate/           VPS migration wizard phases
    ├── phase-preflight.sh   Phase 1: Pre-flight checks
    ├── phase-setup.sh       Phase 2: Setup strut on VPS
    ├── phase-audit.sh       Phase 3: Audit
    ├── phase-generate.sh    Phase 4: Generate stacks
    ├── phase-backup.sh      Phase 5: Pre-cutover backup
    ├── phase-test.sh        Phase 6: Test deployment
    ├── phase-cutover.sh     Phase 7: Cutover
    ├── phase-cleanup.sh     Phase 8: Cleanup
    ├── github-auth.sh       GitHub authentication helpers
    ├── setup-repo.sh        Repository setup
    └── ssh-helpers.sh       SSH helper functions

templates/             Stack scaffolding templates
├── Dockerfile
├── docker-compose.dev.yml
├── docker-compose.prod.yml
├── docker-entrypoint.sh
├── env.template
├── services.conf.template
├── strut.conf.template
├── dev.sh
└── .github/           CI/CD workflow templates

tests/                 BATS test suite
├── test_helper/
│   └── common.bash    Shared test helpers
├── integration/
│   ├── test_e2e.bats
│   └── test_recipes_e2e.bats
├── test_config.bats
├── test_registry.bats
├── test_health_discovery.bats
├── test_init.bats
├── test_scaffold.bats
├── test_docker_helpers.bats
├── test_utils.bats
├── test_volumes.bats
├── test_drift_helpers.bats
├── test_schema_helpers.bats
├── test_topology.bats
├── test_deploy_blue_green.bats
├── test_local_helpers.bats
├── test_github_token.bats
├── test_cmd_ship.bats
├── test_tui.bats
├── test_audit.bats
├── test_remote_init.bats
├── test_no_hardcodes.bats
└── ...

User Project

my-project/
├── strut.conf              # Project-level config
├── groups.conf             # Stack group definitions
├── notifications.conf      # Notification provider config
├── .prod.env               # Production secrets (gitignored)
├── .staging.env            # Staging secrets (gitignored)
├── scripts/
│   ├── provision-harbor.sh # Host provisioning scripts
│   └── provision-compass.sh
└── stacks/
    ├── gateway/
    │   ├── Caddyfile.harbor    # Host-specific Caddyfile
    │   └── Caddyfile.compass
    └── my-app/
        ├── docker-compose.yml
        ├── docker-compose.local.yml
        ├── .env.template
        ├── services.conf
        ├── required_vars
        ├── volume.conf
        ├── repos.conf
        ├── backup.conf
        ├── .drift-ignore
        ├── hooks/
        │   ├── pre_deploy.sh
        │   └── post_deploy.sh
        ├── nginx/
        ├── sql/init/
        └── config/