cleanup, adding license and readme

Dockerfile

@@ -1,30 +1,33 @@
+# if you're doing anything beyond your local machine, please pin this to a specific version at https://hub.docker.com/_/node/
 FROM node:6
 
 RUN mkdir -p /usr/src/app
 
 # set our node environment, either development or production
-# defaults to production
+# defaults to production, compose overrides this to development on build and run
 ARG NODE_ENV=production
 ENV NODE_ENV $NODE_ENV
 
-# default to port 80, and 5858 or 9229 for debug
+# default to port 80 for node, and 5858 or 9229 for debug
 ARG PORT=80
 ENV PORT $PORT
 EXPOSE $PORT 5858 9229
 
 # check every 30s to ensure this service returns HTTP 200
 HEALTHCHECK CMD curl -fs http://localhost:$PORT/healthz || exit 1
 
-# install dependencies first, in a different location for easier app bind mount
+# install dependencies first, in a different location for easier app bind mounting for local development
 WORKDIR /usr/src
 COPY package.json /usr/src/
 RUN npm install && npm cache clean
 ENV PATH /data/node_modules/.bin:$PATH
 
-# copy in our source code last
+# copy in our source code last, as it changes the most
 WORKDIR /usr/src/app
 COPY . /usr/src/app
 
-# if you want to use npm start instead, then use --init with docker run
-# so that signals are passed properly
+# if you want to use npm start instead, then use `docker run --init in production`
+# so that signals are passed properly. Note the code in index.js is needed to catch Docker signals
+# using node here is still more graceful stopping then npm with --init afaik
+# I still can't come up with a good production way to run with npm and graceful shutdown
 CMD [ "node", "index.js" ]

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+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
+SOFTWARE.

README.md

@@ -0,0 +1,68 @@
+## 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 with all the bells, whistles, and best practices. Issues/PR welcome.
+
+### Features
+
+- Local Dev: docker-compose builds a local dev image that is just like production image execpt 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.
+- Local Dev: 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 `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`.
+- Local Dev: Uses `docker-compose up` for single-line build and run of local development server.
+- Local Dev: docker-compose uses proper bind-mounts of host source code into container so you can edit locally while running code in Linux container.
+- Local Dev: docker-compose uses nodemon for development for auto-restarting node in container when you change files on host.
+- Local Dev: opens the legacy debug port 5858 and new inspect port 9229 for using host-based debugging like chrome tools or VS Code.
+- Local Dev: Nodemon enables `--debug` by default in docker-compose, but you can change to `--inspect` for new 6.3+ debugging.
+- Local Dev: for Visual Studio Code fans, `.vscode` has a config for both `--debug` and `--inspect` node options.
+
+- Building: `COPY` in `package.json` and run `npm install && npm cache clean` *before* `COPY` in your source code. This saves big on build time and keep container lean.
+
+- Production: 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).
+- Production: Defaults to `NODE_ENV=production` in Dockerfile and overrides to `development` in docker-compose for local dev.
+- Production: Proper `NODE_ENV` use means dev dependencies won't be installed in container by default. Using docker-compose will build with them by default.
+- Production: Defaults to `node index.js` rather then npm for allowing graceful shutdown of node. npm doesn't pass SIGTERM/SIGINIT 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.
+
+
+### 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 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-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 1.13, it's meant for happy local development.
+
+
+### 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, 5858, 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.
+
+
+
+MIT License, 
+
+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
+SOFTWARE.

index.js

@@ -3,14 +3,20 @@
 
 var express = require('express');
 // this example uses express web framework so we know what longer build times
-// do and how Dockerfile layer ordering matters
+// do and how Dockerfile layer ordering matters. If you mess up Dockerfile ordering
+// you'll see long build times on every code change + build. If done correctly,
+// code changes should be only a few seconds to build locally due to build cache.
 
 var morgan = require('morgan');
+// morgan provides easy logging for express, and by default it logs to stdout
+// which is a best practice in Docker. Friends don't let friends code their apps to
+// do app logging to files in containers.
 
 // Constants
 const PORT = process.env.PORT || 8080;
-// so either set PORT envvar when running node natively (local dev)
-// or rely on default which should match Dockerfile EXPOSE
+// if you're not using docker-compose for local development, this will default to 8080
+// to prevent non-root permission problems with 80. Dockerfile is set to make this 80
+// because containers don't have that issue :)
 
 // Appi
 var app = express();
@@ -24,6 +30,7 @@ app.get('/', function (req, res) {
 app.get('/healthz', function (req, res) {
 	// do app logic here to determine if app is truly healthy
 	// you should return 200 if healthy, and anything else will fail
+	// if you want, you should be able to restrict this to localhost (include ipv4 and ipv6)
   res.send('I am happy and healthy\n');
 });
 
@@ -34,10 +41,13 @@ var server = app.listen(PORT, function () {
 
 //
 // need this in docker container to properly exit since node doesn't handle SIGINT/SIGTERM
-// this also won't work on using npm start since
+// this also won't work on using npm start since:
 // https://github.com/npm/npm/issues/4603
 // https://github.com/npm/npm/pull/10868
 // https://github.com/RisingStack/kubernetes-graceful-shutdown-example/blob/master/src/index.js
+// if you want to use npm then start with `docker run --init` to help, but I still don't think it's
+// a graceful shutdown of node process
+//
 
 // quit on ctrl-c when running docker in terminal
 process.on('SIGINT', function onSigint () {

package.json

@@ -1,13 +1,14 @@
 {
-  "name": "docker-node-hello",
+  "name": "node-docker-good-defaults",
   "private": true,
-  "version": "0.0.1",
-  "description": "Node.js Hello world app using docker",
+  "version": "1.0.0",
+  "description": "Node.js Hello world app using docker features for easy docker-compose local dev and solid production defaults",
   "author": "Bret Fisher <[email protected]>",
   "main": "index.js",
   "scripts": {
     "start": "node index.js",
-    "dev": "./node_modules/nodemon/bin/nodemon.js"
+    "dev-docker": "../node_modules/nodemon/bin/nodemon.js --debug=5858",
+    "dev-host": "nodemon --debug=5858"
   },
   "dependencies": {
     "express": "^4.14.1",