AGENT SKILL

docker-pro

Docker guidance — Dockerfile best practices, multi-stage builds, Compose, networking, volumes, and image security.

License 许可
MIT
所属仓库
TanNhatCMS/jarvis
最近更新
2026-11-07
Stars
★ 0
Forks
1

01 前言 Front Matter

name
docker-pro
category
development
description
Docker guidance — Dockerfile best practices, multi-stage builds, Compose, networking, volumes, and image security.

03 SKILL.md 正文

Overview

Docker packages applications and their dependencies into portable images that run identically anywhere the Docker runtime exists. Containers are the unit of deployment for modern infrastructure — understanding images, layers, networking, and volumes is prerequisite knowledge for Kubernetes, CI/CD, and cloud platforms.

The common failure mode is treating Dockerfiles as an afterthought: bloated images, leaked secrets, and containers that work on a laptop but die in production. This skill covers writing production-grade Dockerfiles, using Compose for local development, and the security and operational practices that matter.

When to use

  • Writing or reviewing Dockerfiles for any language.
  • Shrinking image sizes and speeding up builds (multi-stage, layer caching).
  • Setting up Docker Compose for local development environments.
  • Debugging container networking, volumes, and permissions.
  • Securing images (non-root users, secret handling, base image choice).
  • Choosing between Docker, Podman, and other runtimes.
  • Preparing images for Kubernetes or any orchestrator.

Core concepts

  • Images are layered. Each Dockerfile instruction creates a layer; layers cache and reuse. Order instructions from least-frequently-changed (base image, system deps) to most-frequently-changed (app code) to maximize cache hits.
  • Multi-stage builds. Build in one stage (compilers, node_modules), copy artifacts into a slim runtime stage. This is the single biggest image-size win — a Go or Java build can drop from 1GB to 50MB.
  • Small base images. alpine, distroless, or -slim variants over full OS images. Smaller images pull faster, have fewer CVEs, and reduce attack surface. Distroless goes further: no shell, no package manager.
  • .dockerignore. Like .gitignore for the build context — exclude .git, node_modules, build artifacts, secrets. A bloated context slows every build and can leak files into images.
  • Run as non-root. Create a user and USER it. Root-in-container is still root-adjacent on the host if there's a breakout; non-root is cheap defense in depth.
  • One process per container. The container's PID 1 should be your app (use exec form CMD so signals propagate). Sidecars and init systems are orchestrator concerns, not image concerns.
  • Layer caching in CI. Cache layers between builds (registry cache, BuildKit cache mounts) — RUN --mount=type=cache for package managers avoids re-downloading dependencies every build.
  • BuildKit. The modern builder: parallel builds, cache mounts, secrets mounts (--mount=type=secret), SSH mounts. Enable it; the legacy builder is obsolete.
  • Secrets never in layers. COPY .env or ARG secrets persist in image history. Use BuildKit secret mounts or multi-stage builds that don't copy secrets into the final stage.
  • Networking. Bridge (default, isolated), host (no isolation, max perf), none, and user-defined networks for inter-container DNS. In Compose, services reach each other by service name automatically.
  • Volumes vs bind mounts. Named volumes for persistent data (databases), bind mounts for development (live code reload). Volumes survive container recreation; container filesystems don't.
  • Healthchecks. HEALTHCHECK instruction so orchestrators know when the app is actually ready — not just when the process started.
  • Compose for dev. Multi-service local environments (app + db + cache) in one YAML file. Profiles, overrides, and .env support keep dev/prod parity without production complexity.
  • Image tagging. Immutable tags per build (git SHA), mutable tags (latest) only for convenience. Deployments should reference immutable digests or SHA tags — latest in production is undebuggable.
  • Scanning. Scan images for CVEs in CI (Trivy, Grype, Docker Scout). Base images accumulate vulnerabilities; rebuild regularly, don't just rescan old images.

Practical workflow

  1. Write the Dockerfile in cache order. Base image → system deps → language deps (lockfile first) → app code → runtime config. Each step ordered by change frequency.
    FROM node:22-slim AS deps
    WORKDIR /app
    COPY package.json package-lock.json ./
    RUN --mount=type=cache,target=/root/.npm npm ci
    
  2. Use multi-stage builds. Separate build and runtime stages; copy only artifacts forward; final stage minimal.
    FROM deps AS build
    COPY . .
    RUN npm run build
    FROM node:22-slim AS runtime
    WORKDIR /app
    COPY --from=build /app/dist ./dist
    COPY --from=deps /app/node_modules ./node_modules
    RUN useradd -r app && chown -R app:app /app
    USER app
    CMD ["node", "dist/index.js"]
    
  3. Add .dockerignore. Exclude .git, node_modules, *.md, local env files, and test artifacts — everything not needed at runtime.
  4. Handle secrets with mounts. RUN --mount=type=secret,id=npmrc npm ci keeps tokens out of layers; never COPY credential files.
  5. Define healthchecks. So orchestrators and Compose can gate on actual readiness:
    HEALTHCHECK --interval=30s --timeout=3s CMD wget -qO- http://localhost:3000/health || exit 1
    
  6. Compose the dev environment. App + dependencies in compose.yaml; named volumes for databases; bind mounts for code; override files for local tweaks.
    services:
      app:
        build: .
        ports: ["3000:3000"]
        volumes: ["./src:/app/src"]
        depends_on: { db: { condition: service_healthy } }
      db:
        image: postgres:16
        volumes: ["pgdata:/var/lib/postgresql/data"]
    volumes: { pgdata: {} }
    
  7. Scan and tag in CI. Build with BuildKit, scan with Trivy/Grype (fail on critical), tag with git SHA, push immutable tags.
  8. Run production-ready. Resource limits, restart policies, log drivers with rotation, read-only filesystems where possible, and no --privileged without justification.

Common pitfalls

  • Secrets in image layers — COPY .env or ARG credentials persist in history; use secret mounts.
  • Running as root — default user is root; create and use a non-root user.
  • Huge images — full OS bases and build tools in the final stage; multi-stage + slim bases.
  • Cache-busting order — COPY . before npm ci invalidates the dependency layer on every code change; copy lockfiles first.
  • Missing .dockerignore — slow builds and leaked files; always define it.
  • Shell-form CMD — CMD npm start wraps in sh, breaking signal propagation; use exec form ["npm", "start"].
  • No healthcheck — orchestrator thinks the container is ready when the process merely started; define one.
  • latest in production — undebuggable deploys; pin immutable tags or digests.
  • Unbounded logs — json-file logs filling disks; configure log rotation.
  • Writable root filesystem — unnecessary attack surface; --read-only with tmpfs for scratch space.
  • Ignoring scans — CVEs accumulating in base images; scan in CI and rebuild regularly.
  • Bind mounts in production — host-path coupling; use named volumes or object storage.
  • No resource limits — one container starving the host; set memory/CPU limits.

04 同仓库更多 Skills

TanNhatCMS
TanNhatCMS/jarvis

web-scrape

Turn web pages into LLM-ready markdown via the Firecrawl API (renders JS, anti-bot handling). Use when browser_open/fetch fails on JS-heavy pages, or when you need clean markdown/structured extraction from a site. Requires FIRECRAWL_API_KEY.

★ 0
TanNhatCMS
TanNhatCMS/jarvis

design-taste-frontend

tasteskill v2, the anti-slop frontend skill. Art direction for websites, distilled from a study of 247 curated gallery sites (One Page Love, Awwwards Sites of the Day). Deals researched directions (idea, composition, type, palette, photographs, section blueprints) from a library, enforces a strict no-slop house style with a real-browser inspector, and runs a look-and-fix loop on screenshots. Use this whenever you build, design, redesign, restyle, polish or review a landing page, marketing site, portfolio, product page, one-pager, hero or any public-facing web page, in any stack (HTML/CSS, React, Next.js, Vue, Svelte, Astro, Tailwind) — also when the user says a page looks generic, templated, "AI-made", sloppy, or asks to make it look designed, premium, award-level or less like every other site. Not for dashboards or app screens.

★ 0
TanNhatCMS
TanNhatCMS/jarvis

test-driven-development

Use when implementing any feature or bugfix, before writing implementation code

★ 0
TanNhatCMS
TanNhatCMS/jarvis

systematic-debugging

Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes

★ 0
TanNhatCMS
TanNhatCMS/jarvis

requesting-code-review

Use when completing tasks, implementing major features, or before merging to verify work meets requirements

★ 0
TanNhatCMS
TanNhatCMS/jarvis

brainstorming

You MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).

★ 0