Explain the npm verbosity in the node image

README.md

@@ -53,6 +53,51 @@ $ docker run -it --rm --name my-running-script -v "$PWD":/usr/src/app -w
 /usr/src/app node:4 node your-daemon-or-script.js
 ```
 
+## Verbosity
+
+By default the Node.js Docker Image has npm log verbosity set to `info` instead
+of the default `warn`. This is because of the way Docker is isolated from the
+host operating system and you are not guaranteed to be able to retrieve the
+`npm-debug.log` file when npm fails.
+
+When npm fails, it writes it's verbose log to a log file inside the container.
+If npm fails during an install when building a Docker Image with the `docker
+build` command, this log file will become inaccessible when Docker exits.
+
+The Docker Working Group have chosen to be overly verbose during a build to
+provide an easy audit trail when install fails. If you prefer npm to be less
+verbose you can easily reset the verbosity of npm using the following
+techniques:
+
+### Dockerfile
+
+If you create your own `Dockerfile` which inherits from the `node` image you can
+simply use `ENV` to override `NPM_CONFIG_LOGLEVEL`.
+
+```
+FROM node
+ENV NPM_CONFIG_LOGLEVEL warn
+...
+```
+
+### Docker Run
+
+If you run the node image using `docker run˙ you can use the `-e` flag to
+override `NPM_CONFIG_LOGLEVEL`.
+
+```
+$ docker run -e NPM_CONFIG_LOGLEVEL=warn node ...
+```
+
+### NPM run
+
+If you are running npm commands you can use `--loglevel` to control the
+verbosity of the output.
+
+```
+$ docker run node npm --loglevel=warn ...
+```
+
 # Image Variants
 
 The `node` images come in many flavors, each designed for a specific use case.