How to Dockerize a Legacy Node.js Project: A Step-by-Step Guide

Dockerizing a legacy Node.js project — especially one with outdated dependencies or that has been dormant for some time — can feel daunting. This guide walks you through the process, highlighting common pitfalls and how to avoid them. By the end, you’ll have your legacy Node.js app running smoothly in a Docker container.

Why Dockerize a Legacy Project?

Dockerizing your project provides a consistent environment for development, testing, and production. It ensures that your app runs the same way regardless of where it’s deployed, eliminating “works on my machine” issues.

While Docker offers benefits for any Node.js project, it is particularly advantageous for legacy projects that may be difficult to run in modern development environments. Legacy projects often rely on outdated dependencies, specific versions of Node.js, or older operating systems, which can be challenging to replicate on a modern machine.

Docker solves this by allowing you to define the exact environment your application needs, encapsulating it in a container that can run consistently across different systems. This is especially useful in scenarios where you need to maintain or update a legacy project while ensuring it continues to function as expected.

By using Docker, you can avoid the headaches of dependency conflicts, ensure compatibility with legacy software, and simplify the process of setting up and tearing down development environments.

Getting Started: Using NVM for Simple Use Cases

Before jumping into Docker, consider using Node Version Manager (NVM) to manage the Node.js versions on your local machine. NVM allows you to install and switch between multiple Node.js versions, making it easier to run older projects that depend on a specific version.

Example of using NVM:

# Install NVM
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.1/install.sh | bash
# Install a specific Node.js version (e.g., 6.11.4)
nvm install 6.11.4
# Use the installed Node.js version
nvm use 6.11.4

While NVM is great for local development, Docker is a better solution for ensuring consistent environments across different stages of deployment.

Step 1: Setting Up the Dockerfile

After installing Docker and verifying that it works, the first step in Dockerizing your Node.js project is to create a Dockerfile. This file defines the environment in which your app will run.

Here’s a basic Dockerfile tailored for a legacy Node.js project:

# Use an official Node.js runtime as a parent image
FROM node:6.11.4

# Set the working directory in the container
WORKDIR /public

# Copy package.json and yarn.lock (or package-lock.json) before running install
COPY package.json yarn.lock ./

# Install dependencies with Yarn
RUN yarn install --frozen-lockfile

# Copy the rest of the application files to the container
COPY . .

# Make port 3001 (or the port you're using) available to the
# world outside the container
EXPOSE 3001

# Run app using "yarn start" or "npm start" depending on
# your project setup
CMD ["yarn", "start"]

Explaining each command

Each instruction in the Dockerfile plays a crucial role in setting up the containerized environment for your legacy Node.js project. The FROM statement specifies the base image, which in this case is a Node.js runtime. This ensures that the container will have the correct version of Node.js installed, which is vital for running legacy projects that rely on specific versions of Node.js and npm. The WORKDIR instruction sets the working directory within the container, allowing subsequent instructions to operate within this context.

Copying the package.json and yarn.lock files first allows Docker to cache the installation of dependencies, so if you only change your application code, Docker can reuse the cached dependencies layer, speeding up the build process. The CMD instruction defines the command that will run when the container starts, in this case, using Yarn to start the application. Understanding these instructions helps you create more efficient and reliable Docker images.

Common Pitfall: Updated Dependencies

If your package.json and yarn.lock are not in sync when the Docker container installs dependencies during the build process, you may end up with some future version of a package that is incompatible with your legacy project.

To avoid this, make sure you’re using yarn install --frozen-lockfile, which ensures that the exact versions specified in yarn.lock are installed until you’ve had time to evaluate if you really need to update your yarn.lock.

Step 2: Handling Legacy Tools and Commands

Legacy projects often rely on outdated tools like Gulp. In modern Node.js environments, npx is commonly used to execute local binaries. However, in older Node.js versions (like 6.x), npxisn’t available.

Example Problem: Yarn Not Found

If your project relies on a package that is typically globally installed like Yarn, you might encounter an error like:

/bin/sh: 1: yarn: not found

Solution: Installing packages globally

When you need to install global packages in your Docker container, specify them in your Dockerfile:

...

# Optional: Install Yarn only if it's not installed
RUN if ! [ -x "$(command -v yarn)" ]; then yarn install -g yarn; fi

...

I like to globally instead yarn right before copying package.json . Ensure you’re installing yarn before running any commands that require the package.

Step 3: Setting Up docker-compose.yml

To simply running your Docker application, use Docker Compose. The docker-compose.yml file defines how the services in your application interact. Here’s an example docker-compose.yml for your legacy Node.js project:

services:
 app:
   build: .
   volumes:
     - .:/public
   ports:
     - "3001:3001"
   #concurrently run gulp watch and yarn start
   command: sh -c "yarn run watch & yarn start"

Explanation:

— build: specifies that the Dockerfile in the current directory should be used to build the image.

— volumes: mounts the current directory into the container’s /public directory, allowing live editing of files.

— ports: maps port 3001 of the container to port 3001 of the host machine.

— command: specifies the command to run the application, in this case, yarn run watch & yarn start.

Common Pitfall: Incorrect Port Mapping

One of the issues you might encounter is that Docker or any proxy server in your code is not correctly forwarding requests to the right port. Verify what port your server is running on, and add this to your docker-compose.yml .

Step 4: Rebuilding and Testing the Docker Image

After making changes to your Dockerfileor cleaning up Docker resources, it’s essential to rebuild your Docker image:

docker-compose up - build

If you’re still running into issues, it might be related to the Docker cache. In that case, use the — no-cacheflag to force a clean build:

docker-compose build --no-cache
docker-compose up

Docker isn’t just a tool for maintaining legacy projects — it can also play a crucial role in modernizing them. By containerizing your legacy application, you can incrementally update and refactor parts of your codebase with confidence, knowing that any changes can be easily rolled back by simply reverting to a previous Docker image. Docker also makes it easier to adopt modern development practices, such as continuous integration and continuous deployment (CI/CD), by providing a standardized environment for testing and deployment. This approach allows you to modernize your legacy system over time, gradually introducing new technologies and practices without the need for a complete rewrite.

Conclusion

Dockerizing a legacy Node.js project can be challenging, especially when dealing with outdated dependencies and tools. By following these steps and being mindful of common pitfalls, you can successfully containerize your app and enjoy the benefits of a consistent, portable development environment.

Remember, while Docker provides a robust solution for running legacy projects, understanding the intricacies of your project’s dependencies and environment is key to a smooth Dockerization process. For more a more exhaustive list of Docker commands and how it works, check out this article.

Happy coding!