/local-deploy

description: Deploy latest Docker image to local Docker environment
allowed-tools: [Read, Write, Edit, Bash, Grep, Glob]

Deploy the latest Docker image from GitHub Container Registry to your LOCAL machine's Docker. Works on any machine with Docker Desktop or Docker Engine installed.

Usage

/local-deploy              # Deploy using dev mode (source-mounted, hot-reload)
/local-deploy --staging    # Deploy using staging mode (self-contained, production-like)
/local-deploy --rebuild    # Trigger GitHub Actions build first, then deploy
/local-deploy --staging --rebuild  # Build and deploy to staging mode

Deployment Modes

| Mode | Flag | Container | Use Case | | ------------------------- | ----------- | ---------------------------- | ---------------------------------------------------------------------------- | | **Development** (default) | (none) | `{{PROJECT_NAME}}-dev-app` | Active development with hot-reload (STANDARD port 3000) | | **Staging** | `--staging` | `{{PROJECT_NAME}}-staging-app` | Production-like, self-contained, survives git operations (port 3001) | | **Both** | `--both` | Both containers | Run dev and staging simultaneously ({{TICKET_PREFIX}}-400/{{TICKET_PREFIX}}-401) |

**When to use each mode:**

• **Dev mode**: You're actively writing code and want hot-reload (STANDARD port 3000)
• **Staging mode**: Testing, demos, or when you need stability during git operations (port 3001)
• **Both modes**: Run both simultaneously for testing migrations, feature comparison, etc.

Workflow

1. Parse Arguments

Check flags:

# Check command arguments
if [[ "$*" == *"--staging"* ]]; then
  MODE="staging"
else
  MODE="development"
fi

if [[ "$*" == *"--rebuild"* ]]; then
  REBUILD=true
else
  REBUILD=false
fi

2. Pre-Deployment Status Check

Get current running status (check both container types):

# Check for staging container
docker ps --filter name={{PROJECT_NAME}}-staging-app --format '{{.Names}}\t{{.Status}}'

# Check for dev container ({{TICKET_PREFIX}}-400: updated container name)
docker ps --filter name={{PROJECT_NAME}}-dev-app --format '{{.Names}}\t{{.Status}}'

Get current commit SHA:

# Try staging first, then dev ({{TICKET_PREFIX}}-400: updated container names)
docker inspect {{PROJECT_NAME}}-staging-app 2>/dev/null | grep 'org.opencontainers.image.revision' | cut -d'"' -f4 || \
docker inspect {{PROJECT_NAME}}-dev-app 2>/dev/null | grep 'org.opencontainers.image.revision' | cut -d'"' -f4

Get latest commit from dev branch:

git log origin/dev -1 --format='%h %s'

Report pre-deployment state showing:

• Current commit and message
• Target commit and message
• Container uptime
• Services status
• Current mode (staging vs dev)

3. Trigger GitHub Actions Build (Conditional)

**Only run if --rebuild flag is present**

If `$REBUILD` is true:

# Trigger workflow
gh workflow run "Build and Push Dev Docker Image" --ref dev

Show confirmation:

Triggering GitHub Actions build...
Workflow: Build and Push Dev Docker Image
Branch: dev

Wait for workflow to start (5-10 seconds):

sleep 10

Get workflow run ID:

WORKFLOW_RUN_ID=$(gh run list --workflow="Build and Push Dev Docker Image" --limit 1 --json databaseId --jq '.[0].databaseId')

Poll for completion (check every 30 seconds):

while true; do
  STATUS=$(gh run view $WORKFLOW_RUN_ID --json status --jq '.status')
  if [[ "$STATUS" == "completed" ]]; then
    CONCLUSION=$(gh run view $WORKFLOW_RUN_ID --json conclusion --jq '.conclusion')
    if [[ "$CONCLUSION" == "success" ]]; then
      echo "Build completed successfully"
      break
    else
      echo "Build failed"
      exit 1
    fi
  fi
  echo "Build in progress... (status: $STATUS)"
  sleep 30
done

Expected duration: 2-5 minutes

If `$REBUILD` is false:

Skipped: Using latest available image from registry

4. Deploy Based on Mode

**Staging Mode** (`--staging`):

./scripts/dev-docker.sh deploy

This single command:

1. Checks for port conflicts with dev stack 2. Pulls latest image from ghcr.io 3. Starts staging compose (no source mounts) 4. Waits for health check (up to 90s) 5. Reports status with container revision

**Development Mode** (default):

./scripts/dev-docker.sh pull
./scripts/dev-docker.sh restart

This:

1. Pulls latest image from ghcr.io 2. Restarts dev containers with source mounts 3. Enables hot-reload for active development

5. Verify Deployment

Check services started successfully:

# For dev mode (STANDARD port 3000, {{TICKET_PREFIX}}-401)
docker ps --filter name={{PROJECT_NAME}}-dev --format 'table {{.Names}}\t{{.Status}}'

# For staging mode (port 3001)
docker ps --filter name={{PROJECT_NAME}}-staging --format 'table {{.Names}}\t{{.Status}}'

Verify health endpoint:

# Dev (STANDARD port 3000)
curl -s http://localhost:3000/api/health | jq

# Staging (port 3001)
curl -s http://localhost:3001/api/health | jq

Expected response:

{
  "status": "healthy",
  "timestamp": "2025-10-11T...",
  "environment": "development"
}

Confirm new commit SHA:

# Staging
docker inspect {{PROJECT_NAME}}-staging-app | grep 'org.opencontainers.image.revision' | cut -d'"' -f4

# Dev ({{TICKET_PREFIX}}-400: updated container name)
docker inspect {{PROJECT_NAME}}-dev-app | grep 'org.opencontainers.image.revision' | cut -d'"' -f4

6. Post-Deployment Monitoring

Check logs for startup issues:

# Staging ({{TICKET_PREFIX}}-400: use container name)
docker logs {{PROJECT_NAME}}-staging-app --tail 50

# Dev ({{TICKET_PREFIX}}-400: use container name or script)
docker logs {{PROJECT_NAME}}-dev-app --tail 50
# Or use script
./scripts/dev-docker.