Provisioning

Provisioning

Run one-time setup scripts on remote hosts. The provision command handles uploading and executing host-specific provisioning scripts via SSH.

Since: v0.23.0

Overview

strut harbor provision                    # Run scripts/provision-harbor.sh on the host
strut harbor provision --verify           # Run verification section only
strut harbor provision --script ./my.sh   # Use custom script
strut harbor provision --dry-run          # Preview

File Convention

Place provision scripts at:

scripts/
├── provision-harbor.sh       # For host "harbor"
├── provision-compass.sh      # For host "compass"
└── provision-staging.sh      # For host "staging"

Or under infra/scripts/ as an alternative location.

The naming convention is provision-<host-alias>.sh. The host alias comes from the [hosts] section in strut.conf (see Multi-Host Topology).

How It Works

1. Resolves the provision script (convention-based or --script <path>)
2. Connects to the host via SSH (from topology or env vars)
3. Checks for a .provisioned marker (skips if already provisioned)
4. SCPs the script to /tmp/ on the remote host
5. Executes it with sudo bash
6. Creates a .provisioned marker with timestamp on success
7. Cleans up the remote temp file

Options

Flag	Description
--script <path>	Use a specific script instead of convention lookup
--verify	Run only the verification section (safe to re-run)
--dry-run	Show execution plan without making changes

Provisioned Marker

Once a host is provisioned, a marker file is created at <deploy_dir>/.provisioned. This prevents accidental re-provisioning.

To re-provision a host:

• Use --verify to re-run the verification section only
• Or delete the marker file on the remote host and run again

Writing Provision Scripts

A provision script is a standard bash script that runs with root access on the remote host. Best practices:

#!/usr/bin/env bash
set -euo pipefail

# --- Provisioning: harbor ---

# Install packages
apt-get update && apt-get install -y docker.io docker-compose-plugin

# Configure Docker
systemctl enable docker
usermod -aG docker ubuntu

# Setup directories
mkdir -p /home/ubuntu/strut

# --- Verification (runs with --verify) ---
if [[ "${1:-}" == "--verify" ]]; then
  echo "Verifying..."
  docker --version || { echo "Docker not installed"; exit 1; }
  docker compose version || { echo "Docker Compose not installed"; exit 1; }
  echo "All checks passed"
  exit 0
fi

Host Resolution

The host alias resolves via:

1. [hosts] section in strut.conf (topology)
2. Fallback to VPS_HOST, VPS_USER, VPS_PORT, VPS_SSH_KEY env vars

Example Workflow

# 1. Write provision script
nano scripts/provision-harbor.sh

# 2. Preview what will happen
strut harbor provision --dry-run

# 3. Run provisioning
strut harbor provision

# 4. Verify it worked
strut harbor provision --verify

# 5. Continue with strut setup
strut harbor remote:init --env prod
strut my-app release --env prod