Tryboy869 docker Best Practices
Docker is the cornerstone of modern container-first development. Treat your Dockerfile and docker-compose.yml as critical source code. These rules ensure your images are fast, secure, reproducible, and aligned with modern DevOps practices.
1. Optimize for Multi-Stage Builds
Always use multi-stage builds. This pattern isolates build-time dependencies from runtime, drastically reducing final image size and attack surface.
❌ BAD: Single-stage build with all dependencies
FROM node:20
WORKDIR /app
COPY package*.json ./
RUN npm install
COPY . .
RUN npm run build
CMD ["node", "dist/server.js"]
✅ GOOD: Multi-stage build for production
# Stage 1: Build application artifacts
FROM node:20-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production # Install only production dependencies for build
COPY . .
RUN npm run build
# Stage 2: Create minimal runtime image
FROM node:20-alpine
WORKDIR /app
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/node_modules ./node_modules # Copy only necessary runtime modules
USER node # Run as non-root user
EXPOSE 3000
CMD ["node", "dist/server.js"]
2. Choose Minimal, Trusted Base Images
Start with the smallest possible base image from a trusted source (Docker Official Images, Verified Publishers). Alpine variants are often the best choice for minimal footprints.
❌ BAD: Large, generic base image
FROM ubuntu:latest # Too large, many unnecessary packages and vulnerabilities
✅ GOOD: Minimal, specific base image
FROM node:20-alpine # Official, small, specific to Node.js
# Or for static content:
FROM nginx:alpine
3. Leverage .dockerignore
Always use a .dockerignore file to exclude irrelevant files and directories from your build context. This significantly speeds up builds and prevents sensitive or unnecessary files from being copied into the image.
❌ BAD: No .dockerignore (sends node_modules, .git, .env, etc., to the daemon)
✅ GOOD: Comprehensive .dockerignore
# .dockerignore
.git
.gitignore
node_modules
npm-debug.log
Dockerfile
docker-compose*.yml
.env
README.md
tmp/
4. Optimize Layer Caching
Order your Dockerfile instructions from least to most frequently changing. Docker caches layers, so placing stable instructions first maximizes cache hits and speeds up subsequent builds.
❌ BAD: Copying all source code before installing dependencies
FROM node:20-alpine
WORKDIR /app
COPY . . # Invalidates cache if any file changes, forcing npm install every time
RUN npm install
✅ GOOD: Copying dependency files first
FROM node:20-alpine
WORKDIR /app
COPY package*.json ./ # Only changes when dependencies change; cache hit if unchanged
RUN npm ci # Cache hit if package.json is unchanged
COPY . . # Only invalidates this layer if source code changes
5. Run as a Non-Root User
Never run your application as root inside the container. Create a dedicated non-root user and switch to it using the USER instruction to enforce the principle of least privilege.
❌ BAD: Running as root (default behavior)
FROM node:20-alpine
WORKDIR /app
COPY . .
RUN npm install
CMD ["node", "app.js"] # Runs as root
✅ GOOD: Running as a non-root user
FROM node:20-alpine
WORKDIR /app
COPY . .
RUN npm install && \
chown -R node:node /app # Ensure non-root user has permissions for app directory
USER node # Switch to non-root user
CMD ["node", "app.js"]
6. Distinguish ARG and ENV
Use ARG for build-time variables that do not persist in the final image. Use ENV for runtime environment variables that your application needs.
❌ BAD: Using ENV for build-only values or ARG for runtime values
FROM ubuntu
ENV BUILD_VERSION=1.0.0 # Persists in image, potentially unnecessary
ARG PORT=8080 # Not available at runtime unless explicitly passed
✅ GOOD: Correct usage of ARG and ENV
FROM node:20-alpine
ARG NODE_ENV=production # Build-time variable, not in final image
ENV APP_PORT=3000 # Runtime variable, available to the application
WORKDIR /app
COPY . .
RUN if [ "$NODE_ENV" = "production" ]; then npm ci --production; else npm ci; fi
EXPOSE ${APP_PORT}
CMD ["node", "app.js"]
7. Implement Health Checks
Define HEALTHCHECK instructions in your Dockerfile to allow Docker and orchestration tools to verify if your containerized service is still working correctly. This is crucial for reliable deployments.
❌ BAD: No health check, relying solely on process exit
CMD ["node", "app.js"]
✅ GOOD: Robust health check
EXPOSE 3000
HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
CMD curl -f http://localhost:3000/health || exit 1
CMD ["node", "app.js"]
8. Log to stdout/stderr
Containerized applications must write logs to stdout and stderr. This allows Docker and orchestration tools to easily capture, aggregate, and manage logs without needing complex in-container log rotation or file access.
❌ BAD: Writing logs to files inside the container
// app.js
fs.appendFileSync('/var/log/app.log', 'Application started\n');
✅ GOOD: Writing logs to stdout/stderr
// app.js
console.log('Application started');
console.error('An error occurred');
9. Use Docker Compose for Local Development
For multi-service applications, always use docker-compose.yml to define and run your services. This ensures a consistent, reproducible development environment for all team members.
❌ BAD: Manually running multiple docker run commands for interconnected services
docker run -p 8080:80 my-web-app
docker run -p 5432:5432 my-database
✅ GOOD: Defining services in docker-compose.yml
# docker-compose.yml
version: '3.8'
services:
web:
build: .
ports:
- "8080:8080"
environment:
DATABASE_URL: postgres://user:password@db:5432/mydb
depends_on:
- db
db:
image: postgres:13-alpine
environment:
POSTGRES_DB: mydb
POSTGRES_USER: user
POSTGRES_PASSWORD: password
volumes:
- db_data:/var/lib/postgresql/data
volumes:
db_data:
10. Manage Secrets Securely with Docker Compose
Never hardcode sensitive information (API keys, passwords) directly in Dockerfile or docker-compose.yml. For local development, use Docker Compose's secrets feature.
❌ BAD: Hardcoding secrets directly in the compose file
# docker-compose.yml
services:
web:
environment:
API_KEY: "supersecretkey123" # BAD! This is committed to source control.
✅ GOOD: Using Docker Compose secrets
# docker-compose.yml
version: '3.8'
services:
web:
image: my-web-app:latest
secrets:
- api_key_file
environment:
API_KEY_PATH: /run/secrets/api_key_file # Application reads from this path
secrets:
api_key_file:
file: ./secrets/api_key.txt # Create this file locally, ensure it's .gitignored
(Note: For production, use a dedicated secret management system like Kubernetes Secrets, AWS Secrets Manager, or HashiCorp Vault.)