ln-783-container-launcher

---
name: ln-783-container-launcher
description: Builds and launches Docker containers with health verification. Use when validating that containerized services start correctly.
license: MIT
---

> **Paths:** File paths (`references/`, `../ln-*`) are relative to this skill directory.

# ln-783-container-launcher

**Type:** L3 Worker
**Category:** 7XX Project Bootstrap

---

## Purpose

Builds Docker images, launches containers, and performs comprehensive health verification using Docker native health checks and retry strategies.

**Scope:**
- Detect and validate docker-compose.yml configuration
- Build Docker images
- Launch containers with proper startup order
- Verify container health using native health checks
- Provide access URLs and cleanup instructions

**Out of Scope:**
- Building application code (handled by ln-781)
- Running tests (handled by ln-782)
- Container orchestration beyond single host (Kubernetes, Swarm)

---

## When to Use

| Scenario | Use This Skill |
|----------|---------------|
| Standalone-capable | Yes |
| Standalone container launch | Yes |
| Development environment setup | Yes |
| Production deployment | No, use proper CI/CD |

---

## Workflow

### Step 1: Pre-flight Checks

Verify Docker environment readiness.

| Check | Failure Action |
|-------|---------------|
| Docker daemon running | Report error with installation instructions |
| Docker Compose available | Report error, suggest installation |
| Compose file exists | Report error, list expected locations |
| Required ports free | Report conflict, suggest alternatives |
| Sufficient disk space | Warn if low space (<2GB free) |

### Step 2: Parse Compose Configuration

Extract service information from docker-compose.yml.

| Information | Purpose |
|-------------|---------|
| Service names | Track which containers to monitor |
| Exposed ports | Know which ports to check |
| Health check definitions | Use native health checks if defined |
| Dependencies (depends_on) | Understand startup order |
| Volume mounts | Verify paths exist |

### Step 3: Build Images

Build all images defined in compose file.

| Aspect | Strategy |
|--------|----------|
| Build context | Use paths from compose file |
| Build args | Pass through from compose configuration |
| Cache | Use Docker layer cache for speed |
| Failure | Report build errors with full log |

### Step 4: Launch Containers

Start containers with proper orchestration.

| Aspect | Strategy |
|--------|----------|
| Startup order | Respect depends_on and healthcheck conditions |
| Detached mode | Run in background |
| Network | Use compose-defined networks |
| Volumes | Mount all defined volumes |

### Step 5: Health Verification

Verify all containers are healthy using appropriate strategy.

**Strategy Selection:**

| Condition | Strategy |
|-----------|----------|
| Service has `healthcheck:` in compose | Use native Docker health status |
| Service has `depends_on: condition: service_healthy` | Wait for Docker health status |
| No healthcheck defined | Use external HTTP probe with retry |

**Retry Configuration:**

| Parameter | Value | Rationale |
|-----------|-------|-----------|
| Max attempts | 10 | Allow slow-starting services |
| Initial delay | 5s | Give containers time to start |
| Backoff | Exponential (5, 10, 20, 40s) | Avoid overwhelming services |
| Max total wait | 120s | Reasonable upper limit |

**Health Check Methods:**

| Method | When to Use |
|--------|------------|
| Docker health status | When container has healthcheck defined |
| HTTP GET to exposed port | For web services without healthcheck |
| Container exec | For services without exposed ports |
| TCP port check | For databases and message queues |

### Step 6: Report Results

Return structured results to orchestrator.

**Result Structure:**

| Field | Description |
|-------|-------------|
| containers | Array of container status objects |
| healthChecks | Array of health check results |
| accessUrls | Map of service name to access URL |
| overallStatus | healthy / unhealthy / partial |
| startupDuration | Time from launch to all healthy |

**Container Status Object:**

| Field | Description |
|-------|-------------|
| name | Container name |
| service | Service name from compose |
| status | running / exited / restarting |
| health | healthy / unhealthy / starting / none |
| port | Exposed port (if any) |
| startedAt | Container start timestamp |

**Health Check Result:**

| Field | Description |
|-------|-------------|
| url | Checked URL or endpoint |
| status | HTTP status code or check result |
| responseTime | Time to respond in ms |
| healthy | Boolean health status |

---

## Error Handling

| Error Type | Action |
|------------|--------|
| Docker daemon not running | Report with start instructions |
| Port already in use | Report conflict, suggest docker compose down first |
| Image build failed | Report with build logs |
| Container exited | Report with container logs |
| Health check timeout | Report with last known status and logs |
| Network unreachable | Check Docker network configuration |

---

## Options

| Option | Default | Description |
|--------|---------|-------------|
| keepRunning | true | Leave containers running after verification |
| stopAfter | false | Stop containers after successful verification |
| healthTimeout | 120 | Max seconds to wait for healthy status |
| showLogs | true | Show container logs on failure |
| buildFirst | true | Build images before starting |
| pullLatest | false | Pull base images before build |

---

## Cleanup Instructions

Provide user with cleanup commands in report.

| Action | Description |
|--------|-------------|
| Stop containers | Stop running containers, preserve data |
| Remove containers and networks | Clean up containers but keep volumes |
| Remove everything | Full cleanup including volumes and images |

---

## Critical Rules

1. **Use native health checks when available** - more reliable than external probes
2. **Implement retry with backoff** - services need time to initialize
3. **Always collect logs on failure** - essential for debugging
4. **Parse compose file for ports** - do not hardcode port numbers
5. **Respect depends_on order** - critical for database-dependent services

### Monitor Integration (Claude Code 2.1.98+)

**MANDATORY READ:** Load `references/monitor_integration_pattern.md`

For container health verification, use `Monitor` to stream container logs:

| Pattern | Command | timeout_ms |
|---------|---------|------------|
| Readiness signal | `docker compose logs -f 2>&1 \| grep --line-buffered -iE 'ready\|listening\|healthy\|started'` | `healthTimeout * 1000` |
| Error watch | `docker compose logs -f 2>&1 \| grep --line-buffered -iE 'error\|fatal\|panic\|exit'` | `healthTimeout * 1000` |

Use `persistent: true` if `keepRunning` is true and ongoing log monitoring is needed.
Fallback: if Monitor is unavailable, use retry loop with `sleep` + `curl` health check.

---

## Definition of Done

- [ ] Docker environment verified
- [ ] All images built successfully
- [ ] All containers running
- [ ] All health checks passing
- [ ] Access URLs provided
- [ ] Results returned to orchestrator

---

## Reference Files

- Parent: `../ln-780-bootstrap-verifier/SKILL.md`

---

**Version:** 2.0.0
**Last Updated:** 2026-01-10