dockerfile-skill

Dockerfile Generator Skill

Overview

This skill generates production-ready Dockerfiles through a 4-phase process:

1. Deep Analysis - Understand project structure, workspace, migrations, and build complexity
2. Generate - Create Dockerfile with migration handling and build optimization
3. Build & Fix - Validate through actual build, fix errors iteratively
4. Runtime Validation - Verify migrations ran, app works, database populated

Key Capabilities

• Workspace/Monorepo Support: pnpm workspace, Turborepo, npm workspaces
• Custom CLI Detection: Auto-detect custom build CLIs (turbo, nx, lerna, rush, or project-specific) and use correct syntax
• Git Hash Bypass: Detect and handle projects requiring git commit hash (GITHUB_SHA)
• Build-Time Env Vars: Auto-detect and add placeholders for Next.js SSG
• Error Pattern Database: 40+ known error patterns with automatic fixes
• Smart .dockerignore: Avoid excluding workspace-required files and CLI config dependencies
• Custom Entry Points: Support for custom server launchers
• Migration Detection: Auto-detect ORM, migrations, handle standalone mode
• Build Optimization: Skip heavy CI tasks (lint/type-check) to prevent OOM
• Runtime Validation: Verify migrations ran, database populated, app working
• Native Module Support: Auto-detect Rust/NAPI-RS modules, multi-architecture builds
• Static Asset Mapping: Detect backend's expected static paths and map frontend outputs
• External Services: Auto-detect PostgreSQL, Redis, MinIO, ManticoreSearch dependencies
• Zero Human Interaction: Auto-generate all config files including secrets

Usage

/dockerfile          # Analyze current directory
/dockerfile <github-url>    # Clone and analyze GitHub repo
/dockerfile <path>       # Analyze specific path

Quick Start

When invoked, ALWAYS follow this sequence:

1. Read and execute modules/analyze.md
2. Read and execute modules/generate.md
3. Read and execute modules/build-fix.md

Workflow

Phase 1: Deep Project Analysis

Load and execute: modules/analyze.md

Output: Structured project metadata including:

• Language / Framework / Package manager
• Build commands / Run commands / Port
• External dependencies (DB/Redis/S3)
• System library requirements
• Migration system detection (ORM, migration count, execution method)
• Build complexity analysis (heavy operations, memory risk)
• Complexity level (L1/L2/L3)

Phase 2: Generate Dockerfile

Load and execute: modules/generate.md

Input: Analysis result from Phase 1 Output:

• Dockerfile (with migration handling, build optimization)
• .dockerignore (workspace-aware)
• docker-compose.yml (if external services needed)
• .env.docker.local (auto-generated with test secrets)
• docker-entrypoint.sh (with migration execution)
• DOCKER.md (complete deployment guide)
• Environment variable documentation

Key Enhancements:

• Auto-detect Next.js Standalone + ORM → separate deps installation
• Auto-detect heavy build operations → optimized build command
• Auto-generate all config files → zero user input required

Phase 3: Build Validation (Closed Loop)

Load and execute: modules/build-fix.md

Process:

1. Execute docker buildx build --platform linux/amd64 --load
2. If success → Proceed to Phase 4
3. If failure → Parse error, match pattern, fix Dockerfile, retry
4. Max iterations based on complexity level

Phase 4: Runtime Validation

Critical Addition: Don't declare success until runtime verification passes!

Validation Steps:

1. Container Startup: docker-compose up -d and verify no crashes
2. Database Migration:

• Query database: psql -c "\dt" → verify tables exist
• Check migration count matches expected (e.g., 76/76)
• Verify no "relation does not exist" errors

3. Application Health:

• Test HTTP endpoint → 200/302/401 acceptable, 500 is failure
• Check logs for errors
• Verify health check endpoint

4. Success Criteria: Only declare success if ALL pass

Why This Matters:

• Previous: Declared success after docker build, but app didn't work at runtime
• Now: Verify migrations ran, database populated, app actually functional
• Prevents silent migration failures (e.g., standalone mode missing ORM deps)

Supporting Resources

• Templates: templates/ - Base Dockerfile templates by tech stack
• Error Patterns: knowledge/error-patterns.md - Known errors and fixes
• System Dependencies: knowledge/system-deps.md - NPM/Pip package → system library mapping
• Best Practices: knowledge/best-practices.md - Docker production best practices
• Output Format: examples/output-format.md - Expected output structure

Complexity Levels

Level	Criteria	Max Build Iterations
L1	Single language, no build step, no external services, no migrations	1
L2	Has build step, has external services (DB/Redis), simple migrations	3
L3	Monorepo, multi-language, complex dependencies, build-time env vars, complex migrations (76+)	5

Common Issues & Solutions

1. Database migrations not running - MOST CRITICAL

Symptom: relation "users" does not exist at runtime Cause: Migrations detected but never executed Prevention: Analysis phase Step 12 detects migrations and configures execution Fix:

• For Standalone + ORM: Install ORM deps separately
• Add runtime migration to entrypoint script
• Verify with psql -c "\dt" after container starts

2. Out of Memory during build

Symptom: Exit code 137, Killed, heap out of memory Cause: Build script includes lint/type-check for 39+ workspace packages Prevention: Analysis phase Step 13 detects heavy operations Fix: Skip CI tasks in Docker build, increase NODE_OPTIONS to 8192MB

3. Workspace files not found

Symptom: ENOENT: no such file or directory, open '/app/e2e/package.json' Cause: .dockerignore excludes workspace package.json files Fix: Use e2e/* instead of e2e, then !e2e/package.json

4. lockfile=false projects

Symptom: Cannot generate lockfile because lockfile is set to false Cause: Project has lockfile=false in .npmrc Fix: Use pnpm install instead of pnpm install --frozen-lockfile

5. Build-time env vars missing

Symptom: KEY_VAULTS_SECRET is not set Cause: Next.js SSG needs env vars at build time Fix: Add ARG/ENV placeholders in build stage

6. Node binary path

Symptom: spawn /bin/node ENOENT Cause: Scripts hardcode /bin/node but node:slim has it at /usr/local/bin/node Fix: Add RUN ln -sf /usr/local/bin/node /bin/node

7. ORM not found in Standalone mode

Symptom: Cannot find module 'drizzle-orm' at runtime Cause: Next.js standalone doesn't include all node_modules Prevention: Analysis phase detects standalone + ORM combination Fix: Install ORM separately in /deps and copy to final image

8. Wrong build command for monorepo with custom CLI

Symptom: Build succeeds but output files missing (e.g., assets-manifest.json not found) Cause: Using yarn workspace @scope/pkg build instead of detected custom CLI syntax Prevention: Analysis phase Step 14 detects custom CLI Fix: Use detected CLI syntax for all build commands

9. Git hash required but .git not in Docker context

Symptom: Failed to open git repo or nodegit errors Cause: Build tool requires git commit hash for versioning Prevention: Analysis phase Step 14 detects git hash dependency Fix: Set ENV GITHUB_SHA=docker-build to bypass git requirement

10. CLI config files excluded by .dockerignore

Symptom: CLI initialization (e.g., ${CLI_NAME} init) fails silently Cause: .prettierrc, .prettierignore, or other config files excluded Prevention: Analysis phase Step 14 detects config file dependencies Fix: Remove config files from .dockerignore exclusions

11. Static assets not found at runtime

Symptom: ENOENT: no such file or directory, open '/app/static/assets-manifest.json' Cause: Frontend builds to different path than backend expects Prevention: Analysis phase Step 14 detects static asset path mapping Fix: Copy frontend outputs to backend's expected path in Dockerfile

Success Criteria

A successful Dockerfile must:

Build Phase:

1. Build without errors (docker buildx build exits 0)
2. Image size reasonable (< 2GB for most apps)
3. Follow production best practices (multi-stage, non-root, fixed versions)
4. Include all necessary supporting files (.dockerignore, docker-compose.yml, etc.)
5. Handle all workspace/monorepo requirements

Runtime Phase - CRITICAL: 6. Container starts successfully (no crashes) 7. Database migrations execute successfully (if migrations detected) 8. Database tables created (verify with psql) 9. Application responds with valid HTTP codes (200/302/401, not 500) 10. No runtime errors in logs (no "relation does not exist", etc.)

DO NOT declare success if:

• Build passes but runtime fails
• Migrations detected but tables missing
• App returns 500 errors
• Logs show database relation errors

Post-Build Validation COMPREHENSIVE

After successful build, perform FULL validation:

# 1. Start services
docker-compose up -d
sleep 30 # Wait for startup

# 2. Check container status
docker-compose ps
# Expected: All containers UP and HEALTHY

# 3. Verify database migrations
if [ migrations_detected ]; then
 # List tables
 docker-compose exec postgres psql -U <user> -d <db> -c "\dt"
 # Expected: List of tables (users, sessions, etc.)
 # If "Did not find any relations" → FAIL

 # Count migrations
 MIGRATION_COUNT=$(docker-compose exec postgres psql -U <user> -d <db> -t -c "SELECT COUNT(*) FROM <migration_table>;")
 # Expected: Matches analysis count (e.g., 76)
fi

# 4. Test application health
HTTP_CODE=$(curl -s -o /dev/null -w "%{http_code}" http://localhost:3210)
# Expected: 200, 302, or 401
# Unacceptable: 500, 502, 503

if [ "$HTTP_CODE" = "500" ]; then
 echo "FAILURE: App returning 500 error"
 docker-compose logs app
 exit 1
fi

# 5. Check for errors in logs
docker-compose logs app | grep -i "error" | tail -20
# Should NOT contain:
# - "relation does not exist"
# - "table not found"
# - "Cannot find module"

# 6. Check image size
docker images <image-name>

# 7. Cleanup (if needed)
docker-compose down

Validation Checklist:

• Image built successfully
• Container started without crashes
• Database connection established
• Migrations executed (if applicable)
• Database tables exist (if applicable)
• HTTP endpoint returns valid status
• No errors in application logs
• Health check passes