Docker Image Node.js: How to Build & Run Node.js Apps in a Container

Docker is one of the most popular tools for packaging and deploying applications, and Node.js is no exception. By creating a Docker image Node.js application, you can ensure a consistent runtime environment, simplify the deployment, and eliminate common issues. So whether you are a developer who wants to work on containerization or preparing to scale the production workload. 

In this guide, we will walk through the process of building, running, and managing Node.js Docker container images. 

Why Use Docker for Node.js Applications?

If you are building a Node.js application, Docker definitely does make it easy on you. So instead of worrying about whether your app will behave the same way on different computers, Docker provides you with a container where everything will be set up for your app. 

Here is why it helps: 

• Docker containers are uniform so it runs the same everywhere. 
• You don’t need to install Node.js or libraries manually.
• Your app and all the dependencies are bundled together in one package. 
• You can run multiple copies, which makes it easy to scale. 
• New developers can start working on the app quickly without complex setups. 

Prerequisites for Building a Docker Image Node.js Application

Before you create a Docker image Node.js application, ensure that you have these ready on your system: 

1. Install Docker

Download and install Docker Desktop app if you are on Windows or macOS. If you are using Linux, then install Docker using the package manager, like apt or yum.

2. Have a Node.js App Ready

You will need a simple app with a package.json file in Node.js before you start working. 

3. Basic Command Line Knowledge

Familiarity with basic commands and practices. 

Building a Docker Image Node.js In Containers

Here is how you can build Docker images in Node: 

Step 1: Create a Node.js Application

Start off by building a simple Node.js app. 

1. Create a new folder:
   mkdir node-docker-app

cd node-docker-app

2. Initialize a Node.js project:
   npm init -y

This creates a package.json file.

3. Create an app.js file with this code:
   const express = require(“express”);

const app = express();

const PORT = 3000;

app.get(“/”, (req, res) => {

  res.send(“Hello from Node.js in Docker!”);

});

app.listen(PORT, () => {

  console.log(`Server running at http://localhost:${PORT}`);

});

4. Install Express (a web framework for Node.js):
   npm install express

Now you have a simple Node.js app that runs on port 3000.

Step 2: Write a Dockerfile for Node.js

The Dockerfile tells you how Docker will build your app’s image. 

Create a file named Dockerfile in your project folder and add:

FROM node:18

WORKDIR /usr/src/app

COPY package*.json ./

RUN npm install

COPY . .

EXPOSE 3000

CMD [“node”, “app.js”]

Step 3: Build the Docker Image

Then run this command inside your project folder: 

docker build -t node-docker-app .

• -t node-docker-app gives your image a name.
• . means “build from the current folder.”

Step 4: Run a Container from the Image

Once your Docker image is ready, you can run the app inside the container. 

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

• -p 3000:3000 maps your computer’s port 3000 to the container’s port 3000.
• Now open your browser and go to http://localhost:3000
• You should see: “Hello from Node.js in Docker!”

Using Official Node.js Docker Images

Using the official Node.js images makes it super simple to set up the containers. So instead of building everything from scratch, you can make use of these: 

docker run -it –name node-app -p 3000:3000 node:18

• node:18 → official Node.js image with Node.js v18.
• This gives you a ready-to-use Node environment inside Docker.

Pushing Node.js Docker Images to Docker Hub

If you want to share the Docker images with your team or deploy it on to the cloud, follow these steps: 

1. Sign in to your account on the Docker hub using: docker login
2. Tag your image with your Docker Hub username: docker tag node-docker-app your-username/node-docker-app:v1
3. Push the image to Docker Hub: docker push your-username/node-docker-app:v1
4. Now, anyone can run your image with: docker run -p 3000:3000 your-username/node-docker-app:v1

Running Node.js with Docker Compose

Docker Compose enables you to manage multiple containers at once using a single file. 

Example docker-compose.yml:

version: “3”

services:

  app:

    image: node:18

    working_dir: /usr/src/app

    volumes:

      – .:/usr/src/app

    ports:

      – “3000:3000”

    command: npm start

Then run:

docker-compose up

This will start your Node.js app automatically with all settings.

Common Issues and Troubleshooting

Issue	Cause	Solution
Error: Cannot find module ‘express’	Dependencies not installed inside container	Run npm install inside the Dockerfile before starting
EADDRINUSE: Port 3000 already in use	Another process is using port 3000	Run on a different port using -p 4000:3000
Permission denied errors	Wrong file permissions inside container	Use USER node in Dockerfile or adjust file permissions
Container exits immediately	Missing CMD or app crashed	Check logs with docker logs <container_id>
Image too large	Unnecessary files copied into image	Add .dockerignore to exclude node_modules, logs, etc.

Conclusion

Using Docker images with Node.js makes your app scalable, consistent, easily deployable, and portable. You can either choose to go with custom images built using a Dockerfile or use the official images available online for a quick setup. Either way, it makes your job easy!