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

dockerfile

# 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

dockerfile

# 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

dockerfile

# 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

bash

# 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

code

Skill("dockerfile-basics")

Related Skills

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