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
| 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.
| 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.
| 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.
| 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.
| 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:
| 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:
| 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:
| 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:
| 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:
| 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:
| url | Checked URL or endpoint
| status | HTTP status code or check result
| responseTime | Time to respond in ms
| healthy | Boolean health status
Error Handling
| 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
| 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.
| 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
Definition of Done
Docker environment verified All images built successfully All containers running All health checks passing Access URLs provided Results returned to orchestrator
Version: 2.0.0 Last Updated: 2026-01-10