Skip to content

CowboyLogic/ai-dev / skills/docker-image-management

docker-image-management

Flagged

Guide for creating, building, and managing Docker images and containers. Use this skill when working with Dockerfiles, containerization, image building, registry operations, container runtime, storage mounts, image security, Docker Compose, or any Docker-related task including optimization, debugging, and best practices.

Docker Image Management Skill

This skill covers the full lifecycle of Docker container images: authoring Dockerfiles, building with BuildKit, running containers, managing storage, pushing to registries, and scanning for vulnerabilities.

Quick Decision Guide

TaskLoad
Writing or optimizing a Dockerfile, multi-stage builds, build cache, build secretsreferences/build.md
Running containers, networking, mounts, resource limits, capabilitiesreferences/run.md
Tagging, pushing/pulling, Docker Hub auth, image scanning (Scout)references/registry.md
Multi-container appsreferences/docker-compose-examples.yml
Dockerfile templates for Node, Python, Go, Java, etc.references/dockerfile-templates.md

Always load the relevant reference file before giving guidance on that topic.

Core Principles

Security first

  • Run as a non-root USER — always. Docker Scout flags containers running as root.
  • Never embed secrets in image layers. Use build-time --secret mounts or runtime env vars.
  • Use official or verified publisher base images. Pin to a specific tag (e.g. node:22-alpine) or digest for reproducibility.

Layer efficiency

  • Order COPY/RUN instructions from least-to-most frequently changed to maximize cache reuse.
  • Install dependencies before copying app code.
  • Combine apt-get update && apt-get install in a single RUN; clean up in the same layer.
  • Use multi-stage builds to keep production images free of build tools.

BuildKit is the default

BuildKit is enabled by default in Docker Engine 23.0+ and Docker Desktop. It provides:

  • Parallel stage execution
  • Efficient layer caching
  • Secret mounts (--secret)
  • SSH forwarding (--ssh)
  • Inline cache export

Use docker buildx build for advanced features (multi-platform, custom builders). docker build wraps Buildx.

Standard Workflow

1. Analyze requirements

Before writing a Dockerfile, identify:

  • Runtime vs. build-only dependencies
  • Exposed ports
  • Required env vars and config
  • Persistent data (volumes)
  • Security context (user, capabilities)

2. Write the Dockerfile

Read references/build.md for Dockerfile instruction guidance and patterns. Copy a starter from references/dockerfile-templates.md and customize.

3. Create .dockerignore

Exclude node_modules/, .git/, .env, *.log, build output dirs, and test files. See references/dockerignore-template for language-specific patterns.

4. Build the image

# Standard build
docker build -t myapp:1.0 .

# Build + push in one step
docker build --push -t registry.example.com/myapp:1.0 .

# Pull fresh base, bypass cache
docker build --pull --no-cache -t myapp:1.0 .

# Pass a build secret (never use --build-arg for secrets)
docker build --secret id=mysecret,src=.env -t myapp:1.0 .

5. Run and test

docker run --rm -p 3000:3000 myapp:1.0
docker logs <container>
docker exec -it <container> sh

Read references/run.md for full runtime options.

6. Tag and push

docker tag myapp:1.0 myorg/myapp:1.0
docker push myorg/myapp:1.0

Read references/registry.md for authentication, tagging strategy, and vulnerability scanning.

Debugging Checklist

SymptomAction
Container exits immediatelydocker logs <container>
Port not reachableCheck -p HOST:CONTAINER, verify EXPOSE
File not found in containerCheck .dockerignore, verify COPY paths
Permission deniedCheck USER and file ownership
Large image sizeUse multi-stage build, alpine base, .dockerignore
Build cache not workingVerify COPY order; check if files changed
Secret exposed in layerUse --secret mount, not --build-arg
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 468kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 468kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 468kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall