home / skills / levnikolaevich / claude-code-skills / ln-783-container-launcher

ln-783-container-launcher skill

safe

/ln-783-container-launcher

This skill builds docker images, launches containers, and verifies health using native checks and retry strategies.

npx playbooks add skill levnikolaevich/claude-code-skills --skill ln-783-container-launcher

Review the files below or copy the command above to add this skill to your agents.

Files (2)

SKILL.md

6.6 KB

---
name: ln-783-container-launcher
description: Builds and launches Docker containers with health verification using best practices
---

> **Paths:** File paths (`shared/`, `references/`, `../ln-*`) are relative to skills repo root. If not found at CWD, locate this SKILL.md directory and go up one level for repo root.

# ln-783-container-launcher

**Type:** L3 Worker
**Category:** 7XX Project Bootstrap
**Parent:** ln-780-bootstrap-verifier

---

## 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 |
|----------|---------------|
| Called by ln-780 orchestrator | 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

---

## 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

Overview

This skill builds Docker images, launches containers, and verifies service health using Docker-native health checks and robust retry strategies. It parses docker-compose configuration, enforces startup order, and returns structured results with access URLs and cleanup instructions. The skill focuses on single-host container lifecycle for development and bootstrap workflows, not production orchestration.

How this skill works

The skill runs pre-flight checks (Docker daemon, compose file, ports, disk space), then parses docker-compose.yml to extract services, ports, healthchecks, and dependencies. It builds images as defined, launches containers in detached mode respecting depends_on and health conditions, and verifies health via native Docker status, HTTP probes, TCP checks, or container execs with exponential backoff. Finally it aggregates container statuses, health check results, access URLs, and runtime metrics into a report for the orchestrator.

When to use it

As part of a bootstrap orchestrator to prepare a local environment before testing
To bring up development stacks locally from docker-compose with health verification
When you need automated, repeatable container startup and status reporting
For single-host container launches where Kubernetes/Swarm are not applicable
When you require structured results and cleanup guidance after launch

Best practices

Prefer Docker-native healthcheck definitions in compose files for reliability
Keep build contexts small and leverage layer cache to speed rebuilds
Define exposed ports and meaningful health endpoints in service configs
Use depends_on with health conditionals for services that must wait
Collect and attach container logs automatically on failures for debugging

Example use cases

Start a local API + database stack and wait until endpoints report healthy
CI bootstrap step that builds images and verifies services before tests
Developer onboarding script that launches demo environments with access URLs
Integration with an orchestrator that needs a single-host environment ready
Quick smoke-run of a compose stack to validate configuration after changes

FAQ

Can this skill be used for production deployments?

No. It targets single-host development and bootstrap workflows. Use proper CI/CD and orchestration platforms for production.

What happens if a service has no healthcheck defined?

The skill falls back to external probes: HTTP GET for web services, TCP checks for ports, or container execs for internal checks, using retries and backoff.