Mastering Docker with Node.js: A Comprehensive Guide for Beginners

In this guide, you will learn how to effectively use Docker with Node.js to build scalable applications.

Introduction

Node.js is a powerful runtime environment that enables developers to build fast, scalable, and efficient server-side applications using JavaScript. Its event-driven, non-blocking architecture has made it a popular choice for real-time applications and microservices. Docker, on the other hand, revolutionizes application deployment by providing lightweight, portable containers that bundle an application and its dependencies, ensuring consistent performance across environments.

In this guide, you will learn how to effectively use Docker with Node.js. We’ll cover the basics of setting up a simple application, creating Dockerfiles, optimizing your containers for production, and implementing best practices.

Prerequisites

Before diving into the details, ensure you meet the following prerequisites:

Virtual Private Server (VPS): While optional to follow this guide, you will want your application hosted for production. Hostinger’s KVM2 is a solid VPS hosting plan to work with for small-to-medium-sized projects – it comes with 2 vCPU cores, 8GB of RAM, 8TB of bandwidth, and 100GB of NVMe disk space for $6.99/month.
Node.js installed on your system: You can download it from the official website, or if you’re using Hostinger’s VPS, you can install Node.js automatically using a Node.js template.
Docker installed and configured: We also have a Docker VPS template that you can install with only a few clicks.
Some basic knowledge of JavaScript and Docker commands, such as docker build and docker run, will simplify the process as well.

Having these prerequisites in place will help you follow along with the examples and maximize the value of this guide.

Getting Started with Docker for Node.js

Choosing the Right Node.js Docker Image

The Node.js Docker Official Image provides prebuilt Docker images optimized for different use cases. These images save time and effort by bundling Node.js with necessary libraries, and they are maintained by the Node.js and Docker teams to ensure security and compatibility.

Here are the main types of Node.js Docker images:

Slim images: These lightweight images include only the essential components required to run Node.js. They are smaller in size; however, they may lack some libraries that are useful during development.
Alpine images: Based on Alpine Linux, these images are ultra-lightweight and ideal for production environments.
Full images: These images are larger in size and include additional tools and libraries. They are particularly useful for development and debugging.

Due to their efficiency and smaller size, the Slim or Alpine-based images are recommended for most production environments. The Full image can be useful for development purposes, especially when debugging or using tools not included in lightweight variants.

Setting Up a Simple Node.js Application

To get started, let’s create a basic Node.js application:

Open your terminal and create a directory for your project:

mkdir node-docker-app

Run the following command to generate a package.json file:

npm init -y

Create the application file named app.js and add the following code:

const http = require("http");

const port = 3000;

const server = http.createServer((req, res) => {
  res.writeHead(200, { "Content-Type": "text/plain" });
  res.end("Hello, Docker!");
});

server.listen(port, () => {
  console.log(`Server running at http://localhost:${port}`);
});

This script creates a basic HTTP server using Node.js’s built-in http module. When accessed, it responds with the message “Hello, Docker!” and logs the server’s URL to the console.

If your application requires additional dependencies, you can install them using npm install. For example, to use the popular express framework:

npm install express

Building a Node.js Application with Docker

At a very basic level, building any Node.js application with Docker takes 3 steps:

Create a Dockerfile.
Build the Docker image.
Run the Docker container.

Step 1: Create a Dockerfile

Create a file named Dockerfile in your project root directory and add the following:

# Use alpine node base image
FROM node:18-alpine

# Set working directory inside the docker node
WORKDIR /app

# Copy package files and install dependencies
COPY package*.json ./
RUN npm install

# Copy the rest of the application code
COPY . .

# Expose the application port
EXPOSE 3000

# Command to run node.js in a docker container
CMD ["node", "app.js"]

Let’s break down the commands we used:

FROM: Specifies the base image to build from.
WORKDIR: Sets the working directory inside the container.
COPY: Is used to copy files from the host machine to the container.
RUN: Executes specified bash command.
CMD: Specifies the command to run when the container starts.

Step 2: Build the Docker Image

To build the Docker container image, open your terminal in the project directory and run:

sudo docker build -t node-docker-app

If the build is successful, Docker will output a series of steps and generate the image.

Step 3: Run the Container

Once the image is built, run the Node.js container using:

sudo docker run -p 3000:3000 node-docker-app

Visit http://localhost:3000 in your browser. If everything is set up correctly, you’ll see the message “Hello, Docker!” displayed.

Containerizing an Existing Node.js Application

Whether you’re working with a simple Node.js app or a more complex project, Docker can streamline the deployment process. For existing applications, this involves adapting your project structure, configuring Docker effectively, and applying best practices to ensure efficiency and consistency across environments.

1. Preparing the Node.js Application for Docker

Before containerizing an existing Node.js project, it’s important to ensure the source code is well-structured and functional. A solid foundation will help streamline the containerization process and reduce the likelihood of errors.

Ensure the package.json file is accurate:

{
  "name": "my-node-app",
  "version": "1.0.0",
  "scripts": {
    "start": "node app.js",
    "test": "jest"
  },
  "dependencies": {
    "express": "^4.18.2"
  }
}

Double-check that the scripts section includes a start script to launch the application.

Lock dependencies with package-lock.json:

npm install

This creates or updates the package-lock.json file, which ensures consistent dependency versions across environments.

Test the application locally:

npm start

Verify all routes, middleware, and features are working correctly. Fix any issues before proceeding with containerization.

Clean up unnecessary files (optional):

Remove any files or directories that are not needed in the container, such as logs, temporary files, or development-specific resources. You can use a .dockerignore file to exclude these during the build process, which we will explore in the next section.

2. Creating a .dockerignore File

The .dockerignore file plays a critical role in optimizing builds. When you build a container image, Docker sends all files in the build context to the Docker daemon.

The .dockerignore file specifies which files and directories should be excluded from this process, similarly to the .gitignore file in Git. This helps:

Minimize the size of the Docker image by avoiding redundant or irrelevant files.
Protect sensitive data, such as environment configuration files.
Speed up the build process by reducing the amount of data sent to the daemon.

Below is an example of a typical .dockerignore file for a Node.js application:

node_modules
pm-debug.log
.env
.DS_Store
logs/
tmp/
dist/
coverage/

Some best practices for the .dockerignore include:

Regularly review and update the .dockerignore file to match your project’s evolving needs.
Exclude all sensitive files, such as API keys or database credentials.
Avoid excluding essential files required for building or running your application.

3. Writing a Dockerfile for the Application

The Dockerfile is a script containing instructions for Docker to build an image of your application. A production-ready Dockerfile for a Node.js application includes several steps to optimize the image for deployment.

Our complete Dockerfile should now look something like this:

# Use a lightweight Node.js default image
FROM node:18-alpine

# Set the working directory
WORKDIR /usr/src/app

# Copy package files and install dependencies
COPY package*.json ./
RUN npm ci --only=production

# Copy application files
COPY . .

# Set environment variables for production
ENV NODE_ENV=production

# Expose the application port
EXPOSE 3000

# Command to start the application
CMD ["node", "app.js"]

4. Building and Running the Docker Image

The next step is to build the Docker image and run the containerized application.

Building the Docker Image

Use the docker build command to create the Docker image from your Dockerfile:

sudo docker build -t my-node-app .

Running the Container

To run the containerized application, use the docker run command:

sudo docker run -p 3000:3000 my-node-app

5. Optimizing the Dockerfile with Multi-Stage Builds

As applications grow in complexity, so do their build processes and dependencies. Multi-stage builds in Docker offer an effective way to reduce the size of the final image by separating the build environment from the runtime environment.

Below is an example of a multi-stage Dockerfile for a Node.js application:

# Stage 1: Build
FROM node:18-alpine AS builder

# Set the working directory
WORKDIR /usr/src/app

# Copy package files and install dependencies
COPY package*.json ./
RUN npm install

# Copy application files and build the production bundle
COPY . .
RUN npm run build

# Stage 2: Production
FROM node:18-alpine

# Set the working directory
WORKDIR /usr/src/app

# Copy only the built files from the builder stage
COPY --from=builder /usr/src/app/dist ./dist
COPY package*.json ./

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

# Set environment variables for production
ENV NODE_ENV=production

# Expose the application port
EXPOSE 3000

# Command to run the application
CMD ["node", "dist/app.js"]

6. Testing the Containerized Application

Once your Node.js application is containerized and running, it’s essential to test it to ensure it behaves as expected in a production-like environment.

Check the application with curl or a web browser.

curl http://localhost:3000

This command sends a request to the containerized application, and you should see the response printed in the terminal.

By following these steps, you can ensure that your Dockerized Node.js application is running as expected and is production-ready.

Call to Action

Ready to take your Docker and Node.js skills to the next level? Get started today with Hostinger and explore the power of containerization!

Conclusion

Dockerizing Node.js applications provides numerous benefits, including consistency across environments, simplified dependency management, and easier deployment. By encapsulating your application and its dependencies into a lightweight, portable container, you can eliminate the typical “works on my machine” issues and streamline your workflow.

In this guide, you learned how to set up a simple Node.js application, create a production-ready Dockerfile, optimize it using multi-stage builds, and test the containerized application effectively. With these skills, you are well-equipped to leverage Docker’s full potential.

How to Use Node.js with Docker FAQ

What is the benefit of using Docker with Node.js?

Docker ensures consistent environments across development, testing, and production by packaging Node.js applications with their dependencies. It simplifies deployment, improves scalability, and eliminates issues caused by environment differences.

Which Node.js Docker image should I use?

For production, use a lightweight image like node:18-alpine to minimize size and improve security. For development, node:18 or node:18-slim can be better choices, as they include additional tools and libraries useful during debugging and development.

How do I create a Dockerfile for a Node.js application?

Create a file named Dockerfile in your project’s base directory and add instructions inside – start with a base image, set a working directory, copy necessary files, install dependencies using npm ci, and define a CMD to start the application.

Can I debug a Node.js application running inside a Docker container?

Yes. Use docker exec -it sh to open a shell in the container and inspect files. Alternatively, expose the debug port (e.g., –inspect=0.0.0.0:9229) and connect your debugger to the container from your host machine or IDE.

👉 Start your website with Hostinger – get fast, secure hosting here 👈