[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M79NKHBMBMPJH7GZ7RSFC7BS":3,"skill-same:01M79NKHBMBMPJH7GZ7RSFC7BS":45},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":24,"commitSha":25,"skillDirectory":26,"forksCount":14,"repositoryHtmlUrl":27,"repositoryHomepageUrl":6,"ownerHtmlUrl":28,"ownerBlogUrl":6,"ownerDescription":29,"updatedAt":30,"install":31,"resources":44},"01M79NKHBMBMPJH7GZ7RSFC7BS","docker-patterns",null,"Docker and Docker Compose patterns for local development, hardened CLI installer harnesses, container security, networking, volumes, and multi-service orchestration. Use when creating or reviewing Dockerfiles and Compose services, testing installers across Linux distributions, or planning accurate native macOS and Windows validation.","JunMystery\u002FAgent-Guidance","JunMystery","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F161468934?v=4","01M79MTMV8F0BY8NK1A92RA8A0","Jun","01M79MTMWCFBKPHN5B25E6V20B",0,"MIT","https:\u002F\u002Fgithub.com\u002FJunMystery\u002FAgent-Guidance\u002Fblob\u002Fmain\u002Fskills\u002Fdocker-patterns\u002FSKILL.md",[],[],"2026-11-15 14:19:17",false,"---\nname: docker-patterns\ndescription: Docker and Docker Compose patterns for local development, hardened CLI installer harnesses, container security, networking, volumes, and multi-service orchestration. Use when creating or reviewing Dockerfiles and Compose services, testing installers across Linux distributions, or planning accurate native macOS and Windows validation.\n---\n\n# Docker Patterns\n\nDocker and Docker Compose best practices for containerized development.\n\n## Docker Compose for Local Development\n\n### Standard Web App Stack\n\n```yaml\n# docker-compose.yml\nservices:\n  app:\n    build:\n      context: .\n      target: dev                     # Use dev stage of multi-stage Dockerfile\n    ports:\n      - \"3000:3000\"\n    volumes:\n      - .:\u002Fapp                        # Bind mount for hot reload\n      - \u002Fapp\u002Fnode_modules             # Anonymous volume -- preserves container deps\n    environment:\n      - DATABASE_URL=postgres:\u002F\u002Fpostgres:postgres@db:5432\u002Fapp_dev\n      - REDIS_URL=redis:\u002F\u002Fredis:6379\u002F0\n      - NODE_ENV=development\n    depends_on:\n      db:\n        condition: service_healthy\n      redis:\n        condition: service_started\n    command: npm run dev\n\n  db:\n    image: postgres:16-alpine\n    ports:\n      - \"5432:5432\"\n    environment:\n      POSTGRES_USER: postgres\n      POSTGRES_PASSWORD: postgres\n      POSTGRES_DB: app_dev\n    volumes:\n      - pgdata:\u002Fvar\u002Flib\u002Fpostgresql\u002Fdata\n      - .\u002Fscripts\u002Finit-db.sql:\u002Fdocker-entrypoint-initdb.d\u002Finit.sql\n    healthcheck:\n      test: [\"CMD-SHELL\", \"pg_isready -U postgres\"]\n      interval: 5s\n      timeout: 3s\n      retries: 5\n\n  redis:\n    image: redis:7-alpine\n    ports:\n      - \"6379:6379\"\n    volumes:\n      - redisdata:\u002Fdata\n\n  mailpit:                            # Local email testing\n    image: axllent\u002Fmailpit\n    ports:\n      - \"8025:8025\"                   # Web UI\n      - \"1025:1025\"                   # SMTP\n\nvolumes:\n  pgdata:\n  redisdata:\n```\n\n### Development vs Production Dockerfile\n\n```dockerfile\n# Stage: dependencies\nFROM node:22-alpine AS deps\nWORKDIR \u002Fapp\nCOPY package.json package-lock.json .\u002F\nRUN npm ci\n\n# Stage: dev (hot reload, debug tools)\nFROM node:22-alpine AS dev\nWORKDIR \u002Fapp\nCOPY --from=deps \u002Fapp\u002Fnode_modules .\u002Fnode_modules\nCOPY . .\nEXPOSE 3000\nCMD [\"npm\", \"run\", \"dev\"]\n\n# Stage: build\nFROM node:22-alpine AS build\nWORKDIR \u002Fapp\nCOPY --from=deps \u002Fapp\u002Fnode_modules .\u002Fnode_modules\nCOPY . .\nRUN npm run build && npm prune --production\n\n# Stage: production (minimal image)\nFROM node:22-alpine AS production\nWORKDIR \u002Fapp\nRUN addgroup -g 1001 -S appgroup && adduser -S appuser -u 1001\nUSER appuser\nCOPY --from=build --chown=appuser:appgroup \u002Fapp\u002Fdist .\u002Fdist\nCOPY --from=build --chown=appuser:appgroup \u002Fapp\u002Fnode_modules .\u002Fnode_modules\nCOPY --from=build --chown=appuser:appgroup \u002Fapp\u002Fpackage.json .\u002F\nENV NODE_ENV=production\nEXPOSE 3000\nHEALTHCHECK --interval=30s --timeout=3s CMD wget -qO- http:\u002F\u002Flocalhost:3000\u002Fhealth || exit 1\nCMD [\"node\", \"dist\u002Fserver.js\"]\n```\n\n### Override Files\n\n```yaml\n# docker-compose.override.yml (auto-loaded, dev-only settings)\nservices:\n  app:\n    environment:\n      - DEBUG=app:*\n      - LOG_LEVEL=debug\n    ports:\n      - \"9229:9229\"                   # Node.js debugger\n\n# docker-compose.prod.yml (explicit for production)\nservices:\n  app:\n    build:\n      target: production\n    restart: always\n    deploy:\n      resources:\n        limits:\n          cpus: \"1.0\"\n          memory: 512M\n```\n\n```bash\n# Development (auto-loads override)\ndocker compose up\n\n# Production\ndocker compose -f docker-compose.yml -f docker-compose.prod.yml up -d\n```\n\n## Networking\n\n### Service Discovery\n\nServices in the same Compose network resolve by service name:\n```\n# From \"app\" container:\npostgres:\u002F\u002Fpostgres:postgres@db:5432\u002Fapp_dev    # \"db\" resolves to the db container\nredis:\u002F\u002Fredis:6379\u002F0                             # \"redis\" resolves to the redis container\n```\n\n### Custom Networks\n\n```yaml\nservices:\n  frontend:\n    networks:\n      - frontend-net\n\n  api:\n    networks:\n      - frontend-net\n      - backend-net\n\n  db:\n    networks:\n      - backend-net              # Only reachable from api, not frontend\n\nnetworks:\n  frontend-net:\n  backend-net:\n```\n\n### Exposing Only What's Needed\n\n```yaml\nservices:\n  db:\n    ports:\n      - \"127.0.0.1:5432:5432\"   # Only accessible from host, not network\n    # Omit ports entirely in production -- accessible only within Docker network\n```\n\n## Volume Strategies\n\n```yaml\nvolumes:\n  # Named volume: persists across container restarts, managed by Docker\n  pgdata:\n\n  # Bind mount: maps host directory into container (for development)\n  # - .\u002Fsrc:\u002Fapp\u002Fsrc\n\n  # Anonymous volume: preserves container-generated content from bind mount override\n  # - \u002Fapp\u002Fnode_modules\n```\n\n### Common Patterns\n\n```yaml\nservices:\n  app:\n    volumes:\n      - .:\u002Fapp                   # Source code (bind mount for hot reload)\n      - \u002Fapp\u002Fnode_modules        # Protect container's node_modules from host\n      - \u002Fapp\u002F.next               # Protect build cache\n\n  db:\n    volumes:\n      - pgdata:\u002Fvar\u002Flib\u002Fpostgresql\u002Fdata          # Persistent data\n      - .\u002Fscripts\u002Finit.sql:\u002Fdocker-entrypoint-initdb.d\u002Finit.sql  # Init scripts\n```\n\n## Container Security\n\n### Dockerfile Hardening\n\n```dockerfile\n# 1. Use specific tags (never :latest)\nFROM node:22.12-alpine3.20\n\n# 2. Run as non-root\nRUN addgroup -g 1001 -S app && adduser -S app -u 1001\nUSER app\n\n# 3. Drop capabilities (in compose)\n# 4. Read-only root filesystem where possible\n# 5. No secrets in image layers\n```\n\n### Compose Security\n\n```yaml\nservices:\n  app:\n    security_opt:\n      - no-new-privileges:true\n    read_only: true\n    tmpfs:\n      - \u002Ftmp\n      - \u002Fapp\u002F.cache\n    cap_drop:\n      - ALL\n    cap_add:\n      - NET_BIND_SERVICE          # Only if binding to ports \u003C 1024\n```\n\n### Secret Management\n\n```yaml\n# GOOD: Use environment variables (injected at runtime)\nservices:\n  app:\n    env_file:\n      - .env                     # Never commit .env to git\n    environment:\n      - API_KEY                  # Inherits from host environment\n\n# GOOD: Docker secrets (Swarm mode)\nsecrets:\n  db_password:\n    file: .\u002Fsecrets\u002Fdb_password.txt\n\nservices:\n  db:\n    secrets:\n      - db_password\n\n# BAD: Hardcoded in image\n# ENV API_KEY=sk-proj-xxxxx      # NEVER DO THIS\n```\n\n## Hardened CLI Installer Harnesses\n\nUse containers to test installer behavior against disposable project copies without allowing the test to mutate the source checkout.\n\n### Respect the Platform Boundary\n\n- Run real containers for Linux distributions such as Debian and Ubuntu.\n- macOS cannot run as a Docker container because Docker shares a Linux kernel. Run the same shell-free test entry point natively on macOS.\n- Windows containers require a Windows Docker engine. Run platform-independent logic on a native Windows CI runner and reserve Windows containers for a Windows host.\n- Keep a native Ubuntu\u002FmacOS\u002FWindows CI matrix for host-specific paths, command shims, quoting, and filesystem behavior.\n\nDo not claim that a Linux container validates macOS or Windows behavior.\n\n### Enforce the Isolation Contract\n\n- Pin base images by immutable digest and pin installed CLI versions.\n- Run as a non-root numeric UID\u002FGID when distro account names differ.\n- Mount the repository and source project read-only.\n- Copy the source project into a writable `tmpfs` workspace before any mutation.\n- Mount `\u002Fworkspace` with `noexec`, UID\u002FGID 1000, and `mode=0700` so only the\n  container user can inspect project data.\n- Keep npm and npx's executable cache at `NPM_CONFIG_CACHE=\u002Ftmp\u002Fnpm-cache` on\n  the executable `\u002Ftmp` mount. Its default size is 2 GiB and can be adjusted\n  with `ECC_TMPFS_SIZE`; `ECC_WORKSPACE_SIZE` separately controls the private\n  workspace mount.\n- Set `read_only: true`, `no-new-privileges:true`, `cap_drop: [ALL]`, and a finite `pids_limit`.\n- Keep the default real-CLI services on `network_mode: none`. Add network access\n  only through a visibly named opt-in service for an authenticated provider\n  session; never make it an accidental environment-driven default.\n- Create only the writable temporary paths the tool needs.\n- Do not pass host credentials into the container by default.\n- Default to a dry run and whitelist only the explicit `dry-run`, `install`,\n  `plugin`, and `shell` modes.\n- Use argument arrays or `spawnSync(..., { shell: false })` for cross-platform runners. Never interpolate project paths into a shell command.\n\n### Exercise the ECC Plugin Setup Harness\n\nUse `docker\u002Fplugin-setup\u002Fcompose.yaml` as the reference implementation. It provides:\n\n- `fixture-tests` for the focused install manifest, target, and executor suite.\n- `real-cli` for the pinned Debian-based generic Linux image.\n- `real-cli-ubuntu` for the pinned Ubuntu image.\n\nValidate the Compose model before building:\n\n```bash\ndocker compose -f docker\u002Fplugin-setup\u002Fcompose.yaml config --quiet\n```\n\nBuild both real Linux images:\n\n```bash\ndocker compose -f docker\u002Fplugin-setup\u002Fcompose.yaml \\\n  build real-cli real-cli-ubuntu\n```\n\nRun the safe default flow in each image:\n\n```bash\ndocker compose -p ecc-plugin-debian-test \\\n  -f docker\u002Fplugin-setup\u002Fcompose.yaml \\\n  run --rm -T real-cli dry-run\n\ndocker compose -p ecc-plugin-ubuntu-test \\\n  -f docker\u002Fplugin-setup\u002Fcompose.yaml \\\n  run --rm -T real-cli-ubuntu dry-run\n```\n\nThe dry run executes the current public command contract:\n\n```bash\necc install --profile core --target claude-project --dry-run --json\n```\n\nBefore that command runs, the container creates a locally packed npm artifact\nfrom the read-only checkout with `npm pack --ignore-scripts`. It extracts the\nself-created tarball under `\u002Ftmp`, validates the `ecc-universal` package name,\nrequired install manifests, and the confined `package.json` `bin.ecc` mapping,\nthen invokes the extracted `ecc` executable. The runtime stays on\n`network_mode: none`, does not execute package lifecycle scripts, and does not\nrely on host `node_modules`; its exact pinned production dependencies are\nalready present in the image.\n\nThe harness rejects an empty plan, a non-`claude-project` target, any operation\noutside `\u002Fworkspace\u002Fproject\u002F.claude`, or any dry run that creates the target\ndirectory. `install` performs the isolated apply twice, checks its managed\ninstall state, lists the installed target, and runs `doctor`.\n\n### Start, Open, Reconnect, and Clean Up a Named Session\n\nStart a detached container without `--rm` so leaving a terminal does not remove\nthe session:\n\n```bash\ndocker compose -p ecc-plugin-session \\\n  -f docker\u002Fplugin-setup\u002Fcompose.yaml \\\n  run --detach --name ecc-plugin-shell real-cli shell\n```\n\nThe container copies the read-only fixture to the stable private directory\n`\u002Fworkspace\u002Fproject`. Confirm it is running, then emit the Docker side of the\nterminal-opener v1 data contract:\n\n```bash\ndocker inspect --format '{{.State.Running}}' ecc-plugin-shell\nnode docker\u002Fplugin-setup\u002Finteractive-plan.js \\\n  --container ecc-plugin-shell \\\n  --workdir \u002Fworkspace\u002Fproject \\\n  --json \\\n  -- bash\n```\n\nThe JSON result has exactly an `executable` and `argv` boundary (plus\n`contractVersion: 1`): the executable is `docker`, and argv begins with\n`exec`, `-it`, and `-w`. Pass that data to the separate terminal-opener skill\nwhen it is installed. This Docker harness deliberately does not import a\nterminal adapter, interpolate a shell command, or manage a host GUI process.\nUntil then, open the same PTY in the current host terminal directly:\n\n```bash\ndocker exec -it -w \u002Fworkspace\u002Fproject ecc-plugin-shell bash\n```\n\nExit the shell without stopping the detached container. Reconnect with the\nsame `docker exec -it` command. When finished, remove the exact named container\nand its Compose project resources:\n\n```bash\ndocker rm --force ecc-plugin-shell\ndocker compose -p ecc-plugin-session \\\n  -f docker\u002Fplugin-setup\u002Fcompose.yaml \\\n  down --remove-orphans\n```\n\nHost credentials are absent by default and credential directories are never\nmounted. The default service also has no network access. When an authenticated\nprovider session genuinely needs a network, build `real-cli` first and then opt\nin visibly with `docker compose -f docker\u002Fplugin-setup\u002Fcompose.yaml\n--profile networked run --service-ports real-cli-networked shell`. The\n`--service-ports` flag publishes the service's loopback callback mapping.\nPrefer authenticating inside that disposable session. If a CI run must\ninherit a host environment credential, make that opt-in at invocation with an\nexplicit Compose `--env NAME` flag, understand that the value is inspectable\nand can be exfiltrated for the container lifetime, and remove the exact named\ncontainer immediately after.\n\n### Authenticate Codex Inside the Networked Session\n\n`codex login` binds its OAuth callback server to `127.0.0.1:1455` inside the\ncontainer. A Docker port publish forwards to the container interface, not\nloopback, so the host browser's redirect to `http:\u002F\u002Flocalhost:1455` is refused\nwithout a bridge. The `real-cli-networked` service publishes host\n`127.0.0.1:1455` to container port `1456`; bridge that port to loopback before\nlogging in:\n\n```bash\n(\n  set -e\n  npm install --global @openai\u002Fcodex@0.162.0   # the harness image does not ship codex\n  node \u002Fecc\u002Fdocker\u002Fplugin-setup\u002Fcodex-auth-relay.js &\n  relay_pid=$!\n  trap 'kill \"$relay_pid\" 2>\u002Fdev\u002Fnull || true; wait \"$relay_pid\" 2>\u002Fdev\u002Fnull || true' EXIT\n  codex login\n)\n```\n\nThe networked service sets `NPM_CONFIG_PREFIX=\u002Ftmp\u002Fecc-npm` and adds its `bin`\ndirectory to `PATH`. This keeps the pinned installation writable for UID 1000\non the executable `\u002Ftmp` mount while the root filesystem remains read-only.\n\nComplete the sign-in in the host browser. Each attempt mints a fresh\n`state`\u002F`code`, so always follow the newest printed link. The token stays in\nthe disposable container's `~\u002F.codex\u002Fauth.json`; removing the named container\ndeletes that credential copy. The login block stops the relay on success or failure.\nOnly one container can hold host port 1455 at a time\nbecause the OAuth redirect targets a fixed port.\n\nThe host publish is restricted to loopback. Inside the container, the relay\nlistens on all interfaces so Docker can forward to it; other containers on the\nsame bridge network can reach it while it runs. Use a dedicated network without\nuntrusted peers for this login, and remove the exact named container after use.\nIdle callback connections close after 30 seconds.\n\nRun the same focused suite natively on the host:\n\n```bash\nnpm run test:plugin-setup-platform\n```\n\nInspect the produced identity and environment before trusting the image:\n\n```bash\ndocker image inspect ecc-plugin-setup:debian ecc-plugin-setup:ubuntu\n```\n\nClean each named test project without deleting unrelated volumes or images:\n\n```bash\ndocker compose -p ecc-plugin-debian-test \\\n  -f docker\u002Fplugin-setup\u002Fcompose.yaml down --remove-orphans\ndocker compose -p ecc-plugin-ubuntu-test \\\n  -f docker\u002Fplugin-setup\u002Fcompose.yaml down --remove-orphans\n```\n\n## .dockerignore\n\n```\nnode_modules\n.git\n.env\n.env.*\ndist\ncoverage\n*.log\n.next\n.cache\ndocker-compose*.yml\nDockerfile*\nREADME.md\ntests\u002F\n```\n\n## Debugging\n\n### Common Commands\n\n```bash\n# View logs\ndocker compose logs -f app           # Follow app logs\ndocker compose logs --tail=50 db     # Last 50 lines from db\n\n# Execute commands in running container\ndocker compose exec app sh           # Shell into app\ndocker compose exec db psql -U postgres  # Connect to postgres\n\n# Inspect\ndocker compose ps                     # Running services\ndocker compose top                    # Processes in each container\ndocker stats                          # Resource usage\n\n# Rebuild\ndocker compose up --build             # Rebuild images\ndocker compose build --no-cache app   # Force full rebuild\n\n# Clean up\ndocker compose down                   # Stop and remove containers\ndocker compose down -v                # Also remove volumes (DESTRUCTIVE)\ndocker system prune                   # Remove unused images\u002Fcontainers\n```\n\n### Debugging Network Issues\n\n```bash\n# Check DNS resolution inside container\ndocker compose exec app nslookup db\n\n# Check connectivity\ndocker compose exec app wget -qO- http:\u002F\u002Fapi:3000\u002Fhealth\n\n# Inspect network\ndocker network ls\ndocker network inspect \u003Cproject>_default\n```\n\n## Anti-Patterns\n\n```\n# BAD: Using docker compose in production without orchestration\n# Use Kubernetes, ECS, or Docker Swarm for production multi-container workloads\n\n# BAD: Storing data in containers without volumes\n# Containers are ephemeral -- all data lost on restart without volumes\n\n# BAD: Running as root\n# Always create and use a non-root user\n\n# BAD: Using :latest tag\n# Pin to specific versions for reproducible builds\n\n# BAD: One giant container with all services\n# Separate concerns: one process per container\n\n# BAD: Putting secrets in docker-compose.yml\n# Use .env files (gitignored) or Docker secrets\n```\n","# Docker Patterns\n\nDocker and Docker Compose best practices for containerized development.\n\n## Docker Compose for Local Development\n\n### Standard Web App Stack\n\n```yaml\n# docker-compose.yml\nservices:\n  app:\n    build:\n      context: .\n      target: dev                     # Use dev stage of multi-stage Dockerfile\n    ports:\n      - \"3000:3000\"\n    volumes:\n      - .:\u002Fapp                        # Bind mount for hot reload\n      - \u002Fapp\u002Fnode_modules             # Anonymous volume -- preserves container deps\n    environment:\n      - DATABASE_URL=postgres:\u002F\u002Fpostgres:postgres@db:5432\u002Fapp_dev\n      - REDIS_URL=redis:\u002F\u002Fredis:6379\u002F0\n      - NODE_ENV=development\n    depends_on:\n      db:\n        condition: service_healthy\n      redis:\n        condition: service_started\n    command: npm run dev\n\n  db:\n    image: postgres:16-alpine\n    ports:\n      - \"5432:5432\"\n    environment:\n      POSTGRES_USER: postgres\n      POSTGRES_PASSWORD: postgres\n      POSTGRES_DB: app_dev\n    volumes:\n      - pgdata:\u002Fvar\u002Flib\u002Fpostgresql\u002Fdata\n      - .\u002Fscripts\u002Finit-db.sql:\u002Fdocker-entrypoint-initdb.d\u002Finit.sql\n    healthcheck:\n      test: [\"CMD-SHELL\", \"pg_isready -U postgres\"]\n      interval: 5s\n      timeout: 3s\n      retries: 5\n\n  redis:\n    image: redis:7-alpine\n    ports:\n      - \"6379:6379\"\n    volumes:\n      - redisdata:\u002Fdata\n\n  mailpit:                            # Local email testing\n    image: axllent\u002Fmailpit\n    ports:\n      - \"8025:8025\"                   # Web UI\n      - \"1025:1025\"                   # SMTP\n\nvolumes:\n  pgdata:\n  redisdata:\n```\n\n### Development vs Production Dockerfile\n\n```dockerfile\n# Stage: dependencies\nFROM node:22-alpine AS deps\nWORKDIR \u002Fapp\nCOPY package.json package-lock.json .\u002F\nRUN npm ci\n\n# Stage: dev (hot reload, debug tools)\nFROM node:22-alpine AS dev\nWORKDIR \u002Fapp\nCOPY --from=deps \u002Fapp\u002Fnode_modules .\u002Fnode_modules\nCOPY . .\nEXPOSE 3000\nCMD [\"npm\", \"run\", \"dev\"]\n\n# Stage: build\nFROM node:22-alpine AS build\nWORKDIR \u002Fapp\nCOPY --from=deps \u002Fapp\u002Fnode_modules .\u002Fnode_modules\nCOPY . .\nRUN npm run build && npm prune --production\n\n# Stage: production (minimal image)\nFROM node:22-alpine AS production\nWORKDIR \u002Fapp\nRUN addgroup -g 1001 -S appgroup && adduser -S appuser -u 1001\nUSER appuser\nCOPY --from=build --chown=appuser:appgroup \u002Fapp\u002Fdist .\u002Fdist\nCOPY --from=build --chown=appuser:appgroup \u002Fapp\u002Fnode_modules .\u002Fnode_modules\nCOPY --from=build --chown=appuser:appgroup \u002Fapp\u002Fpackage.json .\u002F\nENV NODE_ENV=production\nEXPOSE 3000\nHEALTHCHECK --interval=30s --timeout=3s CMD wget -qO- http:\u002F\u002Flocalhost:3000\u002Fhealth || exit 1\nCMD [\"node\", \"dist\u002Fserver.js\"]\n```\n\n### Override Files\n\n```yaml\n# docker-compose.override.yml (auto-loaded, dev-only settings)\nservices:\n  app:\n    environment:\n      - DEBUG=app:*\n      - LOG_LEVEL=debug\n    ports:\n      - \"9229:9229\"                   # Node.js debugger\n\n# docker-compose.prod.yml (explicit for production)\nservices:\n  app:\n    build:\n      target: production\n    restart: always\n    deploy:\n      resources:\n        limits:\n          cpus: \"1.0\"\n          memory: 512M\n```\n\n```bash\n# Development (auto-loads override)\ndocker compose up\n\n# Production\ndocker compose -f docker-compose.yml -f docker-compose.prod.yml up -d\n```\n\n## Networking\n\n### Service Discovery\n\nServices in the same Compose network resolve by service name:\n```\n# From \"app\" container:\npostgres:\u002F\u002Fpostgres:postgres@db:5432\u002Fapp_dev    # \"db\" resolves to the db container\nredis:\u002F\u002Fredis:6379\u002F0                             # \"redis\" resolves to the redis container\n```\n\n### Custom Networks\n\n```yaml\nservices:\n  frontend:\n    networks:\n      - frontend-net\n\n  api:\n    networks:\n      - frontend-net\n      - backend-net\n\n  db:\n    networks:\n      - backend-net              # Only reachable from api, not frontend\n\nnetworks:\n  frontend-net:\n  backend-net:\n```\n\n### Exposing Only What's Needed\n\n```yaml\nservices:\n  db:\n    ports:\n      - \"127.0.0.1:5432:5432\"   # Only accessible from host, not network\n    # Omit ports entirely in production -- accessible only within Docker network\n```\n\n## Volume Strategies\n\n```yaml\nvolumes:\n  # Named volume: persists across container restarts, managed by Docker\n  pgdata:\n\n  # Bind mount: maps host directory into container (for development)\n  # - .\u002Fsrc:\u002Fapp\u002Fsrc\n\n  # Anonymous volume: preserves container-generated content from bind mount override\n  # - \u002Fapp\u002Fnode_modules\n```\n\n### Common Patterns\n\n```yaml\nservices:\n  app:\n    volumes:\n      - .:\u002Fapp                   # Source code (bind mount for hot reload)\n      - \u002Fapp\u002Fnode_modules        # Protect container's node_modules from host\n      - \u002Fapp\u002F.next               # Protect build cache\n\n  db:\n    volumes:\n      - pgdata:\u002Fvar\u002Flib\u002Fpostgresql\u002Fdata          # Persistent data\n      - .\u002Fscripts\u002Finit.sql:\u002Fdocker-entrypoint-initdb.d\u002Finit.sql  # Init scripts\n```\n\n## Container Security\n\n### Dockerfile Hardening\n\n```dockerfile\n# 1. Use specific tags (never :latest)\nFROM node:22.12-alpine3.20\n\n# 2. Run as non-root\nRUN addgroup -g 1001 -S app && adduser -S app -u 1001\nUSER app\n\n# 3. Drop capabilities (in compose)\n# 4. Read-only root filesystem where possible\n# 5. No secrets in image layers\n```\n\n### Compose Security\n\n```yaml\nservices:\n  app:\n    security_opt:\n      - no-new-privileges:true\n    read_only: true\n    tmpfs:\n      - \u002Ftmp\n      - \u002Fapp\u002F.cache\n    cap_drop:\n      - ALL\n    cap_add:\n      - NET_BIND_SERVICE          # Only if binding to ports \u003C 1024\n```\n\n### Secret Management\n\n```yaml\n# GOOD: Use environment variables (injected at runtime)\nservices:\n  app:\n    env_file:\n      - .env                     # Never commit .env to git\n    environment:\n      - API_KEY                  # Inherits from host environment\n\n# GOOD: Docker secrets (Swarm mode)\nsecrets:\n  db_password:\n    file: .\u002Fsecrets\u002Fdb_password.txt\n\nservices:\n  db:\n    secrets:\n      - db_password\n\n# BAD: Hardcoded in image\n# ENV API_KEY=sk-proj-xxxxx      # NEVER DO THIS\n```\n\n## Hardened CLI Installer Harnesses\n\nUse containers to test installer behavior against disposable project copies without allowing the test to mutate the source checkout.\n\n### Respect the Platform Boundary\n\n- Run real containers for Linux distributions such as Debian and Ubuntu.\n- macOS cannot run as a Docker container because Docker shares a Linux kernel. Run the same shell-free test entry point natively on macOS.\n- Windows containers require a Windows Docker engine. Run platform-independent logic on a native Windows CI runner and reserve Windows containers for a Windows host.\n- Keep a native Ubuntu\u002FmacOS\u002FWindows CI matrix for host-specific paths, command shims, quoting, and filesystem behavior.\n\nDo not claim that a Linux container validates macOS or Windows behavior.\n\n### Enforce the Isolation Contract\n\n- Pin base images by immutable digest and pin installed CLI versions.\n- Run as a non-root numeric UID\u002FGID when distro account names differ.\n- Mount the repository and source project read-only.\n- Copy the source project into a writable `tmpfs` workspace before any mutation.\n- Mount `\u002Fworkspace` with `noexec`, UID\u002FGID 1000, and `mode=0700` so only the\n  container user can inspect project data.\n- Keep npm and npx's executable cache at `NPM_CONFIG_CACHE=\u002Ftmp\u002Fnpm-cache` on\n  the executable `\u002Ftmp` mount. Its default size is 2 GiB and can be adjusted\n  with `ECC_TMPFS_SIZE`; `ECC_WORKSPACE_SIZE` separately controls the private\n  workspace mount.\n- Set `read_only: true`, `no-new-privileges:true`, `cap_drop: [ALL]`, and a finite `pids_limit`.\n- Keep the default real-CLI services on `network_mode: none`. Add network access\n  only through a visibly named opt-in service for an authenticated provider\n  session; never make it an accidental environment-driven default.\n- Create only the writable temporary paths the tool needs.\n- Do not pass host credentials into the container by default.\n- Default to a dry run and whitelist only the explicit `dry-run`, `install`,\n  `plugin`, and `shell` modes.\n- Use argument arrays or `spawnSync(..., { shell: false })` for cross-platform runners. Never interpolate project paths into a shell command.\n\n### Exercise the ECC Plugin Setup Harness\n\nUse `docker\u002Fplugin-setup\u002Fcompose.yaml` as the reference implementation. It provides:\n\n- `fixture-tests` for the focused install manifest, target, and executor suite.\n- `real-cli` for the pinned Debian-based generic Linux image.\n- `real-cli-ubuntu` for the pinned Ubuntu image.\n\nValidate the Compose model before building:\n\n```bash\ndocker compose -f docker\u002Fplugin-setup\u002Fcompose.yaml config --quiet\n```\n\nBuild both real Linux images:\n\n```bash\ndocker compose -f docker\u002Fplugin-setup\u002Fcompose.yaml \\\n  build real-cli real-cli-ubuntu\n```\n\nRun the safe default flow in each image:\n\n```bash\ndocker compose -p ecc-plugin-debian-test \\\n  -f docker\u002Fplugin-setup\u002Fcompose.yaml \\\n  run --rm -T real-cli dry-run\n\ndocker compose -p ecc-plugin-ubuntu-test \\\n  -f docker\u002Fplugin-setup\u002Fcompose.yaml \\\n  run --rm -T real-cli-ubuntu dry-run\n```\n\nThe dry run executes the current public command contract:\n\n```bash\necc install --profile core --target claude-project --dry-run --json\n```\n\nBefore that command runs, the container creates a locally packed npm artifact\nfrom the read-only checkout with `npm pack --ignore-scripts`. It extracts the\nself-created tarball under `\u002Ftmp`, validates the `ecc-universal` package name,\nrequired install manifests, and the confined `package.json` `bin.ecc` mapping,\nthen invokes the extracted `ecc` executable. The runtime stays on\n`network_mode: none`, does not execute package lifecycle scripts, and does not\nrely on host `node_modules`; its exact pinned production dependencies are\nalready present in the image.\n\nThe harness rejects an empty plan, a non-`claude-project` target, any operation\noutside `\u002Fworkspace\u002Fproject\u002F.claude`, or any dry run that creates the target\ndirectory. `install` performs the isolated apply twice, checks its managed\ninstall state, lists the installed target, and runs `doctor`.\n\n### Start, Open, Reconnect, and Clean Up a Named Session\n\nStart a detached container without `--rm` so leaving a terminal does not remove\nthe session:\n\n```bash\ndocker compose -p ecc-plugin-session \\\n  -f docker\u002Fplugin-setup\u002Fcompose.yaml \\\n  run --detach --name ecc-plugin-shell real-cli shell\n```\n\nThe container copies the read-only fixture to the stable private directory\n`\u002Fworkspace\u002Fproject`. Confirm it is running, then emit the Docker side of the\nterminal-opener v1 data contract:\n\n```bash\ndocker inspect --format '{{.State.Running}}' ecc-plugin-shell\nnode docker\u002Fplugin-setup\u002Finteractive-plan.js \\\n  --container ecc-plugin-shell \\\n  --workdir \u002Fworkspace\u002Fproject \\\n  --json \\\n  -- bash\n```\n\nThe JSON result has exactly an `executable` and `argv` boundary (plus\n`contractVersion: 1`): the executable is `docker`, and argv begins with\n`exec`, `-it`, and `-w`. Pass that data to the separate terminal-opener skill\nwhen it is installed. This Docker harness deliberately does not import a\nterminal adapter, interpolate a shell command, or manage a host GUI process.\nUntil then, open the same PTY in the current host terminal directly:\n\n```bash\ndocker exec -it -w \u002Fworkspace\u002Fproject ecc-plugin-shell bash\n```\n\nExit the shell without stopping the detached container. Reconnect with the\nsame `docker exec -it` command. When finished, remove the exact named container\nand its Compose project resources:\n\n```bash\ndocker rm --force ecc-plugin-shell\ndocker compose -p ecc-plugin-session \\\n  -f docker\u002Fplugin-setup\u002Fcompose.yaml \\\n  down --remove-orphans\n```\n\nHost credentials are absent by default and credential directories are never\nmounted. The default service also has no network access. When an authenticated\nprovider session genuinely needs a network, build `real-cli` first and then opt\nin visibly with `docker compose -f docker\u002Fplugin-setup\u002Fcompose.yaml\n--profile networked run --service-ports real-cli-networked shell`. The\n`--service-ports` flag publishes the service's loopback callback mapping.\nPrefer authenticating inside that disposable session. If a CI run must\ninherit a host environment credential, make that opt-in at invocation with an\nexplicit Compose `--env NAME` flag, understand that the value is inspectable\nand can be exfiltrated for the container lifetime, and remove the exact named\ncontainer immediately after.\n\n### Authenticate Codex Inside the Networked Session\n\n`codex login` binds its OAuth callback server to `127.0.0.1:1455` inside the\ncontainer. A Docker port publish forwards to the container interface, not\nloopback, so the host browser's redirect to `http:\u002F\u002Flocalhost:1455` is refused\nwithout a bridge. The `real-cli-networked` service publishes host\n`127.0.0.1:1455` to container port `1456`; bridge that port to loopback before\nlogging in:\n\n```bash\n(\n  set -e\n  npm install --global @openai\u002Fcodex@0.162.0   # the harness image does not ship codex\n  node \u002Fecc\u002Fdocker\u002Fplugin-setup\u002Fcodex-auth-relay.js &\n  relay_pid=$!\n  trap 'kill \"$relay_pid\" 2>\u002Fdev\u002Fnull || true; wait \"$relay_pid\" 2>\u002Fdev\u002Fnull || true' EXIT\n  codex login\n)\n```\n\nThe networked service sets `NPM_CONFIG_PREFIX=\u002Ftmp\u002Fecc-npm` and adds its `bin`\ndirectory to `PATH`. This keeps the pinned installation writable for UID 1000\non the executable `\u002Ftmp` mount while the root filesystem remains read-only.\n\nComplete the sign-in in the host browser. Each attempt mints a fresh\n`state`\u002F`code`, so always follow the newest printed link. The token stays in\nthe disposable container's `~\u002F.codex\u002Fauth.json`; removing the named container\ndeletes that credential copy. The login block stops the relay on success or failure.\nOnly one container can hold host port 1455 at a time\nbecause the OAuth redirect targets a fixed port.\n\nThe host publish is restricted to loopback. Inside the container, the relay\nlistens on all interfaces so Docker can forward to it; other containers on the\nsame bridge network can reach it while it runs. Use a dedicated network without\nuntrusted peers for this login, and remove the exact named container after use.\nIdle callback connections close after 30 seconds.\n\nRun the same focused suite natively on the host:\n\n```bash\nnpm run test:plugin-setup-platform\n```\n\nInspect the produced identity and environment before trusting the image:\n\n```bash\ndocker image inspect ecc-plugin-setup:debian ecc-plugin-setup:ubuntu\n```\n\nClean each named test project without deleting unrelated volumes or images:\n\n```bash\ndocker compose -p ecc-plugin-debian-test \\\n  -f docker\u002Fplugin-setup\u002Fcompose.yaml down --remove-orphans\ndocker compose -p ecc-plugin-ubuntu-test \\\n  -f docker\u002Fplugin-setup\u002Fcompose.yaml down --remove-orphans\n```\n\n## .dockerignore\n\n```\nnode_modules\n.git\n.env\n.env.*\ndist\ncoverage\n*.log\n.next\n.cache\ndocker-compose*.yml\nDockerfile*\nREADME.md\ntests\u002F\n```\n\n## Debugging\n\n### Common Commands\n\n```bash\n# View logs\ndocker compose logs -f app           # Follow app logs\ndocker compose logs --tail=50 db     # Last 50 lines from db\n\n# Execute commands in running container\ndocker compose exec app sh           # Shell into app\ndocker compose exec db psql -U postgres  # Connect to postgres\n\n# Inspect\ndocker compose ps                     # Running services\ndocker compose top                    # Processes in each container\ndocker stats                          # Resource usage\n\n# Rebuild\ndocker compose up --build             # Rebuild images\ndocker compose build --no-cache app   # Force full rebuild\n\n# Clean up\ndocker compose down                   # Stop and remove containers\ndocker compose down -v                # Also remove volumes (DESTRUCTIVE)\ndocker system prune                   # Remove unused images\u002Fcontainers\n```\n\n### Debugging Network Issues\n\n```bash\n# Check DNS resolution inside container\ndocker compose exec app nslookup db\n\n# Check connectivity\ndocker compose exec app wget -qO- http:\u002F\u002Fapi:3000\u002Fhealth\n\n# Inspect network\ndocker network ls\ndocker network inspect \u003Cproject>_default\n```\n\n## Anti-Patterns\n\n```\n# BAD: Using docker compose in production without orchestration\n# Use Kubernetes, ECS, or Docker Swarm for production multi-container workloads\n\n# BAD: Storing data in containers without volumes\n# Containers are ephemeral -- all data lost on restart without volumes\n\n# BAD: Running as root\n# Always create and use a non-root user\n\n# BAD: Using :latest tag\n# Pin to specific versions for reproducible builds\n\n# BAD: One giant container with all services\n# Separate concerns: one process per container\n\n# BAD: Putting secrets in docker-compose.yml\n# Use .env files (gitignored) or Docker secrets\n```\n",{"name":5,"description":7},"main","5d0a87185c0e172c3901e2a6e5916b6d544b8b94","skills\u002Fdocker-patterns","https:\u002F\u002Fgithub.com\u002FJunMystery\u002FAgent-Guidance","https:\u002F\u002Fgithub.com\u002FJunMystery","AI is the typist, I am the architect. Building efficient, secure, and user-centric products through disciplined AI prompt engineering.","2026-11-13 17:41:25",{"source":8,"skillName":5,"commands":32,"prompt":42,"zipAvailable":43},[33,36,39],{"tool":34,"command":35},"npx","npx skills add JunMystery\u002FAgent-Guidance --skill docker-patterns",{"tool":37,"command":38},"bunx","bunx skills add JunMystery\u002FAgent-Guidance --skill docker-patterns",{"tool":40,"command":41},"pnpm","pnpm dlx skills add JunMystery\u002FAgent-Guidance --skill docker-patterns","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002FJunMystery\u002FAgent-Guidance\u002Fblob\u002Fmain\u002Fskills\u002Fdocker-patterns\u002FSKILL.md",true,[],[46,52,58,64,70,76],{"skillNo":47,"name":48,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":49,"categories":50,"keywords":51,"publishedAt":19},"01M79QR1E309VJ6CTQKB32AWWA","zero-trust-architecture-cheat-sheet","https:\u002F\u002Fgithub.com\u002FJunMystery\u002FAgent-Guidance\u002Fblob\u002Fmain\u002Fskills\u002Fzero-trust-architecture-cheat-sheet\u002FSKILL.md",[],[],{"skillNo":53,"name":54,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":55,"categories":56,"keywords":57,"publishedAt":19},"01M79QQV7GHYR02DYGN41S23WN","xss-filter-evasion-cheat-sheet","https:\u002F\u002Fgithub.com\u002FJunMystery\u002FAgent-Guidance\u002Fblob\u002Fmain\u002Fskills\u002Fxss-filter-evasion-cheat-sheet\u002FSKILL.md",[],[],{"skillNo":59,"name":60,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":61,"categories":62,"keywords":63,"publishedAt":19},"01M79QQNSN7YB8XB61FFSCS3WH","xs-leaks-cheat-sheet","https:\u002F\u002Fgithub.com\u002FJunMystery\u002FAgent-Guidance\u002Fblob\u002Fmain\u002Fskills\u002Fxs-leaks-cheat-sheet\u002FSKILL.md",[],[],{"skillNo":65,"name":66,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":67,"categories":68,"keywords":69,"publishedAt":19},"01M79QQHZZJKFDY9132G5A65C2","xpath-injection-prevention-cheat-sheet","https:\u002F\u002Fgithub.com\u002FJunMystery\u002FAgent-Guidance\u002Fblob\u002Fmain\u002Fskills\u002Fxpath-injection-prevention-cheat-sheet\u002FSKILL.md",[],[],{"skillNo":71,"name":72,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":73,"categories":74,"keywords":75,"publishedAt":19},"01M79QQB9ZSD3DJG8658EHQXR1","xml-security-cheat-sheet","https:\u002F\u002Fgithub.com\u002FJunMystery\u002FAgent-Guidance\u002Fblob\u002Fmain\u002Fskills\u002Fxml-security-cheat-sheet\u002FSKILL.md",[],[],{"skillNo":77,"name":78,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":79,"categories":80,"keywords":81,"publishedAt":19},"01M79QQ60WKV7PFMXWT9CW8PM6","xml-external-entity-prevention-cheat-sheet","https:\u002F\u002Fgithub.com\u002FJunMystery\u002FAgent-Guidance\u002Fblob\u002Fmain\u002Fskills\u002Fxml-external-entity-prevention-cheat-sheet\u002FSKILL.md",[],[]]