Development vs production Dockerfiles - CLI Comparison

Introduction

When building software with Docker, you often need different setups for development and production. Development Dockerfiles include tools and settings to help you write and test code easily. Production Dockerfiles focus on making the app small, fast, and secure for users.

When you want to run your app with live code changes during development without rebuilding the image every time.

When you need debugging tools and extra logs while developing your app.

When you want a smaller, faster Docker image to deploy to users in production.

When you want to avoid including development tools and files in your production image for security and performance.

When you want to use multi-stage builds to share code but separate development and production environments.

Config File - Dockerfile

Dockerfile

### Development stage
FROM node:18-alpine AS development
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm install
COPY . .
CMD ["npm", "run", "dev"]

### Production stage
FROM node:18-alpine AS production
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm install --production
COPY . .
CMD ["node", "server.js"]

This Dockerfile uses two stages: development and production.

The development stage installs all dependencies and runs the app with live reload for easy coding.

The production stage installs only the necessary packages to run the app, making the image smaller and faster.

You can build either stage depending on your need.

Commands

Builds the Docker image using the development stage. This image includes all tools and dependencies for coding and testing.

Terminal

docker build --target development -t my-app-dev .

Expected Output

Sending build context to Docker daemon  10.24MB

Step 1/10 : FROM node:18-alpine AS development

18-alpine: Pulling from library/node

...

Successfully built abcdef123456

Successfully tagged my-app-dev:latest

→

--target - Specifies which stage in the Dockerfile to build

→

-t - Names the image for easy reference

Runs the development image and maps port 3000 so you can access the app in your browser during development.

Terminal

docker run -p 3000:3000 my-app-dev

Expected Output

Starting development server...

Listening on http://localhost:3000

→

-p - Maps container port to host port

Builds the Docker image using the production stage. This image is optimized for running the app in production with only necessary files.

Terminal

docker build --target production -t my-app-prod .

Expected Output

Sending build context to Docker daemon  10.24MB

Step 1/10 : FROM node:18-alpine AS production

18-alpine: Pulling from library/node

...

Successfully built 123456abcdef

Successfully tagged my-app-prod:latest

→

--target - Specifies which stage in the Dockerfile to build

→

-t - Names the image for easy reference

Runs the production image and maps port 8080 on your machine to port 3000 in the container to serve the app to users.

Terminal

docker run -p 8080:3000 my-app-prod

Expected Output

Server started on port 3000

→

-p - Maps container port to host port

Key Concept

If you remember nothing else from this pattern, remember: use separate Dockerfile stages to keep development tools out of your production image for better performance and security.

Common Mistakes

Building the Docker image without specifying the --target flag and expecting a development or production image.

Docker will build the last stage by default, which may not be the one you want.

Always use --target development or --target production to build the correct stage.

Including development dependencies in the production image by copying all files and running full npm install.

This makes the production image larger and may expose unnecessary tools or files.

Use npm install --production in the production stage to install only needed packages.

Running the production image with the development command like npm run dev.

The production image may not have development tools or live reload, causing errors or unexpected behavior.

Use the correct CMD for each stage: npm run dev for development, node server.js for production.

Summary

Use multi-stage Dockerfiles to separate development and production environments.

Build development images with all tools for coding and testing using --target development.

Build production images with only necessary files and dependencies using --target production.

Run containers with appropriate port mappings to access your app.

Avoid mixing development tools in production images for better security and performance.