docker-build

Docker Build — Image Building and Management

Complete reference for docker build and image lifecycle management. Build, tag, inspect, push, prune.

When to Use

ALWAYS use this skill when the user mentions:

"docker build", "how to build an image", "docker build command"
"docker tag", "docker push", "push image"
"docker images", "image management", "docker image"
"--build-arg", "build arguments"
"docker history", "docker inspect", "image inspection"
"docker image prune", "docker system prune", "clean up images"

✅ Use When	❌ Use Instead
Running docker build, tagging, pushing
Managing local images
Needing `docker build` CLI reference
Writing the Dockerfile itself	`docker-dockerfile`
Multi-platform builds	`docker-buildx`
BuildKit advanced features	`docker-buildx`

docker build — Complete Syntax

docker build [OPTIONS] PATH | URL | -

Essential Options

# Basic build
docker build -t myapp:v1 .

# Tag multiple tags at once
docker build -t myapp:v1.2.3 -t myapp:latest -t ghcr.io/org/myapp:v1.2.3 .

# Build from specific Dockerfile
docker build -f Dockerfile.prod -t myapp:prod .

# Build from Git repository
docker build -t myapp https://github.com/user/repo.git#main

# Build from stdin
cat Dockerfile | docker build -t myapp -
docker build -t myapp - <<EOF
FROM alpine:3.20
CMD ["echo", "hello"]
EOF

Build Arguments (--build-arg)

# Pass build arguments
docker build --build-arg NODE_VERSION=22 --build-arg ENV=production -t myapp .

# From file
docker build --build-arg $(cat .env.build | xargs) -t myapp .

ARG NODE_VERSION=20
FROM node:${NODE_VERSION}-alpine
ARG ENV=development
ENV NODE_ENV=${ENV}
RUN echo "Building for ${NODE_ENV}"

Option	Purpose
`--build-arg KEY=VALUE`	Pass single argument
`--build-arg-file FILE`	Read args from file
`ARG KEY=default`	Define in Dockerfile with default

Build Control

# No cache (force full rebuild)
docker build --no-cache -t myapp .

# Pull base image even if cached locally
docker build --pull -t myapp .

# Quiet mode (only image ID)
docker build -q -t myapp .

# Set build target (multi-stage)
docker build --target builder -t myapp:builder .

# BuildKit output (export to local directory)
docker build --output type=local,dest=./out .

# Platform (with BuildKit)
docker build --platform linux/amd64 -t myapp .

# Add metadata
docker build --label "org.opencontainers.image.version=v1.2.3" -t myapp .

Build Context

# Current directory
docker build -t myapp .

# Specific directory
docker build -t myapp ./app

# Remote Git repo
docker build -t myapp https://github.com/user/repo.git#v1.0.0:subdir

# Pipe context via stdin (no context)
docker build -t myapp - < Dockerfile

Image Tagging — docker tag

# Tag an existing image
docker tag myapp:v1 myapp:latest
docker tag myapp:v1 ghcr.io/org/myapp:v1

# Tag with registry
docker tag myapp:v1 registry.example.com:5000/myapp:v1

# Force overwrite existing tag
docker tag myapp:v1 myapp:latest   # replaces where :latest points

Tag Naming Convention

[registry[:port]/][namespace/]name[:tag|@digest]

ghcr.io/myorg/myapp:v1.2.3
│       │     │      │
│       │     │      └── tag (semver)
│       │     └── image name
│       └── namespace
└── registry

Image Inspection

# List images
docker images
docker image ls
docker image ls --format "table {{.Repository}}\t{{.Tag}}\t{{.Size}}"

# Inspect image details
docker inspect myapp:v1
docker inspect --format='{{.Config.Env}}' myapp:v1
docker inspect --format='{{.Created}}' myapp:v1

# View layer history
docker history myapp:v1
docker history --no-trunc --human myapp:v1

# Show digest
docker image ls --digests myapp
docker inspect --format='{{index .RepoDigests 0}}' myapp:v1

Pushing to Registry

# Login
docker login
docker login ghcr.io -u USERNAME -p $TOKEN

# Push
docker push myapp:v1
docker push myapp --all-tags

# Push with digest
docker push myapp@sha256:abc123...

Image Cleanup

# Remove specific image
docker rmi myapp:v1
docker image rm myapp:v1

# Remove dangling images (<none>:<none>)
docker image prune

# Remove all unused images
docker image prune -a

# Full system cleanup
docker system prune -a --volumes

# Check disk usage
docker system df
docker system df -v

Workflow — Recommended Build Process

Step 1: Prepare Dockerfile: Writing completed (or use docker-dockerfile to generate) Step 2: Configure build parameters: Confirm --build-arg, --label, --target Step 3: Execute build: docker build -t myapp:v1 -t myapp:latest . Step 4: Verify image: docker images / docker history / docker inspect Step 5: Push to registry: docker push before docker login, pin by digest in production

Gotchas — Common Pitfalls

docker build -t myapp . sends entire context: Without .dockerignore, sends node_modules/.git and everything. Use .dockerignore to minimize context.
docker build --no-cache is slow: Only use when truly needed. Normal builds reuse cached layers.
docker tag is mutable: Tags can be moved. For production, use digest (@sha256:...) instead of tag.
docker push without login fails silently: Always docker login first, or use CI credential helpers.
docker system prune -a is destructive: Removes ALL unused images, containers, networks. Don't run in production without confirmation.
docker build --pull changes base image: Your build may produce different output if base image was updated.

Boundary — Capability Boundaries (Applicable and Non-Applicable Scenarios)

Category	Scenario	Description
✅ Can do	docker build to build images	Full command syntax, context management, multiple tags
✅ Can do	docker tag to tag images	Naming conventions, multiple registry tags
✅ Can do	docker push to push images	Registry login, digest pinning
✅ Can do	Image management (inspect/history/prune)	Local image lifecycle
⚠️ Conditional	BuildKit advanced features (secret/cache/ssh)	Use `docker-buildx`
⚠️ Conditional	Push large images when the network is unstable	Configure max-concurrent-uploads
❌ Out of scope	Dockerfile authoring	Use `docker-dockerfile`
❌ Out of scope	Multi-platform builds (arm64/amd64)	Use `docker-buildx`
❌ Out of scope	CI/CD pipeline integration	Use `docker-cicd`

When NOT to Use This Skill

❌ Skip	✅ Use Instead
Writing the Dockerfile itself	`docker-dockerfile`
Multi-platform/arm64 builds	`docker-buildx`
BuildKit secrets/cache/SSH	`docker-buildx`
Running containers	`docker-run`
Docker basics	`docker-basics`

Security & Stability

Always scan built images with docker scout before pushing to production registry.
Use docker build --pull to ensure base images are up-to-date with security patches.
Never embed secrets in build args (--build-arg is visible in image history). Use BuildKit --secret instead.
Tag images with --label for metadata (version, git SHA, build timestamp) for audit trails.
Remove unused images regularly with docker image prune to free disk space and reduce attack surface.

📚 Official Documentation References

Documentation	Address
Docker Build	https://docs.docker.com/build/
docker build command	https://docs.docker.com/reference/cli/docker/build/
docker tag	https://docs.docker.com/reference/cli/docker/image/tag/
docker push	https://docs.docker.com/reference/cli/docker/image/push/
docker image	https://docs.docker.com/reference/cli/docker/image/
Dockerfile reference	https://docs.docker.com/reference/dockerfile/

🧭 Docker Skills Journey

📍 You are here: docker-build — Image Building and Management

basics → dockerfile → build → buildx → run → compose → ...

→ Next: docker-buildx — Multi-platform builds and BuildKit advanced features