Node.js Docker "Good Defaults": A Best Practice Template for Node In A Container

TL;DR: Get the Project Skeleton on GitHub and improve your Node+Docker skills

I've been a Node fan since 2012, when Kevin Griffin and I shifted our bootstrap startup to it from asp.net. I'm no expert (like the ETA shop is) but I've used it and Docker long enough to learn the happy path for Developers + Operations.

So I made you this with ❤️

This project turns on all the Buttery Goodness of Docker and Docker Compose so your Node app will develop and run best in a Container, both for development, and for production.

I've created documentation and a project skeleton on GitHub, and welcome feedback in the issues.

Here's what you get for the low low price of software libre:

Assumptions

• You have Docker and Docker-Compose installed (Docker for Mac, Docker for Windows, get.docker.com and manual Compose installed for Linux).
• You want to use Docker for local development (i.e. never need to install node/npm on host) and have dev and prod Docker images be as close as possible.
• You don't want to loose fidelity in your dev workflow. You want a easy environment setup, using local editors, node debug/inspect, local code repo, while node server runs in a container.
• You use docker-compose for local development only (docker-compose was never intended to be a production deployment tool anyway).
• The docker-compose.yml is not meant for docker stack deploy in Docker 1.13, it's meant for happy local development.

Local Development Features

• Dev as close to prod as you can. docker-compose builds a local development image that is similar to the production image except for the below dev-only features. The goal is to have your development environment be as close to test and prod images/containers as possible while still giving you all the nice tools to make you a happy dev.
• Prevent needing node/npm on host. Installs node_modules outside the app root in the container so local development won't run into a problem of bind-mounting over it with local source code. This means it will npm install once on container build and you don't need to run npm on host or on each docker run. It will re-run on build if you change package.json.
• One line startup. Uses docker-compose up for single-line building and running of a local development server.
• Edit locally while code runs in container. docker-compose uses proper bind-mounts of host source code into container so you can edit locally while running the code in a Linux container.
• Use nodemon in container. docker-compose uses nodemon for development for auto-restarting node in the container when you change files on host.
• Enable debug from host to container. Opens the legacy debug port 5858 and new inspect port 9229 for using host-based debugging like Chrome DevTools or VS Code. Nodemon enables --debug by default in docker-compose, but you can change to --inspect for new 6.3+ debugging.
• Provides VSCode debug config. for Visual Studio Code fans, .vscode has a config for both --debug and --inspect node options.
• Small image and quick re-builds. COPY in package.json and run npm install && npm cache clean before COPY in your source code. This saves big on build time and keep container lean.

Production-minded Features

• Use Docker build-in healthchecks. uses Dockerfile HEALTHCHECK with /healthz route to help Docker know if your container is running properly (example always returns 200, but you get the idea).
• Proper NODE_ENV use. Defaults to NODE_ENV=production in Dockerfile and overrides to development in docker-compose for local dev.
• Don't add dev dependencies into production image. Proper NODE_ENV use means dev dependencies won't be installed in container by default. Using docker-compose will build with them by default.
• Enables proper SIGTERM/SIGINT for graceful exit. Defaults to node index.js rather then npm for allowing graceful shutdown of node. npm doesn't pass SIGTERM/SIGINT properly (you can't ctrl-c when running docker run in foreground). To get node index.js to graceful exit, extra signal-catching code is needed. The Dockerfile and index.js document the options and links to known issues.

Get the Project Skeleton on GitHub and improve your Node+Docker skills.