Skip to content

Commit

Permalink
general updates
Browse files Browse the repository at this point in the history
  • Loading branch information
@BretFisher
BretFisher committed Jan 17, 2022
1 parent 034b816 commit 43acc6e
Show file tree
Hide file tree
Showing 4 changed files with 102 additions and 86 deletions.
5 changes: 4 additions & 1 deletion .github/workflows/linter.yml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,4 +11,7 @@ jobs:
call-super-linter:
# use Reusable Workflows to call my linter config remotely
# https://docs.github.com/en/actions/learn-github-actions/reusing-workflows
uses: bretfisher/super-linter-workflow/.github/workflows/super-linter.yaml@main
uses: bretfisher/super-linter-workflow/.github/workflows/super-linter.yaml@main
with:
devops-only: true
#filter-regex-exclude: .*compose-sample-3/html/.*
4 changes: 2 additions & 2 deletions Dockerfile
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# if you're doing anything beyond your local machine, please pin this to a specific version at https://hub.docker.com/_/node/
# FROM node:12-alpine also works here for a smaller image
FROM node:12-slim
# FROM node:14-alpine also works here for a smaller image
FROM node:14-slim

# set our node environment, either development or production
# defaults to production, compose overrides this to development on build and run
Expand Down
175 changes: 94 additions & 81 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,101 +1,114 @@
## Node + Docker Hello World, for Showing Good Defaults for Using Node.js in Docker
# Node + Docker for Showing Good Defaults in Using Node.js with Docker

[![Lint Code Base](https://github.com/BretFisher/node-docker-good-defaults/actions/workflows/linter.yml/badge.svg)](https://github.com/BretFisher/node-docker-good-defaults/actions/workflows/linter.yml)
[![Build and Push Image](https://github.com/BretFisher/node-docker-good-defaults/actions/workflows/docker-build-and-push.yml/badge.svg)](https://github.com/BretFisher/node-docker-good-defaults/actions/workflows/docker-build-and-push.yml)

> 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 my [DockerCon 2019 talk and repo](https://github.com/BretFisher/dockercon19). I also have more about everything Docker and Node.js in my 8 hour video course [Docker for Node.js](https://www.bretfisher.com/node/).
**Note** I have more advanced examples of Node.js Dockerfiles and Compose files in my [DockerCon 2019 talk and repo](https://github.com/BretFisher/dockercon19).
I also have more about everything Docker and Node.js in my 8 hour video course [Docker for Node.js](https://www.bretfisher.com/node/).

**Also Note**, I have other resources on [Docker and Kubernetes here](https://www.bretfisher.com/docker).

### 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_modules` outside 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 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 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 inspect port 9229 for using host-based debugging 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` in `package.json` and run `npm install` **before** `COPY` 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)


### 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.
- **Run node in the container as `node` user, not `root`**.
- **Use docker-stack.yml example for Docker Swarm deployments**.


### 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 lose 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 Swarm, it's meant for happy local development. Use `docker-stack.yml` for Swarm.


### Getting Started
## 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.
The 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_modules` outside 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 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 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 inspect port 9229 for using host-based
debugging 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` in `package.json` and run `npm install`
**before** `COPY` 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)

## 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.
- **Run node in the container as `node` user, not `root`**.
- **Use docker-stack.yml example for Docker Swarm deployments**.

## 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 lose 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 Swarm,
it's meant for happy local development. Use `docker-stack.yml` for Swarm.

## Getting Started

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

- Running `docker-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 with `nodemon` to 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 `up`.
- Compose should detect if you need to rebuild due to changed package.json or Dockerfile, but `docker-compose build` works for manually building.
- Be sure to use `docker-compose down` to cleanup after your done dev'ing.
- Running `docker-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 with `nodemon` to 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 `up`.
- Compose should detect if you need to rebuild due to changed package.json or Dockerfile,
but `docker-compose build` works for manually building.
- Be sure to use `docker-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 next `docker-compose build`

To execute the unit-tests, you would:
- Execute `docker-compose exec node npm test`, It will:
- Run a process `npm test` in the container node.
- You can use the *vscode* to debug unit-tests with config `Docker Test (Attach 9230 --inspect)`, It will:
- Start a debugging process in the container and wait-for-debugger, this is done by *vscode tasks*
- It will also kill previous debugging process if existing.

### Ways to improve security
- `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 next `docker-compose build`

#### Run Node.js as Non-Root User

As mentioned in the official docker node image docs, Docker runs the image as root. This can pose a potential security issue.
- https://github.com/nodejs/docker-node/blob/master/docs/BestPractices.md#non-root-user

As a security best practice, it is recommended for node apps to listen on non-privileged ports as mentioned here:
- https://github.com/i0natan/nodebestpractices/blob/master/sections/security/non-root-user.md
To execute the unit-tests, you would:

### Other Resources
- Execute `docker-compose exec node npm test`, It will:
- Run a process `npm test` in the container node.
- You can use the *vscode* to debug unit-tests with config `Docker Test (Attach 9230 --inspect)`,
It will:
- Start a debugging process in the container and wait-for-debugger, this is done by *vscode tasks*
- It will also kill previous debugging process if existing.

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

MIT License,
### Run Node.js as Non-Root User

Copyright (c) 2015-2019 Bret Fisher
As mentioned in the official docker node image docs, Docker runs the image as root.
This can pose a
[potential security issue](https://github.com/nodejs/docker-node/blob/master/docs/BestPractices.md#non-root-user).

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:
As a security best practice, it is recommended for node apps to listen on non-privileged ports
[as mentioned here](https://github.com/i0natan/nodebestpractices/blob/master/sections/security/non-root-user.md).

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
## Other Resources

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
SOFTWARE.
- [https://blog.hasura.io/an-exhaustive-guide-to-writing-dockerfiles-for-node-js-web-apps-bbee6bd2f3c4](https://blog.hasura.io/an-exhaustive-guide-to-writing-dockerfiles-for-node-js-web-apps-bbee6bd2f3c4)
4 changes: 2 additions & 2 deletions healthcheck.js
View file
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
var http = require("http");
var http = require('http');

var options = {
timeout: 2000,
Expand All @@ -13,7 +13,7 @@ var request = http.request(options, (res) => {
process.exit();
});

request.on('error', function(err) {
request.on('error', function (err) {
console.error('ERROR', err);
process.exit(1);
});
Expand Down

0 comments on commit 43acc6e

Please sign in to comment.