ai-training/.cursor/skills/deploy/steps/07_scripts.md

Step 7: Deployment Scripts

Role: DevOps / Platform engineer Goal: Create executable deployment scripts for pulling Docker images and running services on the remote target machine. Constraints: Produce real, executable shell scripts. This is the ONLY step that creates implementation artifacts.

Steps

1. Read containerization.md and deployment_procedures.md from previous steps
2. Read .env.example for required variables
3. Create the following scripts in SCRIPTS_DIR/:

deploy.sh — Main deployment orchestrator

• Validates that required environment variables are set (sources .env if present)
• Calls pull-images.sh, then stop-services.sh, then start-services.sh, then health-check.sh
• Exits with non-zero code on any failure
• Supports --rollback flag to redeploy previous image tags

pull-images.sh — Pull Docker images to target machine

• Reads image list and tags from environment or config
• Authenticates with container registry
• Pulls all required images
• Verifies image integrity (digest check)

start-services.sh — Start services on target machine

• Runs docker compose up -d or individual docker run commands
• Applies environment variables from .env
• Configures networks and volumes
• Waits for containers to reach healthy state

stop-services.sh — Graceful shutdown

• Stops services with graceful shutdown period
• Saves current image tags for rollback reference
• Cleans up orphaned containers/networks

health-check.sh — Verify deployment health

• Checks all health endpoints
• Reports status per service
• Returns non-zero if any service is unhealthy

4. All scripts must:

   • Be POSIX-compatible (#!/bin/bash with set -euo pipefail)
   • Source .env from project root or accept env vars from the environment
   • Include usage/help output (--help flag)
   • Be idempotent where possible
   • Handle SSH connection to remote target (configurable via DEPLOY_HOST env var)

5. Document all scripts in deploy_scripts.md

Self-verification

• All five scripts created and executable
• Scripts source environment variables correctly
• deploy.sh orchestrates the full flow
• pull-images.sh handles registry auth and image pull
• start-services.sh starts containers with correct config
• stop-services.sh handles graceful shutdown
• health-check.sh validates all endpoints
• Rollback supported via deploy.sh --rollback
• Scripts work for remote deployment via SSH (DEPLOY_HOST)
• deploy_scripts.md documents all scripts

Save action

Write scripts to SCRIPTS_DIR/. Write deploy_scripts.md using templates/deploy_scripts.md.