Repository files navigation

This tries to be a "good defaults" example of starting to use Node.js in Docker for local development and shipping to production with basic bells, whistles, and best practices. Issues/PR welcome.

Note I have more advanced examples of Node.js Dockerfiles and Compose files in myDockerCon 2019 talk and repository.I also have more about everything Docker and Node.js in my 8 hour video courseDocker for Node.js.

Also Note, I have other resources onDocker and Kubernetes here.

• Dev as close to prod as you can.docker-compose builds a local development image that is just like production image except for thebelow dev-only features needed in image.The goal is to have dev env be as close to test and prod as possible while still giving all thenice tools to make you a happy dev.
• Prevent needing node/npm on host.Installsnode_modules outside app root in container so local development won't run into aproblem of bind-mounting over it with local source code. This means it will runnpm 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 changepackage.json.
• One line startup. Usesdocker-compose up for single-line build and run of localdevelopment server.
• Edit locally while code runs in container.docker-compose uses proper bind-mounts of host source code into container so you can editlocally while running code in Linux container.
• Use nodemon in container. docker-compose uses nodemon for development for auto-restartingNode.js in container when you change files on host.
• Enable debug from host to container. opens the inspect port 9229 for using host-baseddebugging like chrome tools or VS Code. Nodemon enables--inspect by default in docker-compose.
• Provides VSCode debug configs and tasks for tests. for Visual Studio Code fans,.vscode directory has the goods, thanks to @JPLemelin.
• Small image and quick re-builds.COPY inpackage.json and runnpm installbeforeCOPY in your source code. This saves big on build time and keep container lean.
• Bind-mount package.json. This allows adding packages in realtime without rebuilding images. e.g.dce node npm install --save <package name> (dosn't work on all systems)

• Use Docker build-in healthchecks. uses DockerfileHEALTHCHECK with/healthz route tohelp Docker know if your container is running properly (example always returns 200, but you get the idea).
• Proper NODE_ENV use. Defaults toNODE_ENV=production in Dockerfile and overrides todevelopment in docker-compose for local dev.
• Don't add dev dependencies into production image. ProperNODE_ENV use means dev dependencieswon't be installed in container by default. Using docker-compose will build with them by default.
• Enables proper SIGTERM/SIGINT for graceful exit. Defaults tonode index.js rather then npmfor allowing graceful shutdown of node.npm doesn't pass SIGTERM/SIGINT properly (you can't ctrl-c when runningdocker run in foreground).To getnode index.js to graceful exit, extra signal-catching code is needed.TheDockerfile andindex.js document the options and links to known issues.
• Run Node.js in the container asnode user, notroot.
• Use docker-stack.yml example for Docker Swarm deployments.

• 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.js/npm on host)and have dev and prod Docker images be as close as possible.
• You don't want to lose fidelity in your dev workflow. You want a easy environment setup,using local editors, Node.js debug/inspect, local code repository, while Node.js server runs in a container.
• You usedocker-compose for local development only (docker-compose was never intended to bea production deployment tool anyway).
• Thedocker-compose.yml is not meant fordocker stack deploy in Docker Swarm,it's meant for happy local development. Usedocker-stack.yml for Swarm.

If this was your Node.js app, to start local development you would:

• Runningdocker-compose up is all you need. It will:
• Build custom local image enabled for development (nodemon,NODE_ENV=development).
• Start container from that image with ports 80 and 9229 open (on localhost).
• Starts withnodemon to restart Node.js 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 onup.
• Compose should detect if you need to rebuild due to changed package.json or Dockerfile,butdocker-compose build works for manually building.
• Be sure to usedocker-compose down to cleanup after your done dev'ing.

If you wanted to add a package while docker-compose was running your app:

• docker-compose exec -w /opt/node_app node npm install --save <package name>
• This installs it inside the running container.
• Nodemon will detect the change and restart.
• --save will add it to the package.json for nextdocker-compose build

To execute the unit-tests, you would:

• Executedocker-compose exec node npm test, It will:
• Run a processnpm test in the container node.
• You can use thevscode to debug unit-tests with configDocker Test (Attach 9230 --inspect),It will:
  • Start a debugging process in the container and wait-for-debugger, this is done byvscode tasks
  • It will also kill previous debugging process if existing.

As mentioned in the official docker Node.js image docs, Docker runs the image as root.This can pose apotential security issue.

As a security best practice, it is recommended for Node.js apps to listen on non-privileged portsas mentioned here.

• https://blog.hasura.io/an-exhaustive-guide-to-writing-dockerfiles-for-node-js-web-apps-bbee6bd2f3c4