interface:
  display_name: Docker Project Foundations
  short_description: Guidance for initializing and structuring a Dockerized project.
  default_prompt: Use this skill when setting up or Dockerizing a project from scratch.
policy:
  allow_implicit_invocation: true

# Development-oriented compose.yaml
# Demonstrates Dockerized dependencies, health checks, bind mounts, and named volumes.
# The Postgres password fallback is for development-only one-command startup.
# Set POSTGRES_PASSWORD in .env to override it for local development.

services:
  app:
    build:
      context: .
      dockerfile: Dockerfile
      target: dev  # Use the dev stage of a multi-stage Dockerfile
    ports:
      - "127.0.0.1:3000:3000"  # Use 0.0.0.0 only when other devices need access
    environment:
      - DATABASE_URL=postgres://appuser:${POSTGRES_PASSWORD:-apppass}@db:5432/appdb
      - REDIS_URL=redis://cache:6379
      - NODE_ENV=development
    volumes:
      - ./src:/app/src        # Bind mount for live reload
      - /app/node_modules     # Anonymous volume to avoid overwriting installed deps
    depends_on:
      db:
        condition: service_healthy
      cache:
        condition: service_healthy

  db:
    image: postgres:17
    environment:
      - POSTGRES_USER=appuser
      - POSTGRES_PASSWORD=${POSTGRES_PASSWORD:-apppass}
      - POSTGRES_DB=appdb
    ports:
      - "127.0.0.1:5432:5432"  # Keep the development database local
    volumes:
      - db-data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U appuser -d appdb"]
      interval: 5s
      timeout: 5s
      retries: 5
    restart: unless-stopped

  cache:
    image: redis:7
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 5s
      timeout: 5s
      retries: 5
    restart: unless-stopped

volumes:
  db-data:

# Verification Checklist

Use this checklist to verify that generated Docker project setup follows the skill's guidance.

## Required files

- [ ] `.dockerignore` exists at the project root (or at each build context root in a multi-service setup).
- [ ] `Dockerfile` exists at the project root (or at each build context root).
- [ ] `compose.yaml` exists at the project root.

## .dockerignore

- [ ] Excludes `.git` directory.
- [ ] Excludes dependency caches (`node_modules/`, `__pycache__/`, `.venv/`, `vendor/`).
- [ ] Excludes IDE/editor configs (`.vscode/`, `.idea/`).
- [ ] Excludes secret files (`.env`, `*.pem`, `*.key`).
- [ ] Excludes root and nested npm credential files with `**/.npmrc`.
- [ ] Does not exclude files that the build actually needs (source code, dependency manifests).

## Dockerfile

- [ ] Base image uses a specific version tag, not `latest`.
- [ ] Base image uses a minimal variant (`-slim` or `-alpine`) where available.
- [ ] Dependency manifests are copied and installed before source code (layer caching).
- [ ] A non-root `USER` is set before `CMD`/`ENTRYPOINT`.
- [ ] No secrets or credentials are hardcoded (`ENV SECRET=...`, `ARG PASSWORD=...`).
- [ ] Neither `COPY` nor `ADD` includes `.npmrc`; both npm installation steps use an optional BuildKit secret mount instead.
- [ ] Public-package builds work without `.npmrc`; private-registry builds receive it through `--secret id=npmrc,src=<config-path>`. Never test with real credentials in image layers or logs.
- [ ] Multi-stage build is used when a build step exists (compile, bundle, transpile).
- [ ] Production stage does not contain dev tools, test frameworks, or build toolchains.

## compose.yaml

- [ ] File is named `compose.yaml`, not `docker-compose.yml`.
- [ ] Infrastructure dependencies (databases, caches, queues) are defined as Compose services, not expected to be installed on the host.
- [ ] `depends_on` uses `condition: service_healthy` for services that need readiness.
- [ ] Infrastructure services have `healthcheck` definitions.
- [ ] Persistent data uses named volumes, not bind mounts.
- [ ] Application source code uses bind mounts for development live-reload.
- [ ] Application and datastore credentials use Compose interpolation rather than literal values, including passwords embedded in connection URLs.
- [ ] Application ports bind to loopback by default; widening to other interfaces is an explicit development choice.
- [ ] Unauthenticated datastores are not published to the host and remain reachable only on the Compose network.
- [ ] Datastore ports needed by local host tools bind to loopback only.
- [ ] Development-only credential fallbacks are clearly labeled, use Compose interpolation, and document a `.env` override.
- [ ] No host-level install instructions (`brew install`, `apt install`) for services that should be containerized.

## Development vs production

- [ ] Development configuration uses bind mounts for source code.
- [ ] Production configuration does not mount source code.
- [ ] A single `Dockerfile` supports both via build stages or build arguments when feasible.

## Validation script

Run the bundled script from the project root before the broader smoke tests, with the script path resolved under the skill directory:

```bash
bash "<skill-dir>/scripts/verify-setup.sh" [--help]
```

Replace `<skill-dir>` with the absolute path of this skill's directory, the folder that contains `SKILL.md` and this `checks/` folder. Do not change into the skill directory to run it; the script checks the current directory.

It checks `.dockerignore`, `Dockerfile`, and `compose.yaml`, then validates the Compose configuration. Exit status is `0` on success or help, `1` for missing files or invalid Compose configuration, and `2` for invalid arguments.

## Validation commands

Run these to smoke-test the generated setup:

```bash
# Verify compose file is syntactically valid
docker compose config --quiet

# Verify the Dockerfile builds successfully
docker compose build

# Verify services start and become healthy
docker compose up -d
docker compose ps   # All services should show "healthy" or "running"

# Clean up
docker compose down -v
```

# Docker Project Structure Reference

## Standard single-service layout

```
project-root/
  .dockerignore
  Dockerfile
  compose.yaml
  src/
  ...
```

For most projects, all Docker files live at the project root. This is the simplest and most conventional layout.

## Multi-service layout

When a repository contains multiple independently built services (e.g., a monorepo with `frontend/` and `backend/`):

```
project-root/
  compose.yaml
  frontend/
    .dockerignore
    Dockerfile
    src/
  backend/
    .dockerignore
    Dockerfile
    src/
```

Each service gets its own `Dockerfile` and `.dockerignore` at the root of its build context. The `compose.yaml` stays at the repository root and references each service's build context:

```yaml
services:
  frontend:
    build:
      context: ./frontend
      dockerfile: Dockerfile
  backend:
    build:
      context: ./backend
      dockerfile: Dockerfile
```

## File naming conventions

| File | Correct name | Deprecated/incorrect alternatives |
|------|-------------|----------------------------------|
| Compose file | `compose.yaml` | `docker-compose.yml`, `docker-compose.yaml` |
| Dockerfile | `Dockerfile` | `dockerfile`, `Dockerfile.dev` (use stages instead) |
| Ignore file | `.dockerignore` | — |

## Build context considerations

The Docker build context is the directory tree sent to the Docker daemon during a build. Key rules:

- The `.dockerignore` file controls what is excluded from the build context.
- A smaller build context means faster builds. Aggressively exclude anything the build does not need.
- The build context root is set by the `context` field in `compose.yaml` or by the path argument to `docker build`.
- Files outside the build context cannot be referenced in a `Dockerfile` (no `COPY ../something`).

## Compose file organization

### Environment variables

Prefer inline `environment:` blocks for small numbers of variables. Use `env_file:` for larger configurations, but never commit files containing real secrets.

```yaml
services:
  app:
    environment:
      - DATABASE_URL=postgres://user:pass@db:5432/myapp
      - REDIS_URL=redis://cache:6379
```

### Volumes

- **Named volumes** for data that must survive container restarts (database storage):

```yaml
volumes:
  db-data:

services:
  db:
    volumes:
      - db-data:/var/lib/postgresql/data
```

- **Bind mounts** for source code during development:

```yaml
services:
  app:
    volumes:
      - ./src:/app/src
```

### Networks

For most single-project development setups, the default Compose network is sufficient. Do not create custom networks unless services need isolation from each other.

### Profiles

Use Compose profiles to group optional services (e.g., monitoring, debug tools) that are not needed in every development session:

```yaml
services:
  prometheus:
    profiles:
      - monitoring
    image: prom/prometheus:v3
```

Start with `docker compose --profile monitoring up` when needed.

## Secrets and credentials

- Never bake secrets into images (no `ENV SECRET_KEY=...` in a `Dockerfile`).
- Use environment variables or Docker secrets for runtime credentials.
- Add secret files (`.env`, `*.pem`, `credentials.json`) to `.dockerignore` and `.gitignore`.
- For development, use `env_file:` in Compose pointing to a `.env` file that is gitignored.

#!/usr/bin/env bash
# Verify Docker project setup. Run from the project root.
# Usage: bash "<skill-dir>/scripts/verify-setup.sh" [--help]
# <skill-dir> is the directory that contains this skill's SKILL.md.
set -euo pipefail

usage() {
    echo "Usage: bash \"<skill-dir>/scripts/verify-setup.sh\" [--help]"
    echo "Run from the project root; <skill-dir> is the directory that contains this skill's SKILL.md."
    echo "Checks: .dockerignore, Dockerfile, and compose.yaml exist; compose config passes."
}

if [[ "${1:-}" == "--help" && $# == 1 ]]; then
    usage
    exit 0
fi

if (( $# != 0 )); then
    usage >&2
    exit 2
fi

status=0

echo "Checking required files..."
for file in .dockerignore Dockerfile compose.yaml; do
    if [[ -f "$file" ]]; then
        echo "OK: $file"
    else
        echo "MISSING: $file" >&2
        status=1
    fi
done

if [[ -f compose.yaml ]]; then
    echo ""
    echo "Validating compose.yaml..."
    if docker compose config --quiet; then
        echo "OK: compose config valid"
    else
        echo "FAIL: compose config invalid" >&2
        status=1
    fi
fi

exit "$status"