Running Node.js in Docker for local development

Devops folks who use Dock­er often have no desire to use JavaScript, and JavaScript devel­op­ers often have no desire to do devops.

How­ev­er, Node.js + Dock­er real­ly is a match made in heaven.

Hear me out.

You don’t have to learn Dock­er in-depth to reap the ben­e­fits from using it.

Whether you’re just using Node.js as a way to run a build­chain to gen­er­ate fron­tend assets that uses Grunt / Gulp / Mix / web­pack / NPM scripts, or you’re devel­op­ing full-blown Node.js apps, you can ben­e­fit from run­ning Node.js in Docker.

In this arti­cle, we’ll show you how you can uti­lize Dock­er to run your Node.js build­chains & apps in local dev with­out need­ing to know a whole lot about how Dock­er works.

Unless you install every NPM package you use globally, you already understand the need for containerization

We’ll be run­ning Node.js on-demand in Dock­er con­tain­ers that run in local dev only when you’re build­ing assets with your build­chain or devel­op­ing your application.

All you’ll need to have installed is Dock­er itself.

If you’re the TL;DR type, you can check out the exam­ple project we used at: eleven­ty-blog-base feature/​docker branch, or look at the master..feature/docker diff.

Link Why in the world would I use Docker?

I think this tweet from Adam Wathan is a per­fect exam­ple of why you would want to use Docker:

“Upgraded Yarn, which broke PHP, which needs Python to reinstall, which needs a new version of Xcode, which needs the latest version of Mojave, which means I need a beer and it’s only noon.”—Adam Wathan

Adam’s cer­tain­ly not alone, this type of ​“depen­den­cy hell” is some­thing that most devel­op­ers have descend­ed down into at some point or another.

And hav­ing one glob­al install for your entire devel­op­ment envi­ron­ment only gets worse from here:

• Updat­ing a depen­den­cy like the Node.js ver­sion for one app may break oth­er apps
• You end up using the old­est pos­si­ble ver­sion of every­thing to keep the tee­ter­ing devel­op­ment envi­ron­ment running
• Try­ing new tech­nolo­gies is cost­ly, because your whole devel­op­ment envi­ron­ment is at risk
• Updat­ing oper­at­ing sys­tem ver­sions often means putting aside a day (or more) to rebuild your devel­op­ment environment
• Get­ting a new com­put­er sim­i­lar­ly means putting aside a day (or more) to rebuild your devel­op­ment environment

Instead of hav­ing one mono­lith­ic local devel­op­ment envi­ron­ment, using Dock­er adds a lay­er of con­tainer­iza­tion that gives each app you are work­ing on exact­ly what it needs to run.

Your computer isn’t disposable, but Docker containers are

Is it quick­er to just start installing stuff via Home­brew on your com­put­er? Sure.

But peo­ple often con­fuse get­ting start­ed quick­ly with speed. What mat­ters more is the speed (and san­i­ty) with which you finish.

So let’s give Dock­er a whirl.

Link Docker setup overview

We’re not going to teach you the ins and outs of Dock­er here; if you want that, check out the An Anno­tat­ed Dock­er Con­fig for Fron­tend Web Devel­op­ment article.

I also high­ly rec­om­mend the Dock­er Mas­tery course (if it’s not on sale now, don’t wor­ry, it will be at some point).

Instead, we’re just going to put Dock­er to work for us. Here’s an overview of how this is going to work:

We’re using make with a Make­file to pro­vide a nice easy way to type our ter­mi­nal com­mands (yes, Vir­ginia, depen­den­cy man­ag­ing build sys­tems have been around since 1976).

Then we’re also using a Dock­er­file that con­tains the infor­ma­tion need­ed to build & run our Dock­er container.

We then lever­age NPM scripts in the scripts sec­tion of our package.json to run our build­chain / application:

So we’ll type some­thing like:

And it will spin up our Node.js Dock­er con­tain­er, and run the build script that’s in the scripts sec­tion of our package.json.

Since we can put what­ev­er we want in the scripts sec­tion of our package.json, we can run what­ev­er we want.

It may seem complicated, but it’s actually relatively simple how it all works

So let’s have a look at how this all works in detail.

Link Docker setup detail

So as to have a real-world exam­ple, what we’re going to do is cre­ate a Dock­er con­tain­er that builds a web­site using the pop­u­lar 11ty sta­t­ic site generator.

I cre­at­ed a pull request (PR) for this 11ty Dock­er set­up, too, so who knows, it might be rolled into the eleven­ty-blog-base repo.

If you want to run this your­self with­out fol­low­ing the steps below, you can just clone my fork of the repo via:

and then fol­low the Run Eleven­ty via Dock­er docs to get it up and running.

Keep in mind that this is just an example, we could be containerizing any Node.js buildchain or app

Now let’s take this step by step to get up and running.

So what we’ll do is make a clone of the eleven­ty-base-blog repo:

Then we’ll make just one change to the package.json that comes from the repos­i­to­ry, adding an install npm script:

MAKE­FILE

Next we’ll cre­ate a Makefile in the project direc­to­ry that looks like this:

The way make works is that if you type make, it looks for a Makefile in the cur­rent direc­to­ry for the recipe to make. In our case, we’re just using it as a con­ve­nient way to cre­ate alias­es that are local to a spe­cif­ic project.

So we can use make as a short­cut to run much more com­pli­cat­ed com­mands that aren’t fun to type:

• make docker — this will build our Node.js Dock­er image for us. You need to build a Dock­er image from a Dock­er­file before you can run it as a container
• make npm run xxx — once built, this will run our Dock­er con­tain­er, and exe­cute the NPM script named xxx as list­ed in the package.json. For instance, make npm run build will run the build script

The TAG?=12-alpine line pro­vides a default Node.js tag to use when build­ing the image, with the num­ber part of it being the Node.js ver­sion (“alpine” is just a very slimmed down Lin­ux distro).

If we want­ed, say, Node.js 14, we could just change that to be TAG?=14-alpine and do a make docker or we could pass it in via the com­mand line for a quick tem­po­rary change: make docker TAG=14.alpine

It’s just that easy to switch the Node.js version

While it’s not impor­tant that you learn the syn­tax of make, let’s have a look at the two com­mands we have in our Makefile.

The \ you see in the Makefile is just a way to allow you to con­tin­ue a shell com­mand on the next line, for read­abil­i­ty reasons.

• docker: # the com­mand alias, so we run it via make docker
  • docker build \ # Build a Dock­er con­tain­er from a Dockerfile
  • . \ # …in the cur­rent directory
  • -t nystudio107/node:${TAG} \ # tag the image with nystudio107/node:12-alpine (or what­ev­er ${TAG} is)
  • --build-arg TAG=${TAG} \ # pass in our ${TAG} vari­able as an argu­ment to the Dockerfile
  • --no-cache # Do not use cache when build­ing the image
• npm: # the com­mand alias, so we run it via make npm run xxx, where xxx is the npm script to run
  • docker container run \ # Run a Dock­er con­tain­er from an image
  • --name 11ty \ # name the con­tain­er instance ​“11ty”
  • --rm \ # remove the con­tain­er when it exits
  • -t \ # pro­vide a ter­mi­nal, so we can have pret­ty col­ored text
  • -p 8080:8080 \ # map port 8080 from inside of the con­tain­er to port 8080 to serve our hot reloaded files from http://localhost:8080
  • -p 3001:3001 \ # map port 3001 from inside of the con­tain­er to port 3001 to serve the Browser­Sync UI from http://localhost:3001
  • -v "${CURDIR}":/app \ # mount a vol­ume from the cur­rent work­ing direc­to­ry to /app inside of the Dock­er container
  • nystudio107/node:${TAG} \ # use the Dock­er image tagged with nystudio107/node:12-alpine (or what­ev­er ${TAG} is)
  • $(filter-out $@,$(MAKECMDGOALS)) # a fan­cy way to pass any addi­tion­al argu­ments from the com­mand line down to Docker

We do the port map­ping to allow 11ty’s hot reload­ing to work dur­ing development.

DOCK­ER­FILE

Now we’ll cre­ate a Dock­er­file in the project root directory:

Our Dockerfile is pret­ty small, but let’s break down what it’s doing:

ARG TAG=12-alpine — Set the build argu­ment TAG to default to 12-alpine. If a --build-arg is pro­vid­ed, it’ll over­ride this so you can spec­i­fy oth­er Node.js version

FROM node:$TAG — Des­ig­nate which base image our con­tain­er will be built from 

WORKDIR /app — Set the direc­to­ry where the com­mands in the Dock­er­file are run to /app

CMD ["run build"] — Set the default com­mand to run build

ENTRYPOINT ["npm"] — When the con­tain­er is spun up, it’ll exe­cute npm xxx where xxx is an argu­ment passed in via the com­mand line, or it’ll fall back on the default run build command

Link Taking Docker for a spin

So let’s take Dock­er for a spin on this project. First we’ll make sure we’re in the project root direc­to­ry, and build our Dock­er con­tain­er with make docker:

Next let’s exe­cute the install script we added to our package.json via make npm install. This runs an npm install, which we only need to do once to get our node_module depen­den­cies installed:

Final­ly, let’s fire up a hot reload­ing devel­op­ment serv­er, and build our site via make npm run serve. This is the only step you’ll nor­mal­ly need to do in order to work on your site:

We can just point our web brows­er at http://localhost:8080 and we’ll see our web­site up and running:

If we make any changes, they’ll auto­mat­i­cal­ly be hot reloaded in the brows­er, so away we go!

“Yeah, so what?” you say?

Real­ize that with the Makefile and Dockerfile in place, we can hand our project off to some­one else and onboard­ing becomes bliss:

• We won’t need to care what ver­sion of Node.js they have installed
• They don’t even have to have Node.js installed at all, in fact

Addi­tion­al­ly, we can come back to the project at any time and:

• The project is guar­an­teed to work, since the devops need­ed to run it is ​“shrink wrapped” around it
• We can eas­i­ly switch Node.js ver­sions with­out affect­ing any­thing else

No more nvm. No more n. No more has­sles switch­ing Node.js ver­sions.

Link Containerization as a way forward

Next time you have the oppor­tu­ni­ty to start fresh with a new com­put­er or a new oper­at­ing sys­tem, con­sid­er tak­ing it.

Don’t install Homebrew.

Don’t install Node.js.

Don’t install dozens of packages.

Instead, take the con­tainer­iza­tion chal­lenge and just install Dock­er, and run every­thing you need from containers

I think you may be pleas­ant­ly sur­prised at how it’ll make your life easier.