Use Docker to Create a Node Development Environment

In this tutorial, instead of creating and running a Node app locally, you'll to take advantage of the Debian Linux operating system that official Docker Node images are based on. You'll create a portable Node development environment that solves the "But it runs on my machine" problem that constantly trolls developers since containers are created predictably from the execution of Docker images on any platform.

Throughout this tutorial, you'll be working in two realms:

• Local Operating System: Using a CLI application, such as Terminal or PowerShell, you'll use a local installation of Docker to build images and run them as containers.

• Container Operating System: Using Docker commands, you'll access the base operating system of a running container. Within that context, you'll use a container shell to issue commands to create and run a Node app.

The container operating system runs in isolation from the local operating system. Any files created within the container won't be accessible locally. Any servers running within the container can't listen to requests made from a local web browser. This is not ideal for local development. To overcome these limitations, you'll bridge these two systems by doing the following:

• Mount a local folder to the container filesystem: Using this mount point as your container working directory, you'll persist locally any files created within the container and you'll make the container aware of any local changes made to project files.

• Allow the host to interact with the container network: By mapping a local port to a container port, any HTTP requests made to the local port will be redirected by Docker to the container port.

To see this Docker-based Node development strategy in action, you'll create a basic Node Express web server. Let's get started!

Removing the Burden of Installing Node

To run a simple "Hello World!" Node app, the typical tutorial asks to:

• Download and install Node
• Download and install Yarn
• To use different versions of Node, uninstall Node and install

  nvm

• Install NPM packages globally

Each operating system has its own quirks making the aforementioned installations non-standard. However, access to the Node ecosystem can be standardized using Docker images. The only installation requirement for this tutorial is Docker. If you need to install Docker, choose your operating system from this Docker installation document and follow the steps provided.

Similar to how NPM works, Docker gives us access to a large registry of Docker images called Docker Hub. From Docker Hub, you can pull and run different versions of Node as images. You can then run these images as local processes that don't overlap or conflict with each other. You can simultaneously create a cross-platform project that depends on Node 8 with NPM and another one that depends on Node 11 with Yarn.

Creating the Project Foundation

To start, anywhere in your system, create a

node-docker

With the goal of running a Node Express server, under the

node-docker

server.js

// server.js
const express = require("express");
const app = express();

const PORT = process.env.PORT || 8080;

app.get("/", (req, res) => {
  res.send(`
    <h1>Docker + Node</h1>
    <span>A match made in the cloud</span>
  `);
});

app.listen(PORT, () => {
  console.log(`Server listening on port ${PORT}...`);
});

A Node project needs a

package.json

node_modules

Accessing the Container Operating System

You can gain access to the container OS with any of the following methods:

• Using a single but long

  docker run

  command.
• Using a

  Dockerfile

  combined with a short

  docker run

  command.
• Using a

  Dockerfile

  in combination with Docker Compose.

Using a single

docker run

command

Execute the following command:

docker run --rm -it --name node-docker \
-v $PWD:/home/app -w /home/app \
-e "PORT=3000" -p 8080:3000  \
-u node node:latest /bin/bash

Let's breakdown this

docker run

docker run --rm -it

docker run

--rm

-i

-t

-i

-t

Think of

--rm

as "out of sight, out of mind".

Without the

-it

team, you won't see anything on the screen.

docker run --rm -it --name node-docker

The

--name

docker ps

docker run --rm -it --name node-docker \
-v $PWD:/home/app -w /home/app

The

-v

<HOST FOLDER RELATIVE PATH>:<CONTAINER FOLDER ABSOLUTE PATH>

An environmental variable can print the current working directory when the command is executed:

$PWD

$CD

-w

docker run --rm -it --name node-docker \
-v $PWD:/home/app -w /home/app \
-e "PORT=3000" -p 8080:3000

The

-e

PORT

3000

-p

8080

3000

PORT

server.js

const PORT = process.env.PORT || 8080;

docker run --rm -it --name node-docker \
-v $PWD:/home/app -w /home/app \
-e "PORT=3000" -p 8080:3000  \
-u node node:latest /bin/bash

For security and to avoid file permission problems, the

-u

node

node:latest

/bin/bash

If the image is not present locally, Docker issues

docker pull

in the background to download it from Docker Hub.

Once the command executes, you'll see the container shell prompt:

node@<CONTAINER ID>:/home/app$

Before moving to the next method, exit the container terminal by typing

exit

<ENTER>

Using a

Dockerfile

The

docker run

docker run --rm -it --name node-docker \
-v $PWD:/home/app -w /home/app \
-e "PORT=3000" -p 8080:3000  \
-u node node:latest /bin/bash

Anything related to image build time can be defined as a custom image using a

Dockerfile

• FROM

  specifies the container base image:

  node:latest

• WORKDIR

  defines

  -w

• USER

  defines

  -u

• ENV

  defines

  -e

• ENTRYPOINT

  specifies to execute

  /bin/bash

  once the container runs

Based on this, under the

node-docker

Dockerfile

FROM node:latest

WORKDIR /home/app
USER node
ENV PORT 3000

EXPOSE 3000

ENTRYPOINT /bin/bash

EXPOSE 3000

docker run

The custom image defined within

Dockerfile

docker build

docker build -t node-docker .

docker build

node-docker

-t

docker images

With the image built, execute this shorter command to run the server:

docker run --rm -it --name node-docker \
-v $PWD:/home/app -p 8080:3000 \
node-docker

The container shell prompts comes up with the following format:

node@<CONTAINER ID>:/home/app$

Once again, before moving to the next method, exit the container terminal by typing

exit

<ENTER>

Using Docker Compose

For Linux, Docker Compose is installed separately.

Based on the

Dockerfile

docker run

Dockerfile

FROM node:latest

WORKDIR /home/app
USER node
ENV PORT 3000

EXPOSE 3000

ENTRYPOINT /bin/bash

Command

docker run --rm -it --name node-docker \
-v $PWD:/home/app -p 8080:3000 \
node-docker

The only elements left to abstract from the

docker run

Under the

node-docker

docker-compose.yml

version: "3"
services:
  nod_dev_env:
    build: .
    container_name: node-docker
    ports:
      - 8080:3000
    volumes:
      - ./:/home/app

• nod_dev_env

  gives the service a name to easily identify it

• build

  specifies the path to the

  Dockerfile

• container_name

  provides a friendly name to the container

• ports

  configures host-to-container port mapping

• volumes

  defines the mounting point of a local folder into a container folder

To start and run this service, execute the following command:

docker-compose up

up

docker run

docker build

docker image
# Notice the image named <project-folder>_nod_dev_env
docker ps -a
# Notice the container named <project-folder>_nod_dev_env_<number>

up

up

docker-compose.yml

docker-compose run

nod_dev_env

First, to clean the images and containers created by

up

docker-compose down

Then, execute the following command to run the service:

docker-compose run --rm --service-ports nod_dev_env

The

run

docker run -it

--service-ports

node@<CONTAINER ID>:/home/app$

If for any reason the ports specified in the Docker Compose file are already in use, you can use the

--publish

-p

4000

3000

docker-compose run --rm -p 4000:3000 nod_dev_env

Installing Dependencies and Running the Server

If you don't have an active container shell, using any of the previous section methods to access it.

In the container shell, initialize the Node project and install dependencies by issuing the following commands (if you prefer, use

npm

):

yarn init -y
yarn add express
yarn add -D nodemon

Verify that

package.json

node_modules

node-docker

nodemon

nodemon

package.json

{
  // Other properties...
  "scripts": {
    "start": "nodemon server.js"
  }
}

In the container shell, execute

yarn start

To test the server, visit

http://localhost:8080/

8080

3000

To test the connection of local file content and server, open

server.js

// server.js

// package and constant definitions...

app.get("/", (req, res) => {
  res.send(`
    <h1>Hello From Node Running Inside Docker</h1>
  `);
});

// server listening...

Refresh the browser window and observe the new response.

Modifying and Extending the Project

Assuming that Node is not installed in your local system, you can use the local terminal to modify project structure and file content but you can't issue any Node-related commands, such as

yarn add

3000

In the event that you want to interact with the server within the container or modify the Node project, you need to execute commands against the running container using

docker exec

docker run

Getting the running container ID is easy.

• If you already have a container shell open, the container ID is present in the shell prompt:

node@<CONTAINER ID>:/home/app$

• You can also get the container ID programmatically using

  docker ps

  to filter containers based on name and return the

  CONTAINER ID

  of any match:

docker ps -qf "name=node-docker"

The

-f

flag filters containers by the

name=node-docker

condition. The

-q

(

--quiet

) limits the output to only display the ID of the match, effectively plugging the

CONTAINER ID

of

node-docker

into the

docker exec

command.

Once you have the container ID, you can use

docker exec

• Open a new instance of the running container shell:

docker exec -it $(docker ps -qf "name=node-docker") /bin/bash

• Make a server request using the internal port

  3000

  :

docker exec -it $(docker ps -qf "name=node-docker") curl localhost:3000

• Install or remove dependencies:

docker exec -it $(docker ps -qf "name=node-docker") yarn add body-parser

One you have another active container shell, you can easily run

curl

and

yarn add

there instead.

Recap... and Uncovering Little Lies

You've learned how to create an isolated Node development environment through different levels of complexity: by running a single

docker run

Dockerfile

Each level requires more file configuration but a shorter command to run the container. This is a worthy trade-off as encapsulating configuration in files makes the environment portable and easier to maintain. Additionally, you learned how to interact with a running container to extend your project.

You may still need to install Node locally for IDEs to provide syntax assistance, or you can use a CLI editor like

vim

Even so, you can still benefit from this isolated development environment. If you restrict project setup, installation, and runtime steps to be executed within the container, you can standardize those steps for your team as everyone would be executing commands using the same version of Linux. Also, all the cache and hidden files created by Node tools stay within the container and don't pollute your local system. Oh, and you also get

yarn

JetBrains is starting to offer the capability to use Docker images as remote interpreters for Node and Python when running and debugging applications. In the future, we may become entirely free from downloading and installing these tools directly in our systems. Stay tuned to see what the industry provides us to make our developer environments standard and portable.