Dockerfile Generator Skill

Overview

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

Deep Analysis - Understand project structure, workspace, migrations, and build complexity
Generate - Create Dockerfile with migration handling and build optimization
Build & Fix - Validate through actual build, fix errors iteratively
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:

Read and execute modules/analyze.md
Read and execute modules/generate.md
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:

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

Phase 4: Runtime Validation

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

Validation Steps:

Container Startup: docker-compose up -d and verify no crashes
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

Application Health:

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

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:

Build without errors (docker buildx build exits 0)
Image size reasonable (< 2GB for most apps)
Follow production best practices (multi-stage, non-root, fixed versions)
Include all necessary supporting files (.dockerignore, docker-compose.yml, etc.)
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

dockerfile-skill