docker-local-dev

What this skill does

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

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