Optimize Node.js Docker Images

Intermediate12 min

Build minimal, secure, and fast Node.js Docker images for production using multi-stage builds and best practices.

Prerequisites

-Docker installed
-Existing Node.js project with package.json

Steps

Create an optimized multi-stage Dockerfile

Use multi-stage builds to separate the build environment from the production runtime, reducing final image size.

$ cat <<'EOF' > Dockerfile # Stage 1: Install dependencies FROM node:20-alpine AS deps WORKDIR /app COPY package.json package-lock.json ./ RUN npm ci --only=production # Stage 2: Build (if needed) FROM node:20-alpine AS builder WORKDIR /app COPY package.json package-lock.json ./ RUN npm ci COPY . . RUN npm run build # Stage 3: Production FROM node:20-alpine AS runner WORKDIR /app ENV NODE_ENV=production RUN addgroup -g 1001 -S nodejs && adduser -S nodejs -u 1001 COPY --from=deps /app/node_modules ./node_modules COPY --from=builder /app/dist ./dist COPY package.json ./ USER nodejs EXPOSE 3000 CMD ["node", "dist/index.js"] EOF

Use alpine images for smaller size. The multi-stage build ensures dev dependencies and source code are not in the final image.

Create .dockerignore to exclude unnecessary files

Prevent unnecessary files from being copied into the Docker build context, improving build speed and security.

$ cat <<'EOF' > .dockerignore node_modules npm-debug.log .git .gitignore .env .env.* Dockerfile docker-compose*.yml *.md tests/ coverage/ .vscode/ .idea/ EOF

Use npm ci instead of npm install

npm ci provides faster, reproducible installs by using the exact versions from package-lock.json.

$ # In Dockerfile: RUN npm ci --only=production # Not: # RUN npm install

npm ci deletes node_modules before installing, ensuring a clean state. It also fails if package-lock.json is out of sync.

Run as non-root user

Create and switch to a non-root user for security. Never run your application as root in a container.

$ # In Dockerfile: RUN addgroup -g 1001 -S nodejs && adduser -S nodejs -u 1001 USER nodejs

If your app writes to the filesystem, ensure the nodejs user has write permissions to those directories.

Build and verify image size

Build the image and check that the final size is reasonable (typically 100-200MB for alpine Node.js apps).

$ docker build -t my-app:latest . && docker images my-app

Add a health check

Add a HEALTHCHECK instruction so orchestrators can monitor container health.

$ # Add to Dockerfile before CMD: HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \ CMD wget --no-verbose --tries=1 --spider http://localhost:3000/health || exit 1

Use wget instead of curl in alpine images since wget is included by default but curl is not.

Full Script

full-script.sh

#!/bin/bash
set -euo pipefail

# Node.js Docker Optimization Script

echo "==> Creating optimized Dockerfile..."
cat > Dockerfile <<'DOCKERFILE'
# Stage 1: Dependencies
FROM node:20-alpine AS deps
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci --only=production && npm cache clean --force

# Stage 2: Build
FROM node:20-alpine AS builder
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci
COPY . .
RUN npm run build

# Stage 3: Production
FROM node:20-alpine AS runner
WORKDIR /app
ENV NODE_ENV=production

RUN addgroup -g 1001 -S nodejs && adduser -S nodejs -u 1001

COPY --from=deps --chown=nodejs:nodejs /app/node_modules ./node_modules
COPY --from=builder --chown=nodejs:nodejs /app/dist ./dist
COPY --chown=nodejs:nodejs package.json ./

USER nodejs
EXPOSE 3000

HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3   CMD wget --no-verbose --tries=1 --spider http://localhost:3000/health || exit 1

CMD ["node", "dist/index.js"]
DOCKERFILE

echo "==> Creating .dockerignore..."
cat > .dockerignore <<'EOF'
node_modules
npm-debug.log
.git
.gitignore
.env
.env.*
Dockerfile
docker-compose*.yml
*.md
tests/
coverage/
.vscode/
.idea/
EOF

echo "==> Building image..."
docker build -t my-app:latest .

echo ""
echo "==> Image size:"
docker images my-app:latest --format "table {{.Repository}}\t{{.Tag}}\t{{.Size}}"

echo ""
echo "==> Image layers:"
docker history my-app:latest --format "table {{.CreatedBy}}\t{{.Size}}" | head -10

FAQ

Discussion

Loading comments...

#!/bin/bash set -euo pipefail # Node.js Docker Optimization Script echo "==> Creating optimized Dockerfile..." cat > Dockerfile <<'DOCKERFILE' # Stage 1: Dependencies FROM node:20-alpine AS deps WORKDIR /app COPY package.json package-lock.json ./ RUN npm ci --only=production && npm cache clean --force # Stage 2: Build FROM node:20-alpine AS builder WORKDIR /app COPY package.json package-lock.json ./ RUN npm ci COPY . . RUN npm run build # Stage 3: Production FROM node:20-alpine AS runner WORKDIR /app ENV NODE_ENV=production RUN addgroup -g 1001 -S nodejs && adduser -S nodejs -u 1001 COPY --from=deps --chown=nodejs:nodejs /app/node_modules ./node_modules COPY --from=builder --chown=nodejs:nodejs /app/dist ./dist COPY --chown=nodejs:nodejs package.json ./ USER nodejs EXPOSE 3000 HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 CMD wget --no-verbose --tries=1 --spider http://localhost:3000/health || exit 1 CMD ["node", "dist/index.js"] DOCKERFILE echo "==> Creating .dockerignore..." cat > .dockerignore <<'EOF' node_modules npm-debug.log .git .gitignore .env .env.* Dockerfile docker-compose*.yml *.md tests/ coverage/ .vscode/ .idea/ EOF echo "==> Building image..." docker build -t my-app:latest . echo "" echo "==> Image size:" docker images my-app:latest --format "table {{.Repository}}\t{{.Tag}}\t{{.Size}}" echo "" echo "==> Image layers:" docker history my-app:latest --format "table {{.CreatedBy}}\t{{.Size}}" | head -10