tomevault-io 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
- Use native health checks when available - more reliable than external probes
- Implement retry with backoff - services need time to initialize
- Always collect logs on failure - essential for debugging
- Parse compose file for ports - do not hardcode port numbers
- 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
Source: levnikolaevich/claude-code-skills — distributed by TomeVault.