deployment-automation

name	deployment-automation
description	Agents should invoke this skill for Docker Compose deployments, container updates, stack health checks, rollbacks, compose-file changes, image upgrades, failed deploys, or service restart planning. Provides safe deployment and rollback workflows.

Deployment Automation

Manage Docker Compose deployments, container lifecycle, image updates, and rollbacks.

Quick Start

Deploy a Compose Stack

# Start services
docker compose up -d

# Start with rebuild
docker compose up -d --build

# Check status
docker compose ps

Update a Running Service

# Pull latest images
docker compose pull

# Recreate with new images
docker compose up -d --remove-orphans

# Verify health
docker compose ps
docker compose logs --tail=20 <service>

---

Docker Compose Management

Lifecycle Commands

# Start all services
docker compose up -d

# Stop all services (preserves volumes)
docker compose down

# Stop and remove volumes (DESTRUCTIVE)
docker compose down -v

# Restart a specific service
docker compose restart <service>

# Scale a service
docker compose up -d --scale <service>=3

# View logs
docker compose logs -f <service>
docker compose logs --tail=50 <service>

Stack Health Check

# List all containers with status
docker compose ps --format "table {{.Name}}\t{{.Status}}\t{{.Ports}}"

# Check resource usage
docker stats --no-stream --format "table {{.Name}}\t{{.CPUPerc}}\t{{.MemUsage}}"

# Inspect a specific container
docker inspect <container> | jq '.[0].State'

---

Image Update Workflow

Safe update process with rollback path:

Step 1: Pre-Update Checks

# Record current state
docker compose ps > /tmp/pre-update-state.txt
docker compose config --images > /tmp/current-images.txt

# Check current image digests
docker compose images --format "table {{.Repository}}\t{{.Tag}}\t{{.ID}}"

Step 2: Pull New Images

# Pull latest images
docker compose pull

# Compare image IDs (see if anything changed)
docker compose images --format "table {{.Repository}}\t{{.Tag}}\t{{.ID}}"

Step 3: Deploy Update

# Recreate containers with new images
docker compose up -d --remove-orphans

# Wait for services to stabilize
sleep 10

# Verify all containers are healthy
docker compose ps

Step 4: Post-Update Verification

# Check for restart loops
docker compose ps --format "{{.Name}}: {{.Status}}" | grep -i "restarting"

# Check logs for errors
docker compose logs --since 2m --tail=50 2>&1 | grep -iE "error|fatal|panic"

# Test service endpoints
curl -s -o /dev/null -w "%{http_code}" http://localhost:<port>/health

Step 5: Rollback (If Needed)

# Rollback to previous image
docker compose down
# Edit compose file or use specific image tags
docker compose up -d

# Or if you tagged the previous image:
docker tag <service>:previous <service>:latest
docker compose up -d

---

Health Check Patterns

In Compose Files

Always include health checks in new deployments:

services:
  myservice:
    image: myimage:latest
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s
    restart: unless-stopped

Common Health Check Types

# HTTP endpoint
healthcheck:
  test: ["CMD", "curl", "-f", "http://localhost:8080/health"]

# TCP port
healthcheck:
  test: ["CMD", "nc", "-z", "localhost", "5432"]

# Command execution
healthcheck:
  test: ["CMD", "pg_isready", "-U", "postgres"]

# Shell command
healthcheck:
  test: ["CMD-SHELL", "wget -q --spider http://localhost:80 || exit 1"]

Monitor Health Status

# Check health status of all containers
docker ps --format "table {{.Names}}\t{{.Status}}"

# Inspect health details
docker inspect --format='{{json .State.Health}}' <container> | jq '.'

# Watch for unhealthy containers
docker ps --filter "health=unhealthy"

---

Container Cleanup

Regular Maintenance

# Remove stopped containers
docker container prune -f

# Remove unused images
docker image prune -f

# Remove unused images (including tagged)
docker image prune -a -f

# Remove unused volumes (CAREFUL — data loss)
docker volume prune -f

# Remove unused networks
docker network prune -f

# Full cleanup (containers, images, networks — NOT volumes)
docker system prune -f

# Full cleanup INCLUDING volumes (DESTRUCTIVE)
docker system prune -a --volumes -f

Disk Usage

# Docker disk usage summary
docker system df

# Detailed breakdown
docker system df -v

---

Compose File Best Practices

Template for New Services

version: "3.8"

services:
  servicename:
    image: image:tag          # Pin to specific tag, not :latest for production
    container_name: servicename
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s
    environment:
      - TZ=Etc/UTC
    volumes:
      - servicename_data:/data
    ports:
      - "8080:8080"
    networks:
      - default
    logging:
      driver: json-file
      options:
        max-size: "10m"
        max-file: "3"

volumes:
  servicename_data:

networks:
  default:

Key Principles

1. Pin image tags — Use image:1.2.3 not image:latest for production
2. Always health check — Every service should have a health check
3. Always restart policy — unless-stopped or always
4. Log rotation — Set max-size and max-file to prevent disk fill
5. Named volumes — Use named volumes, not bind mounts, for data persistence
6. Timezone — Set TZ=Etc/UTC for consistent logs
7. Resource limits — Set memory/CPU limits for critical services

Resource Limits

services:
  myservice:
    deploy:
      resources:
        limits:
          memory: 512M
          cpus: "0.5"
        reservations:
          memory: 256M
          cpus: "0.25"

---

Rollback Strategies

Strategy 1: Image Tag Pinning

# Before update: note current tag
docker compose images

# Update compose file to new tag
# If it fails: revert compose file to old tag
docker compose up -d

Strategy 2: Docker Image Tagging

# Tag current image before updating
docker tag myimage:latest myimage:rollback
docker compose pull
docker compose up -d

# If it fails:
docker tag myimage:rollback myimage:latest
docker compose up -d

Strategy 3: Compose File Versioning

# Keep previous compose file
cp docker-compose.yml docker-compose.yml.bak

# Deploy new version
docker compose up -d

# If it fails:
cp docker-compose.yml.bak docker-compose.yml
docker compose up -d

---

Troubleshooting

Container Won't Start

# Check logs
docker compose logs <service>

# Check if port is already in use
ss -tlnp | grep <port>

# Check if image exists
docker images | grep <image>

# Try running interactively
docker compose run --rm <service> sh

Container Keeps Restarting

# Check restart count
docker inspect <container> --format='{{.RestartCount}}'

# Check exit code
docker inspect <container> --format='{{.State.ExitCode}}'

# Check OOM kill
docker inspect <container> --format='{{.State.OOMKilled}}'

# View last logs before crash
docker logs --tail=50 <container>

Out of Disk Space

# Check Docker disk usage
docker system df

# Identify large images
docker images --format "{{.Repository}}:{{.Tag}} {{.Size}}" | sort -k2 -h

# Clean up
docker system prune -f
docker image prune -a -f

---

Kai skill — Docker deployment and lifecycle management