Are you tired of the dreaded "it works on my machine" syndrome? By packaging your application and its dependencies into portable, self-contained units called containers, Docker ensures consistent behavior across different environments, from development to production.
In this hands-on guide, I'll show you how to effortlessly "Dockerize" your Node.js applications to unlock a smoother and more reliable development and deployment process.
Let's get started!
To demonstrate Node.js application development and deployment with Docker, we'll use a URL shortener application built with Fastify that stores shortened URLs in PostgreSQL. Our goal is to create a custom Docker image to run this application in various environments.
Begin by cloning the application from GitHub:
Navigate into the project directory and install its dependencies:
Before running the application, we need a PostgreSQL database. Launch a PostgreSQL Docker container using the Alpine variant of its official image:
If you don't have the postgres:alpine image, it will be downloaded from
DockerHub. The container will be named url-shortener-db, removed upon stopping
(--rm), and have port 5432 mapped to the same port on your host machine.
Two environmental variables are also supplied to the container:
POSTGRES_PASSWORD: This sets a password for the default postgres user.
You must provide a value to this variable to use the PostgreSQL image.
POSTGRED_DB: This allows you to specify the name of the default database
that will be created when the container is launched.
If you have a local PostgreSQL instance, stop it first to avoid port conflicts:
A successful launch of the container will output logs confirming database readiness:
With the database running, open a new terminal, navigate to the project
directory, then copy .env.sample to .env and modify the POSTGRES entries
within as needed:
With the .env file created and updated, apply the database migrations and
start the Node.js application:
The console output will indicate the application running on port 5000:
You may now open http://localhost:5000 to see the application interface:
Test its functionality by shortening a URL and clicking Visit to verify redirection:
With a functional Node.js application set up, you're now ready to containerize it using Docker.
Once your Node.js app is running in a container, make sure it stays reachable. Better Stack Uptime Monitoring checks your endpoints from multiple regions and alerts you fast when something breaks, with timelines, error details, and screenshots so you can pinpoint the cause.
To deploy our Node.js application, we'll create a Docker image using a Dockerfile. This text file provides instructions to the Docker engine on constructing the image.
Think of a Docker image as a template capturing your application and its environment. It includes configuration details and a layered filesystem containing the software required to run your application. A Docker container is a live, isolated environment created from this image where your application runs.
Essentially, Docker images define the application's build and packaging process, while containers are the running instances.
Let's start by examining the format of the Dockerfile which is shown below:
Any line that begins with a # is a comment (except
parser directives),
while other lines must contain a specific command followed by its arguments.
Although command names are not case-sensitive, they are often written in
uppercase to distinguish them from arguments.
Let's create a Dockerfile to build our URL shortener's Docker image:
The first decision to make when writing a Dockerfile is choosing an
appropriate base image. This image must be capable of running Node.js code so
that your application can run within the container. A common choice is the
official Node.js image which comes
pre-installed with the necessary runtime environment for running Node.js
applications.
I recommend using the latest LTS version (v20.16.0 at the time of writing) to guarantee stability when deploying to production. For the most up-to-date information, check the Node.js releases page.
There are also several variants to pick from, but I recommend using the latest Alpine variant as it is known for being exceptionally lightweight and simple.
Go ahead and enter the base image into your Dockerfile as follows:
This image sets up a functional Node.js environment, saving us setup time. All subsequent instructions will be built upon this base.
Next, change the working directory within the image to /build with the
WORKDIR instruction:
This directive avoids the need to run mkdir and cd when you want to navigate
into a new directory.
Installing your application dependencies is the next step. Before proceeding,
you need to copy the package.json and package-lock.json files into the image
with the COPY directive:
Copying package.json and package-lock.json first optimizes Docker builds by
leveraging layer caching. Since
dependencies change less frequently than application code, this ensures that the
subsequent dependency installation instruction is only re-executed when those
files are modified, leading to significantly faster build times when only the
source code changes.
Let's add the instruction to install the application dependencies next:
Here, we've opted for npm ci over npm install for faster and more consistent
builds. It removes any existing node_modules directory and installs production
dependencies (without devDependencies) precisely as listed in
package-lock.json without modifying this file. Clearing the cache also helps
reduce image size since it's not needed within the container.
Now that you've installed the application dependencies, the next step is to copy the rest of the source code into the image:
Next, you can document the ports that a container built on this image will
listen on using the EXPOSE instruction:
Finally, specify the command to run when starting the application:
The CMD instruction defines the command for launching the application in a
container based on this image. We're using the node command directly here
instead of npm start because the latter doesn't forward termination signals
like SIGTERM to the application (for a graceful shutdown) but kills it
directly.
The final Dockerfile is thus:
With these instructions in place, you're ready to build the Docker image.
Having prepared your Dockerfile, you can create the Docker image using the
docker build command. Before proceeding, create a .dockerignore file in your
project's root directory to exclude unnecessary files from the build context.
This helps with reducing image size, speeding up builds, and preventing
accidental inclusion of sensitive information.
In our case, we'll ignore any .env files, the .git directory, and the
node_modules directory:
Now, build the Docker image from your project root:
The -t flag assigns the url-shortener name to the image. You can also add a
specific tag, such as 0.1.0, using the command below. Without a tag, Docker
defaults to latest.
After the build, verify the new image exists in your local library:
Now, run the image as a Docker container with docker run:
However, this command fails due to missing environment variables:
The error indicates that the application could not find some required
environmental variables when starting the container. This makes sense since the
.env file wasn't copied over to the Docker image to prevent secrets from
leaking into the image.
To resolve this, pass environment variables from the .env file to the
container through the --env-file flag:
Now we get a different error:
This occurs because the application is configured to connect a PostgreSQL
instance running on localhost within the container, where PostgreSQL isn't
running.
To enable communication between the application container and the
url-shortener-db container, create a custom
Docker network:
Stop the existing url-shortener-db container with Ctrl-C, and restart it on
the new url-shortener network through the --network option:
Once it's up and running once again, update your .env file as follows:
The POSTGRES_HOST variable has been updated from localhost to
url-shortener-db, which makes it possible for application container to
communicate with the PostgreSQL instance running in the url-shortener-db
container.
Finally, launch the application once again and apply the --network option like
this:
You will observe that it is successful now:
However, when you try to visit http://localhost:5000, you will observe that
the application doesn't load:
Fastify (and other servers) typically listen for connections only on the local
interface (127.0.0.1) when running on a host machine. However, this isn't
sufficient within a Docker container as the host and other network devices can't
access it.
To enable external connections, Fastify needs to bind to an address accessible
outside the container. Using 0.0.0.0 achieves this by binding to all available
network interfaces, allowing Fastify to receive connections from any reachable
IP address.
Open your server.js file and modify the following line by adding the host
property:
Save the file, then quit the existing url-shortener-app container with
Ctrl-C. Now build a new version of your url-shortener Docker image to
replace the existing one:
Once it finishes, relaunch the container once again:
The application should now be accessible at http://localhost:5000.
Web servers like Nginx or Caddy are often placed before Node.js applications to enhance performance and security. They excel at tasks like load balancing, reverse proxying, serving static assets, and handling SSL/TLS termination and caching. While Node.js can handle some of these, a dedicated web server is often a more performant and robust solution for production environments.
Let's set up a Caddy instance as a reverse proxy for our Node.js application. Keep both the application and PostgreSQL containers running, then open a new terminal and launch a Caddy container based on the official Alpine image:
Ensure to keep both application and PostgreSQL containers running, then open a new terminal and launch a new container for Caddy by running the command below:
Once you see the "serving initial configuration" message, you can visit
http://localhost in your browser to view the Caddy default page:
Exit the container with Ctrl-C and create a Caddyfile in the project root:
Populate it with the following contents:
This Caddyfile configures a web server on http://localhost that forwards all
incoming requests to the url-shortener-app host listening on port 5000.
To see this in action, relaunch the Caddy container and add the highlighted options below for persistent storage and network connectivity:
This command now includes persistent volumes (caddy-config and caddy-data)
to store configuration and data, respectively. It also mounts your custom
Caddyfile and connects to the url-shortener network for communication with
the app container.
Now, when you access http://localhost, you should see the URL shortener
application functioning as it did before, but with the added benefits of a
dedicated web server. Do check out the
Caddy docs for more details.
I'm sure you'll agree that running multiple containers to get your application going is quite tedious, especially if your application isn't a monolith like in this demo but contains multiple microservices all running in standalone containers.
This is where Docker Compose comes in.
Instead of manually creating and managing individual Docker containers using the
docker run command, Compose offers a solution by allowing you to define and
manage multi-container applications within a single YAML file. This streamlines
your workflow and provides a structured approach for complex applications.
Let's create a docker-compose.yml file in your project's root directory to
configure your Node.js application and its associated services:
This configuration defines three services:
app: Your URL shortener application that is dependent on a health postgres
service.
caddy: A Caddy web server acting as a reverse proxy, serving on port 80 and
using a custom Caddyfile.
postgres: An Alpine Linux-based PostgreSQL database, configured with
specific settings and a health check to ensure readiness.
These services share the url-shortener network and utilize volumes to persist
data. Placeholders are used for environment variables, which will be populated
from your .env file when the containers are started. Notably, port 5000 isn't
published anymore, making the app accessible only via Caddy at
http://localhost.
Before bringing up your services with docker compose, run the command below to
stop and remove the existing containers with:
Now, run the following command to launch all three services with Compose:
This builds the app image and launches all three services in the foreground.
You'll notice that the respective logs produced by each container are prefixed
with the container name as shown below:
You can also run the services in the background through the --detach option.
Stop the existing instances with Ctrl-C first, then run:
Verify they're running with docker compose ps:
To stop and remove the running containers, execute:
There you have it! You can now launch all your services and their dependencies
with a single command and stop them again as needed. Creating additional
services is also as easy as adding a new service definition in the
docker-compose.yml file.
Let's move on now to exploring how to develop your application directly within Docker.
With Better Stack Logs, you can stream logs in real time, search across containers, and spot patterns like failing health checks or error spikes after a deploy.
Now that you've mastered image creation and multi-container management with Docker Compose, let's transform Docker into a productive development environment. This will simplify setup on your local machine and ensure a standardized workflow for the rest of your team.
Begin by modifying your Dockerfile to make use of
multi-stage builds:
We've introduced a development stage inheriting from the base image,
designed to execute npm run dev from the /app directory. The production
stage, intended for production builds, retains the original instructions.
The application dependencies are now being installed in the /node directory
without omitting the devDependencies this time around. This is essential since
you can't guarantee that everyone will be using host OS for development.
You'll also notice that we didn't copy the project's contents into /node/app
for the development stage; instead, we'll mount the local directory for live
development and enable automatic reloads via nodemon.
Next, update the app portion of your docker-compose.yml file:
The services.app.build.target value is now set to ${NODE_ENV} so that when
you're building the application appropriate stage is used instead according what
the value supplied through the .env file.
On the other hand, the current directory is mounted to the /node/app directory
within the container. This also mounts the local node_modules directory into
the container negating the effect of installing the dependencies to /node in
the first place.
To mitigate this, we've added an anonymous volume to hide the container's local
node_modules directory. Node.js's module resolution algorithm ensures that the
node_modules directory in the /node directory is found and used as a result.
To launch the application in development mode, all you need to do is change your
NODE_ENV entry to development:
Then run:
After building the Docker image, everything should start up the same way as before:
You'll notice that this time around, the dev script was executed and nodemon
is now watching for changes. Since we mounted the project directory to the
docker container, making changes as usual will trigger a restart of the
application.
You can test this out by adding a simple health check route to your application code:
Once you save the file, you'll notice that the application restarts in the
url-shortener-app container:
You can now send a request to http://localhost/health and you should get the
correct response:
The only time you'll need to rebuild the image in development is when you add or remove a dependency to your project.
With this setup, you only need access to the source code and Docker installed on the host machine to create a complete Node.js development environment with a single command.
If you're a VS Code user, you might want to check out the Dev Containers extension to enhance your local development workflow even further. The relevant tooling for other editors may be found here.
With Better Stack, you can use eBPF instrumentation to capture request traces automatically, even in containers, without adding tracing libraries or changing your app code.
Throughout this guide, you've gained hands-on experience in preparing a Docker image for your Node.js application and using it for local development or production deployment.
But this is just the beginning of your Docker journey! There are countless opportunities for optimizing your development and deployment workflows even further.
Ensure to check out the following resources on Dockerfile best practices, security recommendations, logging in Docker and deploying containerized apps to AWS to take your usage to the next level.
If you'd like to continue experimenting with the demo app, do check out the updated source code on GitHub.
Thanks for reading, and happy coding!
This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.
We use cookies to authenticate users, improve the product user experience, and for personalized ads. Learn more.