# Docker Local Dev

> Generate Docker Compose and Dockerfile configurations for local development through interactive Q&A. Supports single-app and monorepo PHP/Laravel, WordPress, Drupal, Joomla, Node.js, and Python stacks with live reload, dependency installer jobs, Nginx/reverse proxy routing, databases, Redis, queues, schedulers, and email testing. Use when designing local dev stacks that differ from optimized prod…

- **Type:** Skill
- **Install:** `agentstack add skill-thienanblog-awesome-ai-agent-skills-docker-local-dev`
- **Verified:** Pending review
- **Seller:** [thienanblog](https://agentstack.voostack.com/s/thienanblog)
- **Installs:** 0
- **Category:** [Databases](https://agentstack.voostack.com/c/databases)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [thienanblog](https://github.com/thienanblog)
- **Source:** https://github.com/thienanblog/awesome-ai-agent-skills/tree/main/skills/docker-local-dev

## Install

```sh
agentstack add skill-thienanblog-awesome-ai-agent-skills-docker-local-dev
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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:

```bash
# 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:**

```bash
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:

```bash
# 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:

```bash
# 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:
```bash
grep -E '^(CACHE_DRIVER|SESSION_DRIVER|QUEUE_CONNECTION)=' .env
```

**If Redis is NOT in use** (CACHE_DRIVER=file, SESSION_DRIVER=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:
```bash
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:
```bash
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:

```bash
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.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: flagged — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-thienanblog-awesome-ai-agent-skills-docker-local-dev
- Seller: https://agentstack.voostack.com/s/thienanblog
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.