---

name: dockerfile-basics description: Learn Dockerfile fundamentals and best practices for building production-ready container images sasmp_version: "1.3.0" bonded_agent: 01-docker-fundamentals bond_type: PRIMARY_BOND

Dockerfile Basics Skill

Master Dockerfile fundamentals and 2024-2025 best practices for building secure, optimized container images.

Purpose

Provide comprehensive guidance on Dockerfile syntax, instruction ordering, layer optimization, and security best practices.

Parameters

Parameter	Type	Required	Default	Description
base_image	string	No	-	Base image to use
language	string	No	-	Programming language (node/python/go/java)
optimize	boolean	No	true	Apply optimization recommendations

Core Instructions

Instruction Reference

Instruction	Purpose	Example
FROM	Base image	FROM node:20-alpine
WORKDIR	Set working directory	WORKDIR /app
COPY	Copy files	COPY package*.json ./
RUN	Execute command	RUN npm ci
ENV	Set environment	ENV NODE_ENV=production
EXPOSE	Document port	EXPOSE 3000
USER	Set user	USER appuser
CMD	Default command	CMD ["node", "app.js"]
ENTRYPOINT	Fixed command	ENTRYPOINT ["./start.sh"]
HEALTHCHECK	Health check	HEALTHCHECK CMD curl -f http://localhost/

Layer Optimization Order

# 1. Base image (most stable)
FROM node:20-alpine

# 2. System dependencies
RUN apk add --no-cache curl

# 3. Create user (security)
RUN addgroup -g 1001 app && adduser -u 1001 -G app -D app

# 4. Set working directory
WORKDIR /app

# 5. Copy dependency files (cache layer)
COPY package*.json ./

# 6. Install dependencies
RUN npm ci --only=production

# 7. Copy application code (most volatile)
COPY --chown=app:app . .

# 8. Switch to non-root user
USER app

# 9. Health check
HEALTHCHECK --interval=30s --timeout=3s CMD curl -f http://localhost:3000/health || exit 1

# 10. Default command
CMD ["node", "server.js"]

Best Practices (2024-2025)

Security Essentials

# Always use specific version tags
FROM node:20.10-alpine  # Good
# FROM node:latest      # Bad

# Run as non-root user
USER nonroot

# Use multi-stage builds
FROM node:20 AS builder
# ... build steps ...
FROM node:20-alpine AS runtime
COPY --from=builder /app/dist ./

Optimization Techniques

# Combine RUN commands
RUN apt-get update && \
    apt-get install -y --no-install-recommends curl && \
    rm -rf /var/lib/apt/lists/*

# Use .dockerignore
# node_modules, .git, *.md, etc.

# Leverage BuildKit cache mounts
RUN --mount=type=cache,target=/root/.npm npm ci

Error Handling

Common Errors

Error	Cause	Solution
COPY failed: file not found	File outside context	Check .dockerignore
returned non-zero code: 127	Command not found	Install package first
permission denied	Running as non-root	Use COPY --chown

Validation Commands

# Lint Dockerfile
hadolint Dockerfile

# Build with no cache
docker build --no-cache -t app:test .

# Inspect layers
docker history app:test

Troubleshooting

Debug Checklist

• .dockerignore excludes unnecessary files?
• Base image tag is specific (not :latest)?
• Dependencies copied before source code?
• Non-root user configured?
• HEALTHCHECK defined?

Common Issues

Symptom	Cause	Fix
Large image size	No multi-stage	Add build stage
Slow builds	Poor layer order	Move COPY after dependencies
Security warnings	Root user	Add USER instruction

Usage

Skill("dockerfile-basics")

Related Skills

• docker-multi-stage
• docker-optimization
• docker-security