Node + Docker Hello World, for Showing Good Defaults for Using Node.js in Docker
This tries to be a "good defaults" example of using Node.js in Docker for local development and shipping to production with all the bells, whistles, and best practices. Issues/PR welcome.
Local Development Features
- Dev as close to prod as you can. docker-compose builds a local development image that is just like production image except for the below dev-only features needed in image. Goal is to have dev env be as close to test and prod as possible while still giving all the nice tools to make you a happy dev.
- Prevent needing node/npm on host. Installs
node_modulesoutside app root in container so local development won't run into a problem of bind-mounting over it with local source code. This means it will run
npm installonce 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
- One line startup. Uses
docker-compose upfor single-line build and run of 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 code in Linux container.
- Use nodemon in container. docker-compose uses nodemon for development for auto-restarting node in 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 tools or VS Code. Nodemon enables
--inspectby default in docker-compose, but you can change to
--debugfor < 6.3 debugging.
- Provides VSCode debug config. for Visual Studio Code fans,
.vscodehas a config for both
- Small image and quick re-builds.
npm install && npm cache cleanbefore
COPYin your source code. This saves big on build time and keep container lean.
- Use Docker build-in healthchecks. uses Dockerfile
/healthzroute 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=productionin Dockerfile and overrides to
developmentin docker-compose for local dev.
- Don't add dev dependencies into production image. Proper
NODE_ENVuse 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.jsrather then npm for allowing graceful shutdown of node. npm doesn't pass SIGTERM/SIGINT properly (you can't ctrl-c when running
docker runin foreground). To get
node index.jsto graceful exit, extra signal-catching code is needed. The
index.jsdocument the options and links to known issues.
- 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-composefor local development only (docker-compose was never intended to be a production deployment tool anyway).
docker-compose.ymlis not meant for
docker stack deployin Docker 1.13, it's meant for happy local development.
If this was your Node.js app, to start local development you would:
docker-compose upis all you need. It will:
- Build custom local image enabled for development (nodemon,
- Start container from that image with ports 80, 5858, and 9229 open (on localhost).
- Starts with
nodemonto restart node on file change in host pwd.
- Mounts the pwd to the app dir in container.
- If you need other services like databases, just add to compose file and they'll be added to the custom Docker network for this app on
- Compose should detect if you need to rebuild due to changed package.json or Dockerfile, but
docker-compose buildworks for manually building.
- Be sure to use
docker-compose downto cleanup after your done dev'ing.
Copyright (c) 2015-2017 Bret Fisher
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE