diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ff4153391f..0315025145 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,26 +1,45 @@ # Contributing to docker-node -Thank you for your contribution. Here are a set of guidelines for contributing to the docker-node project. +Thank you for your contribution. Here are a set of guidelines for contributing +to the docker-node project. ## Version Updates New **Node.js** releases are released as soon as possible. -New **NPM** releases are not tracked. We simply use the NPM version bundled in the corresponding Node.js release. +New **NPM** releases are not tracked. We simply use the NPM version bundled in +the corresponding Node.js release. -**Yarn** is updated to the latest version only when there is a new Node.js SemVer PATCH release (unless Yarn has received a security update), and it's updated only in the branch with the new release, preferably in the same PR. The `update.sh` script does this automatically when invoked with a specific branch, e.g. `./update.sh 6.10`. +**Yarn** is updated to the latest version only when there is a new Node.js +SemVer PATCH release (unless Yarn has received a security update), and it's +updated only in the branch with the new release, preferably in the same PR. The +`update.sh` script does this automatically when invoked with a specific branch, +e.g. `./update.sh 6.10`. ### Submitting a PR for a version update -If you'd like to help us by submitting a PR for a version update, please do the following: - -1. [Fork this project.](https://help.github.com/en/github/getting-started-with-github/fork-a-repo) -1. [Clone the forked repository.](https://help.github.com/en/github/creating-cloning-and-archiving-repositories/cloning-a-repository) -1. Create a branch for the update PR. For example, `git checkout master; git checkout -b version-update`. -1. Run `./update.sh`. You can see additional options by using accessing the built-in help documentation with `./update.sh -h`. This script will automatically update the appropriate files with the latest versions and checksums. -1. Commit the modified files to the `version-update` branch and push the branch to your fork. -1. [Create a PR to merge the branch from your fork into this project's master branch.](https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/creating-a-pull-request-from-a-fork). +If you'd like to help us by submitting a PR for a version update, please do the +following: + +1. [Fork this + project.](https://help.github.com/en/github/getting-started-with-github/fork-a-repo) +1. [Clone the forked + repository.](https://help.github.com/en/github/creating-cloning-and-archiving-repositories/cloning-a-repository) +1. Create a branch for the update PR. For example, `git checkout master; git + checkout -b version-update`. +1. Run `./update.sh`. You can see additional options by using accessing the + built-in help documentation with `./update.sh -h`. This script will + automatically update the appropriate files with the latest versions and + checksums. +1. Commit the modified files to the `version-update` branch and push the branch + to your fork. +1. [Create a PR to merge the branch from your fork into this project's master + branch.](https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/creating-a-pull-request-from-a-fork). ## Adding dependencies to the base images -NodeJS is a big ecosystem with a variety of different use cases. The docker images for node are designed to provide the minimum for running core node. Additional dependencies (including dependencies for npm or yarn such as git) will not be included in these base images and will need to be included in descendent image. +NodeJS is a big ecosystem with a variety of different use cases. The docker +images for node are designed to provide the minimum for running core node. +Additional dependencies (including dependencies for npm or yarn such as git) +will not be included in these base images and will need to be included in +descendent image. diff --git a/GOVERNANCE.md b/GOVERNANCE.md index 77020bc50c..7bf9733b4b 100644 --- a/GOVERNANCE.md +++ b/GOVERNANCE.md @@ -111,8 +111,6 @@ If an agenda item cannot reach a consensus a WG member can call for a closing vote. The call for a vote must be seconded by a majority of the WG or else the discussion will continue. Simple majority wins. - - ## Developer's Certificate of Origin 1.1 By making a contribution to this project, I certify that: diff --git a/README.md b/README.md index 072637a460..20cc1f0de5 100644 --- a/README.md +++ b/README.md @@ -2,8 +2,10 @@ [![dockeri.co](http://dockeri.co/image/_/node)](https://registry.hub.docker.com/_/node/) -[![GitHub issues](https://img.shields.io/github/issues/nodejs/docker-node.svg "GitHub issues")](https://github.com/nodejs/docker-node) -[![GitHub stars](https://img.shields.io/github/stars/nodejs/docker-node.svg "GitHub stars")](https://github.com/nodejs/docker-node) +[![GitHub issues](https://img.shields.io/github/issues/nodejs/docker-node.svg +"GitHub issues")](https://github.com/nodejs/docker-node) [![GitHub +stars](https://img.shields.io/github/stars/nodejs/docker-node.svg "GitHub +stars")](https://github.com/nodejs/docker-node) The official Node.js docker image, made with love by the node community. @@ -11,7 +13,7 @@ The official Node.js docker image, made with love by the node community. ## Table of Contents -- [What is Node.js?](#what-is-nodejs) +- [What is Node.js](#what-is-nodejs) - [How to use this image](#how-to-use-this-image) - [Create a `Dockerfile` in your Node.js app project](#create-a-dockerfile-in-your-nodejs-app-project) - [Best Practices](#best-practices) @@ -31,18 +33,18 @@ The official Node.js docker image, made with love by the node community. - [Docker Working Group Members](#docker-working-group-members) - [Docker Working Group Collaborators](#docker-working-group-collaborators) - [Emeritus](#emeritus) - - [Docker Working Group Members](#docker-working-group-members-1) + - [Emeritus Docker Working Group Members](#emeritus-docker-working-group-members) -## What is Node.js? +## What is Node.js Node.js is a platform built on Chrome's JavaScript runtime for easily building fast, scalable network applications. Node.js uses an event-driven, non-blocking I/O model that makes it lightweight and efficient, perfect for data-intensive real-time applications that run across distributed devices. -See: http://nodejs.org +See: ## How to use this image @@ -58,8 +60,8 @@ EXPOSE 8888 You can then build and run the Docker image: ```console -$ docker build -t my-nodejs-app . -$ docker run -it --rm --name my-running-app my-nodejs-app +docker build -t my-nodejs-app . +docker run -it --rm --name my-running-app my-nodejs-app ``` If you prefer Docker Compose: @@ -83,16 +85,18 @@ services: You can then run using Docker Compose: ```console -$ docker-compose up -d +docker-compose up -d ``` -Docker Compose example copies your current directory (including node_modules) to the container. -It assumes that your application has a file named [`package.json`](https://docs.npmjs.com/files/package.json) -defining [start script](https://docs.npmjs.com/misc/scripts#default-values). +Docker Compose example copies your current directory (including node_modules) to +the container. It assumes that your application has a file named +[`package.json`](https://docs.npmjs.com/files/package.json) defining [start +script](https://docs.npmjs.com/misc/scripts#default-values). ### Best Practices -We have assembled a [Best Practices Guide](./docs/BestPractices.md) for those using these images on a daily basis. +We have assembled a [Best Practices Guide](./docs/BestPractices.md) for those +using these images on a daily basis. ### Run a single Node.js script @@ -101,16 +105,18 @@ complete `Dockerfile`. In such cases, you can run a Node.js script by using the Node.js Docker image directly: ```console -$ docker run -it --rm --name my-running-script -v "$PWD":/usr/src/app -w /usr/src/app node:8 node your-daemon-or-script.js +docker run -it --rm --name my-running-script -v "$PWD":/usr/src/app \ + -w /usr/src/app node:8 node your-daemon-or-script.js ``` ### Verbosity -Prior to 8.7.0 and 6.11.4 the docker images overrode the default npm log -level from `warn` to `info`. However due to improvements to npm and new Docker -patterns (e.g. multi-stage builds) the working group reached a [consensus](https://github.com/nodejs/docker-node/issues/528) -to revert the log level to npm defaults. If you need more verbose output, please -use one of the following methods to change the verbosity level. +Prior to 8.7.0 and 6.11.4 the docker images overrode the default npm log level +from `warn` to `info`. However due to improvements to npm and new Docker +patterns (e.g. multi-stage builds) the working group reached a +[consensus](https://github.com/nodejs/docker-node/issues/528) to revert the log +level to npm defaults. If you need more verbose output, please use one of the +following methods to change the verbosity level. #### Dockerfile @@ -129,7 +135,7 @@ If you run the node image using `docker run` you can use the `-e` flag to override `NPM_CONFIG_LOGLEVEL`. ```console -$ docker run -e NPM_CONFIG_LOGLEVEL=info node ... +docker run -e NPM_CONFIG_LOGLEVEL=info node ... ``` #### NPM run @@ -138,7 +144,7 @@ If you are running npm commands you can use `--loglevel` to control the verbosity of the output. ```console -$ docker run node npm --loglevel=warn ... +docker run node npm --loglevel=warn ... ``` ## Image Variants @@ -147,8 +153,8 @@ The `node` images come in many flavors, each designed for a specific use case. All of the images contain pre-installed versions of `node`, [`npm`](https://www.npmjs.com/), and [`yarn`](https://yarnpkg.com). For each supported architecture, the supported variants are different. In the file: -[architectures](./architectures), it lists all supported variants for all of -the architectures that we support now. +[architectures](./architectures), it lists all supported variants for all of the +architectures that we support now. ### `node:` @@ -164,31 +170,32 @@ need to install, thus reducing the overall size of all images on your system. ### `node:alpine` -This image is based on the popular -[Alpine Linux project](http://alpinelinux.org), available in -[the `alpine` official image](https://hub.docker.com/_/alpine). Alpine Linux is -much smaller than most distribution base images (~5MB), and thus leads to much -slimmer images in general. +This image is based on the popular [Alpine Linux +project](http://alpinelinux.org), available in [the `alpine` official +image](https://hub.docker.com/_/alpine). Alpine Linux is much smaller than most +distribution base images (~5MB), and thus leads to much slimmer images in +general. This variant is highly recommended when final image size being as small as -possible is desired. The main caveat to note is that it does use -[musl libc](http://www.musl-libc.org) instead of -[glibc and friends](http://www.etalabs.net/compare_libcs.html), so certain -software might run into issues depending on the depth of their libc -requirements. However, most software doesn't have an issue with this, so this -variant is usually a very safe choice. See -[this Hacker News comment thread](https://news.ycombinator.com/item?id=10782897) -for more discussion of the issues that might arise and some pro/con comparisons -of using Alpine-based images. One common issue that may arise is a missing shared -library required for use of `process.dlopen`. To add the missing shared libraries -to your image, adding the [`libc6-compat`](https://pkgs.alpinelinux.org/package/edge/main/x86/libc6-compat) +possible is desired. The main caveat to note is that it does use [musl +libc](http://www.musl-libc.org) instead of [glibc and +friends](http://www.etalabs.net/compare_libcs.html), so certain software might +run into issues depending on the depth of their libc requirements. However, most +software doesn't have an issue with this, so this variant is usually a very safe +choice. See [this Hacker News comment +thread](https://news.ycombinator.com/item?id=10782897) for more discussion of +the issues that might arise and some pro/con comparisons of using Alpine-based +images. One common issue that may arise is a missing shared library required for +use of `process.dlopen`. To add the missing shared libraries to your image, +adding the +[`libc6-compat`](https://pkgs.alpinelinux.org/package/edge/main/x86/libc6-compat) package in your Dockerfile is recommended: `apk add --no-cache libc6-compat` -To minimize image size, it's uncommon for additional related tools -(such as `git` or `bash`) to be included in Alpine-based images. Using this -image as a base, add the things you need in your own Dockerfile -(see the [`alpine` image description](https://hub.docker.com/_/alpine/) for -examples of how to install packages if you are unfamiliar). +To minimize image size, it's uncommon for additional related tools (such as +`git` or `bash`) to be included in Alpine-based images. Using this image as a +base, add the things you need in your own Dockerfile (see the [`alpine` image +description](https://hub.docker.com/_/alpine/) for examples of how to install +packages if you are unfamiliar). ### `node:slim` @@ -217,14 +224,15 @@ upgrade your Docker daemon. ## Supported Node.js versions -This project will support Node.js versions as still under active support as per the [Node.js release schedule](https://github.com/nodejs/Release). +This project will support Node.js versions as still under active support as per +the [Node.js release schedule](https://github.com/nodejs/Release). ## Governance and Current Members The Node.js Docker Image is governed by the Docker Working Group. See [GOVERNANCE.md](https://github.com/nodejs/docker-node/blob/master/GOVERNANCE.md) -to learn more about the group's structure and [CONTRIBUTING.md](CONTRIBUTING.md) for guidance -about the expectations for all contributors to this project. +to learn more about the group's structure and [CONTRIBUTING.md](CONTRIBUTING.md) +for guidance about the expectations for all contributors to this project. ### Docker Working Group Members @@ -242,6 +250,6 @@ about the expectations for all contributors to this project. ### Emeritus -#### Docker Working Group Members +#### Emeritus Docker Working Group Members - Christopher Horrell ([chorrell](https://github.com/chorrell)) diff --git a/SECURITY.md b/SECURITY.md index b6bd73dc9a..30d0182bc2 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -2,11 +2,16 @@ ## Reporting a Vulnerability -Security issues relating to Node.js project should follow the process documented on . +Security issues relating to Node.js project should follow the process documented +on . -CVEs for the base image packages should be reported to those repositories. Nothing to address those CVEs is in the hands of this repos. +CVEs for the base image packages should be reported to those repositories. +Nothing to address those CVEs is in the hands of this repos. - [Alpine](https://github.com/alpinelinux/docker-alpine) -- [Debian (buster, stretch)](https://github.com/debuerreotype/docker-debian-artifacts) +- [Debian (buster, + stretch)](https://github.com/debuerreotype/docker-debian-artifacts) -When base images are patched, the images are rebuilt and rolled out to the Docker hub without intervention by this repo. This process is explained in . +When base images are patched, the images are rebuilt and rolled out to the +Docker hub without intervention by this repo. This process is explained in +. diff --git a/docs/BestPractices.md b/docs/BestPractices.md index c883b2a0a4..25b965a6f0 100644 --- a/docs/BestPractices.md +++ b/docs/BestPractices.md @@ -1,3 +1,24 @@ + + +## Table of Contents + +- [Docker and Node.js Best Practices](#docker-and-nodejs-best-practices) + - [Table of Contents](#table-of-contents) + - [Environment Variables](#environment-variables) + - [Global npm dependencies](#global-npm-dependencies) + - [Upgrading/downgrading Yarn](#upgradingdowngrading-yarn) + - [Local](#local) + - [Global](#global) + - [Handling Kernel Signals](#handling-kernel-signals) + - [Non-root User](#non-root-user) + - [Memory](#memory) + - [CMD](#cmd) + - [Docker Run](#docker-run) + - [Security](#security) + - [node-gyp alpine](#node-gyp-alpine) + + + # Docker and Node.js Best Practices ## Table of Contents @@ -15,31 +36,38 @@ ## Environment Variables -Run with `NODE_ENV` set to `production`. This is the way you would pass in secrets and other runtime configurations to your application as well. +Run with `NODE_ENV` set to `production`. This is the way you would pass in +secrets and other runtime configurations to your application as well. -``` +```console -e "NODE_ENV=production" ``` ## Global npm dependencies -If you need to install global npm dependencies, it is recommended to place those dependencies in the [non-root user](#non-root-user) directory. To achieve this, add the following line to your `Dockerfile` +If you need to install global npm dependencies, it is recommended to place those +dependencies in the [non-root user](#non-root-user) directory. To achieve this, +add the following line to your `Dockerfile` ```Dockerfile ENV NPM_CONFIG_PREFIX=/home/node/.npm-global -ENV PATH=$PATH:/home/node/.npm-global/bin # optionally if you want to run npm global bin without specifying path +# optionally if you want to run npm global bin without specifying path +ENV PATH=$PATH:/home/node/.npm-global/bin ``` ## Upgrading/downgrading Yarn ### Local -If you need to upgrade/downgrade `yarn` for a local install, you can do so by issuing the following commands in your `Dockerfile`: - -> Note that if you create some other directory which is not a descendant one from where you ran the command, you will end up using the global (dated) version. If you wish to upgrade `yarn` globally follow the instructions in the next section. +If you need to upgrade/downgrade `yarn` for a local install, you can do so by +issuing the following commands in your `Dockerfile`: -> When following the local install instructions, due to duplicated yarn the image will end up being bigger. +> Note that if you create some other directory which is not a descendant one +> from where you ran the command, you will end up using the global (dated) +> version. If you wish to upgrade `yarn` globally follow the instructions in the +> next section. When following the local install instructions, due to duplicated +> yarn the image will end up being bigger. ```Dockerfile FROM node:6 @@ -56,14 +84,16 @@ FROM node:6 ENV YARN_VERSION 1.16.0 -RUN curl -fSLO --compressed "https://yarnpkg.com/downloads/$YARN_VERSION/yarn-v$YARN_VERSION.tar.gz" \ +RUN curl -fSLO --compressed \ + "https://yarnpkg.com/downloads/$YARN_VERSION/yarn-v$YARN_VERSION.tar.gz" \ && tar -xzf yarn-v$YARN_VERSION.tar.gz -C /opt/ \ && ln -snf /opt/yarn-v$YARN_VERSION/bin/yarn /usr/local/bin/yarn \ && ln -snf /opt/yarn-v$YARN_VERSION/bin/yarnpkg /usr/local/bin/yarnpkg \ && rm yarn-v$YARN_VERSION.tar.gz ``` -If you're using an Alpine-based image, `curl` won't be present, so you'll need to make sure it's installed while using it: +If you're using an Alpine-based image, `curl` won't be present, so you'll need +to make sure it's installed while using it: ```Dockerfile FROM node:6-alpine @@ -71,7 +101,8 @@ FROM node:6-alpine ENV YARN_VERSION 1.5.1 RUN apk add --no-cache --virtual .build-deps-yarn curl \ - && curl -fSLO --compressed "https://yarnpkg.com/downloads/$YARN_VERSION/yarn-v$YARN_VERSION.tar.gz" \ + && curl -fSLO --compressed \ + "https://yarnpkg.com/downloads/$YARN_VERSION/yarn-v$YARN_VERSION.tar.gz" \ && tar -xzf yarn-v$YARN_VERSION.tar.gz -C /opt/ \ && ln -snf /opt/yarn-v$YARN_VERSION/bin/yarn /usr/local/bin/yarn \ && ln -snf /opt/yarn-v$YARN_VERSION/bin/yarnpkg /usr/local/bin/yarnpkg \ @@ -81,19 +112,29 @@ RUN apk add --no-cache --virtual .build-deps-yarn curl \ ## Handling Kernel Signals -Node.js was not designed to run as PID 1 which leads to unexpected behaviour when running inside of Docker. For example, a Node.js process running as PID 1 will not respond to `SIGINT` (`CTRL-C`) and similar signals. As of Docker 1.13, you can use the `--init` flag to wrap your Node.js process with a [lightweight init system](https://github.com/krallin/tini) that properly handles running as PID 1. +Node.js was not designed to run as PID 1 which leads to unexpected behaviour +when running inside of Docker. For example, a Node.js process running as PID 1 +will not respond to `SIGINT` (`CTRL-C`) and similar signals. As of Docker 1.13, +you can use the `--init` flag to wrap your Node.js process with a [lightweight +init system](https://github.com/krallin/tini) that properly handles running as +PID 1. -``` +```console docker run -it --init node ``` -You can also include Tini [directly in your Dockerfile](https://github.com/krallin/tini#using-tini), ensuring your process is always started with an init wrapper. +You can also include Tini [directly in your +Dockerfile](https://github.com/krallin/tini#using-tini), ensuring your process +is always started with an init wrapper. ## Non-root User -By default, Docker runs container as root which inside of the container can pose as a security issue. You would want to run the container as an unprivileged user wherever possible. The node images provide the `node` user for such purpose. The Docker Image can then be run with the `node` user in the following way: +By default, Docker runs container as root which inside of the container can pose +as a security issue. You would want to run the container as an unprivileged user +wherever possible. The node images provide the `node` user for such purpose. The +Docker Image can then be run with the `node` user in the following way: -``` +```console -u "node" ``` @@ -106,9 +147,12 @@ FROM node:6.10.3 USER node ``` -Note that the `node` user is neither a build-time nor a run-time dependency and it can be removed or altered, as long as the functionality of the application you want to add to the container does not depend on it. +Note that the `node` user is neither a build-time nor a run-time dependency and +it can be removed or altered, as long as the functionality of the application +you want to add to the container does not depend on it. -If you do not want nor need the user created in this image you can remove it with the following: +If you do not want nor need the user created in this image you can remove it +with the following: ```Dockerfile # For debian based images use: @@ -130,7 +174,8 @@ If you need another name for the user (ex. `myapp`) execute: RUN usermod -d /home/myapp -l myapp node ``` -For alpine based images, you do not have `groupmod` nor `usermod`, so to change the uid/gid you have to delete the previous user: +For alpine based images, you do not have `groupmod` nor `usermod`, so to change +the uid/gid you have to delete the previous user: ```Dockerfile RUN deluser --remove-home node \ @@ -140,15 +185,21 @@ RUN deluser --remove-home node \ ## Memory -By default, any Docker Container may consume as much of the hardware such as CPU and RAM. If you are running multiple containers on the same host you should limit how much memory they can consume. +By default, any Docker Container may consume as much of the hardware such as CPU +and RAM. If you are running multiple containers on the same host you should +limit how much memory they can consume. -``` +```console -m "300M" --memory-swap "1G" ``` ## CMD -When creating an image, you can bypass the `package.json`'s `start` command and bake it directly into the image itself. First off this reduces the number of processes running inside of your container. Secondly it causes exit signals such as `SIGTERM` and `SIGINT` to be received by the Node.js process instead of npm swallowing them. +When creating an image, you can bypass the `package.json`'s `start` command and +bake it directly into the image itself. First off this reduces the number of +processes running inside of your container. Secondly it causes exit signals such +as `SIGTERM` and `SIGINT` to be received by the Node.js process instead of npm +swallowing them. ```Dockerfile CMD ["node","index.js"] @@ -156,10 +207,11 @@ CMD ["node","index.js"] ## Docker Run -Here is an example of how you would run a default Node.JS Docker Containerized application: +Here is an example of how you would run a default Node.JS Docker Containerized +application: -``` -$ docker run \ +```console +docker run \ -e "NODE_ENV=production" \ -u "node" \ -m "300M" --memory-swap "1G" \ @@ -170,11 +222,14 @@ $ docker run \ ## Security -The Docker team has provided a tool to analyze your running containers for potential security issues. You can download and run this tool from here: https://github.com/docker/docker-bench-security +The Docker team has provided a tool to analyze your running containers for +potential security issues. You can download and run this tool from here: + ## node-gyp alpine -Here is an example of how you would install dependencies for packages that require node-gyp support on the alpine variant: +Here is an example of how you would install dependencies for packages that +require node-gyp support on the alpine variant: ```Dockerfile FROM node:alpine