Docker Local Dev

Docker Local Development Environment Generator

Overview

This skill helps you create optimized Docker development environments for your projects. It generates docker-compose.yml, Dockerfile, and related configurations through an interactive, question-driven workflow.

When to use this skill:

• Setting up a new Docker development environment
• Dockerizing an existing project for local development
• Adding services (database, Redis, email testing) to your Docker setup
• Updating or merging with existing Docker configurations

Key Principle: This skill ALWAYS asks questions before making decisions. You will be notified about each configuration choice and can adjust settings to match your exact needs.

Important Notice

This skill uses an interactive approach. Before generating any files, I will:

1. Run auto-detection scripts to identify your tech stack (saves AI tokens)
2. Present the detection results for your confirmation
3. Ask 10-15 clarifying questions about your preferences
4. Show you a preview before creating or modifying files

Why this approach? Docker configurations are project-specific. Asking questions ensures the setup matches YOUR requirements, not generic defaults. This prevents issues and saves debugging time later.

Core Design Defaults

• Treat local development and production as separate targets. Local prioritizes live reload, bind mounts, fast debug/test cycles, and optional debug tooling. Production prioritizes immutable images, small runtime layers, no bind mounts, no dev dependency installers, and scoped runtime secrets.
• Prefer bind-mounted source plus named dependency volumes for active development. For PHP/Node monorepos, one-shot dependency installer services are valid and intentional; they install vendor, node_modules, or package-manager stores into named volumes, exit with code 0, and may appear as stopped in Docker UIs.
• Use dependency installer services only for local/dev compose unless the user explicitly wants a production-like dev image. Production images should install dependencies during image build.
• Do not assume wildcard local domains. Prefer explicit *.localhost hostnames because host machines commonly resolve them to 127.0.0.1 without /etc/hosts changes. Ask whether wildcard routing is needed locally only when the user is actively testing wildcard behavior. If the user only needs production wildcard support, use explicit local hostnames and document production wildcard requirements separately.
• When frontend apps use same-origin /api proxying to the API, preserve that route through the local reverse proxy instead of introducing browser CORS/preflight requirements.
• Generalize examples for community-safe reuse. Use neutral local placeholders such as app.localhost, api.localhost, apps/web, and packages/ui; never copy private project names, customer names, private domains, internal paths, secrets, or production data into reusable skill content.
• For implementation details, read the relevant reference before generating files: service strategy in references/service-configuration-guide.md, domain/networking in references/networking-ports-guide.md, and verification in references/health-check-patterns.md.
• For host port tracking, use a per-user registry path, never a machine-specific project path. Resolve it as ${DOCKER_LOCAL_DEV_PORT_REGISTRY} when set; otherwise use ${XDG_STATE_HOME:-$HOME/.local/state}/docker-local-dev/HOST_PORT_REGISTRY.md. Read an existing registry before proposing host-exposed ports. Before creating or updating it, explain the exact path and scan root, then ask for confirmation because the registry may record local project names, service names, and exposed ports.

Quick Start

To generate a Docker development environment:

1. Navigate to your project root
2. Tell the AI: "Use the docker-local-dev skill to set up Docker"
3. Confirm or correct the auto-detected tech stack
4. Answer the configuration questions
5. Review and approve the generated files

Supported Tech Stacks

| Stack | Framework/CMS | Process Manager | Notes | |-------|--------------|-----------------|-------| | PHP | Laravel 10/11/12/13 | Supervisor | Queue workers, scheduler | | PHP | WordPress | WP-CLI | Debug plugins, error logging | | PHP | Drupal 10/11 | Drush | Development services | | PHP | Joomla 4/5 | - | CLI tools, debug mode | | Node.js | Express, NestJS, Next.js | PM2 or Supervisor | Hot reload support | | Python | Django, FastAPI, Flask | Celery, Supervisor | WSGI/ASGI servers |

Unsupported Stack? The skill will proceed with generic configuration and suggest contributing improvements. See CONTRIBUTING.md for details.

Interactive Workflow

Phase 0: Auto-Detection (Script-based)

Before using AI, run detection scripts to save tokens:

# The skill will run this automatically
./scripts/detect-stack.sh

Detection checks:

• composer.json → Laravel, PHP version
• wp-config.php, wp-content/ → WordPress
• core/, sites/default/ → Drupal
• configuration.php, administrator/ → Joomla
• package.json → Node.js, framework, version
• requirements.txt, pyproject.toml → Python, framework
• .env, config files → Database type, Redis usage

Present results to user:

I detected: Laravel 11 + PHP 8.3 + MySQL + Redis

Is this correct?
- Yes → proceed with detected settings
- No → I'll analyze further using AI

If stack is NOT officially supported:

I detected [stack] but this is not in our supported list.
The Docker setup may not be optimal.

Proceeding with generic configuration...

If this works for you, please consider contributing to improve support!
See: CONTRIBUTING.md

Phase 1: Initial Discovery

Check for existing Docker files:

1. Look for docker-compose.yml, docker-compose.yaml, Dockerfile
2. If found, ask:

``` I found existing Docker files:

• docker-compose.yml (modified 2 days ago)
• Dockerfile

How should I proceed?

1. Merge (preserve your custom settings, add new services)
2. Replace (backup existing, generate fresh)
3. Cancel (let me review first)

```

Backup strategy:

• Timestamped backups: docker-compose.yml.backup.2024-01-15-143022
• Never overwrite without backup

Phase 1.5: Naming Strategy

IMPORTANT: Ask about Docker naming before generating Compose files.

Container UIs such as OrbStack and Docker Desktop do not only show the container name. They also group containers by the Docker Compose project name and list child rows by service name. In monorepos or on machines with many stacks, generic names like web, app, or websocket become hard to scan.

Always ask:

How would you like this stack named in Docker UIs?

1. Project-prefixed names (recommended)
   - Compose project/group: `inventory-office-web`
   - Container name: `inventory-office-web`
   - Service names: explicit when helpful, otherwise role-based inside the project

2. Minimal names
   - Compose project/group: folder name
   - Container name: default Compose-generated name
   - Service names: short generic names like `web`, `app`, `db`

Recommended defaults for monorepos or multi-project machines:

• Set the top-level Compose name: field to an explicit project slug such as inventory-api, inventory-office-web, or inventory-websocket
• Set container_name: to the same explicit prefix pattern, for example inventory-api-app, inventory-office-web, inventory-websocket
• Prefer explicit single-service names when the whole stack is one app/service, for example office-web: or websocket:
• For multi-service stacks, role-based service names are acceptable under a clear project/group name, for example app, web, db, redis inside inventory-api

Rules:

• Never rely on the folder name alone for Compose grouping in monorepos
• Prefer kebab-case names
• Keep the same prefix across project name, image tags, and container names when possible
• If an existing stack already has a stable naming convention, preserve it unless the user asks to rename it

Phase 1.75: Monorepo Discovery

Detect monorepo/workspace layout before generating services:

find . -maxdepth 3 \( -name pnpm-workspace.yaml -o -name turbo.json -o -name nx.json -o -name lerna.json -o -name package.json -o -name composer.json \) -print
find . -maxdepth 2 -type d \( -name apps -o -name packages -o -name services \) -print

Ask monorepo-specific questions:

This looks like a monorepo/workspace.

Which apps should run in Docker?
- App path and role, for example apps/api, apps/web, services/worker
- Dev command for each app
- Internal port for each app
- Public local hostname, if any
- Shared packages that must live-reload
- Package manager and lockfile location

Recommended monorepo defaults:

• Use the repository root as build.context when Dockerfiles need shared packages or root lockfiles.
• Set app-specific dockerfile, working_dir, command, and dependency volumes per service.
• Mount the repo root only when workspace resolution or shared package live reload requires it; otherwise mount app paths narrowly.
• Keep top-level Compose name: explicit and service names role-based under that project.
• Do not leak real project names/domains in reusable examples; use neutral names such as api, web, admin, worker, app.localhost, and apps/*.

Phase 2: Tech Stack Confirmation

If auto-detection succeeded:

Detected configuration:
- Framework: Laravel 11
- PHP Version: 8.3
- Database: MySQL (from .env DB_CONNECTION)
- Redis: Yes (from .env REDIS_HOST)
- Queue: Yes (jobs table detected)

Please confirm or adjust these settings.

If auto-detection failed or unclear:

What is your primary tech stack?

1. PHP/Laravel
2. WordPress
3. Drupal
4. Joomla
5. Node.js (Express/NestJS/Next.js)
6. Python (Django/FastAPI/Flask)
7. Other (I'll try generic configuration)

Phase 3: CMS-Specific Questions

WordPress:

WordPress Development Options:

1. Install debug plugins?
   - Query Monitor (SQL queries, hooks, conditionals)
   - Debug Bar (debug info in admin bar)

2. Enable WP_DEBUG and error logging?
   - WP_DEBUG = true
   - WP_DEBUG_LOG = true
   - SCRIPT_DEBUG = true

Drupal:

Drupal Development Options:

1. Install Drush globally in container?
2. Enable development services (verbose errors, twig debug)?
3. Disable caching for development?

Joomla:

Joomla Development Options:

1. Enable debug mode?
2. Install Joomla CLI tools?

Phase 3.5: Existing Docker Images Scan

Before suggesting service versions, check locally available images to save disk space:

# The skill will run this automatically
./scripts/detect-images.sh

Present results to user:

I found these images already on your machine:

Databases:
- mysql:8.0.35 (2.3 GB)
- mariadb:11.2 (1.1 GB)

Using existing images saves disk space and download time.

Which database would you like to use?
1. mysql:8.0.35 (already downloaded - saves 2.3 GB)
2. mariadb:11.2 (already downloaded - saves 1.1 GB)
3. Different version (will download new image)
   → What version do you need for production compatibility?

If no existing images found:

No database images found locally.

Which database would you like to use?
1. MySQL 8.0 (recommended for Laravel/WordPress)
2. MariaDB 11 (MySQL-compatible, smaller)
3. PostgreSQL 16 (if your app requires it)

Same approach for other services:

• Check for existing Redis, PHP, Node, Nginx, Mailpit/MailHog images
• Suggest matching versions when available
• Always offer "different version" option for production compatibility

Phase 4: Service Configuration (Smart Recommendations)

IMPORTANT: Check actual usage before recommending services.

Before suggesting any optional service, verify if it's actually being used in the project:

# Check .env for actual service usage
grep -E '^(CACHE_DRIVER|CACHE_STORE|SESSION_DRIVER|QUEUE_CONNECTION|MAIL_MAILER)=' .env

Database Selection (always needed, use images from Phase 3.5):

Which database would you like to use?

1. MySQL 8.0 (recommended for Laravel/WordPress)
2. MariaDB 11 (MySQL-compatible, lighter)
3. PostgreSQL 16 (required for some apps)

Redis Configuration (check actual usage first):

First, check if Redis is actually used:

grep -E '^(CACHE_DRIVER|SESSION_DRIVER|QUEUE_CONNECTION)=' .env

If Redis is NOT in use (CACHEDRIVER=file, SESSIONDRIVER=file, QUEUE_CONNECTION=sync):

I noticed your .env configuration:
- CACHE_DRIVER=file (not using Redis for cache)
- SESSION_DRIVER=file (not using Redis for sessions)
- QUEUE_CONNECTION=sync (not using Redis for queues)

Redis is not currently used in your project.
Do you want to add Redis anyway?
1. No, skip Redis (recommended based on your config)
2. Yes, I plan to switch to Redis later

If Redis IS in use (any of the above = redis):

Do you need Redis?

1. Yes, for caching only
2. Yes, for caching + sessions
3. Yes, for caching + sessions + queues
4. No, I don't need Redis

Email Testing (check actual usage first):

First, check MAIL_MAILER setting:

grep -E '^MAIL_MAILER=' .env

If using log or array mailer:

Your MAIL_MAILER is set to 'log' (emails logged, not sent).
Do you want to add email testing service anyway?
1. No, skip email testing (recommended based on your config)
2. Yes, add Mailpit for testing

If using smtp or other mailer:

Which email testing service would you prefer?

1. Mailpit (modern, actively maintained, recommended)
   - Web UI: http://localhost:8025
   - SMTP: localhost:1025

2. MailHog (widely used, stable)
   - Web UI: http://localhost:8025
   - SMTP: localhost:1025

3. None (I'll configure email separately)

Background Task Processing (check actual usage first):

For Laravel, check if queues are actually used:

grep -E '^QUEUE_CONNECTION=' .env
# Also check if async jobs, failed jobs, queued listeners, or dispatch calls exist
find app -path '*/Jobs/*' -type f 2>/dev/null
grep -R "ShouldQueue\|queue:work\|dispatch(" app routes config 2>/dev/null

# If dependencies are installed, inspect scheduler tasks
php artisan schedule:list --no-interaction 2>/dev/null || true

If QUEUE_CONNECTION=sync:

Your QUEUE_CONNECTION is set to 'sync' (no background processing).
Do you need background task processing anyway?
1. No, skip queue workers (recommended based on your config)
2. Yes, I plan to switch to async queues later

If QUEUE_CONNECTION=database/redis:

Do you need background task processing?

1. Queue workers only (Supervisor)
2. Scheduler only (cron replacement via Supervisor)
3. Both queue workers and scheduler
4. No background processing needed

Laravel scheduler rule:

• A scheduler service is infrastructure support, not proof that scheduled tasks exist.
• If schedule:list shows no tasks, ask whether to add a scheduler service now or document it as production-ready but idle.
• In production compose, run queue workers and the scheduler as separate services from the web/API container.

For Node.js:

How do you want to manage Node.js processes?

1. PM2 (process manager with clustering, recommended)
2. Supervisor (simple process monitoring)
3. Direct node command (development only)

For Python:

Background task processing options:

1. Celery workers (for Django/FastAPI async tasks)
2. Supervisor for scheduled tasks (cron replacement)
3. Both Celery and scheduled tasks
4. No background processing needed

Phase 5: Port Exposure & Configuration

IMPORTANT: Ask about reverse proxy first before exposing ports.

Host Port Registry Preflight:

Before asking for or suggesting any host-exposed port, resolve and check the user's host port registry:

PORT_REGISTRY_FILE="${DOCKER_LOCAL_DEV_PORT_REGISTRY:-${XDG_STAT

…

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [thienanblog](https://github.com/thienanblog)
- **Source:** [thienanblog/awesome-ai-agent-skills](https://github.com/thienanblog/awesome-ai-agent-skills)
- **License:** Apache-2.0

Install and usage instructions live in the source repository linked above.