chore(setup): improve setup.sh UX and update README

- Add --help and ansible-only/no-terraform modes\n- Add basic prereq checks and clearer error messages\n- Update README with new setup options and python requirements for helper scripts

README.md

@@ -24,6 +24,12 @@ This repo is intended to be driven by `setup.sh`:
 ./setup.sh
 ```
 
+For options:
+
+```bash
+./setup.sh --help
+```
+
 What it does:
 
 - Applies Terraform from `terraform/`
@@ -36,10 +42,18 @@ If you want Terraform only:
 ./setup.sh --no-ansible
 ```
 
+If you want Ansible only (requires an existing `inventory/hosts.yml`):
+
+```bash
+./setup.sh --ansible-only
+```
+
 ## Prereqs (local)
 
 - `terraform`
 - `ansible`
+- `python3` (for helper scripts)
+- `pip` / `python3 -m pip`
 - SSH access to the hosts
 
 If your SSH key is passphrase-protected, you must load it into your agent before running Ansible non-interactively:
@@ -179,6 +193,12 @@ Private keys (stored as Forgejo Actions secrets):
 
 To generate/update both Actions secrets (and optionally update both public keys in vault):
 
+Install Python deps first:
+
+```bash
+python3 -m pip install -r requirements.txt
+```
+
 ```bash
 python3 scripts/forgejo_set_actions_secret.py \
   --repo jfraeysd/infra-controller \

setup.sh

@@ -5,6 +5,27 @@ set -euo pipefail
 vault_args=()
 temp_vault_pass_file=""
 
+usage() {
+  cat <<'EOF'
+Usage: ./setup.sh [--no-ansible] [--no-terraform|--ansible-only] [--] [terraform <args>]
+
+Defaults:
+  - Runs Terraform (plan/apply) in terraform/
+  - Generates Ansible inventory from Terraform outputs
+  - Runs Ansible playbooks
+
+Options:
+  --no-ansible        Run Terraform only (no Ansible).
+  --no-terraform      Skip Terraform; requires existing inventory/hosts.yml.
+  --ansible-only      Alias for --no-terraform.
+  --help              Show this help.
+
+Terraform passthrough:
+  ./setup.sh -- terraform <cmd> [args]
+  ./setup.sh -- <terraform-subcommand> [args]
+EOF
+}
+
 cleanup() {
   if [[ -n "${temp_vault_pass_file}" ]] && [[ -f "${temp_vault_pass_file}" ]]; then
     rm -f "${temp_vault_pass_file}"
@@ -16,11 +37,23 @@ terraform_apply_args=()
 terraform_passthrough=()
 
 run_ansible=true
+run_terraform=true
+
+if [[ "${1:-}" == "--help" ]] || [[ "${1:-}" == "-h" ]]; then
+  usage
+  exit 0
+fi
+
 if [[ "${1:-}" == "--no-ansible" ]]; then
   run_ansible=false
   shift
 fi
 
+if [[ "${1:-}" == "--no-terraform" ]] || [[ "${1:-}" == "--ansible-only" ]]; then
+  run_terraform=false
+  shift
+fi
+
 if [[ "${1:-}" == "--" ]]; then
   shift
   if [[ "${1:-}" == "terraform" ]]; then
@@ -44,7 +77,25 @@ if [[ -f ".env" ]]; then
   set +a
 fi
 
+if [[ "${run_terraform}" == "true" ]]; then
+  if ! command -v terraform >/dev/null 2>&1; then
+    echo "terraform is required (install terraform or run with --no-terraform)" >&2
+    exit 2
+  fi
+fi
+
+if [[ "${run_ansible}" == "true" ]]; then
+  if ! command -v ansible-playbook >/dev/null 2>&1; then
+    echo "ansible-playbook is required (install ansible or run with --no-ansible)" >&2
+    exit 2
+  fi
+fi
+
 if [[ -f "secrets/vault.yml" ]]; then
+  if ! command -v ansible-vault >/dev/null 2>&1; then
+    echo "ansible-vault is required to read secrets/vault.yml" >&2
+    exit 2
+  fi
   if [[ -f "secrets/.vault_pass" ]]; then
     vault_args+=(--vault-password-file "secrets/.vault_pass")
   elif [[ -f ".vault_pass" ]]; then
@@ -81,30 +132,31 @@ if [[ -f "secrets/vault.yml" ]]; then
   fi
 fi
 
-terraform -chdir=terraform init
+if [[ "${run_terraform}" == "true" ]]; then
+  terraform -chdir=terraform init
 
-if (( ${#terraform_passthrough[@]} )); then
-  terraform -chdir=terraform "${terraform_passthrough[@]}"
-  exit 0
-fi
+  if (( ${#terraform_passthrough[@]} )); then
+    terraform -chdir=terraform "${terraform_passthrough[@]}"
+    exit 0
+  fi
 
-if (( ${#terraform_apply_args[@]} )); then
-  terraform -chdir=terraform apply "${terraform_apply_args[@]}"
-else
-  terraform -chdir=terraform plan -out=tfplan
-  terraform -chdir=terraform apply tfplan
-fi
+  if (( ${#terraform_apply_args[@]} )); then
+    terraform -chdir=terraform apply "${terraform_apply_args[@]}"
+  else
+    terraform -chdir=terraform plan -out=tfplan
+    terraform -chdir=terraform apply tfplan
+  fi
 
-rm -f terraform/tfplan
+  rm -f terraform/tfplan
 
-web_ipv4=$(terraform -chdir=terraform output -raw web_ip)
-services_ipv4=$(terraform -chdir=terraform output -raw services_ip)
+  web_ipv4=$(terraform -chdir=terraform output -raw web_ip)
+  services_ipv4=$(terraform -chdir=terraform output -raw services_ip)
 
-ssh_user=${TF_VAR_user:-ansible}
+  ssh_user=${TF_VAR_user:-ansible}
 
-mkdir -p inventory/host_vars
+  mkdir -p inventory/host_vars
 
-cat > inventory/hosts.yml <<EOF
+  cat > inventory/hosts.yml <<EOF
 all:
   children:
     web_hosts:
@@ -121,9 +173,15 @@ all:
           ansible_user: ${ssh_user}
 EOF
 
-cat > inventory/host_vars/web.yml <<EOF
+  cat > inventory/host_vars/web.yml <<EOF
 public_ipv4: ${web_ipv4}
 EOF
+else
+  if [[ ! -f inventory/hosts.yml ]]; then
+    echo "inventory/hosts.yml is missing; run without --no-terraform at least once to generate it" >&2
+    exit 2
+  fi
+fi
 
 if [[ "${run_ansible}" == "true" ]]; then
   if [[ -n "${vault_args+x}" ]] && (( ${#vault_args[@]} )); then