docs: dockerfile considerations

An application with a dependency on a node
module that requires and invokes build tools
during a 'docker build' may experience a
compilation error if the Dockerfile image
lacks certain libraries/tools.

It is important to choose the appropriate
Docker image for your application.

docs/site/Application-generator.md

@@ -34,7 +34,8 @@ application project.
 `--vscode`: Add VSCode config files to LoopBack4 application project
 
 `--docker`: Generate Dockerfile and add npm scripts to build/run the project in
-a docker container.
+a docker container. See also
+[Dockerfile considerations](#dockerfile-considerations) below.
 
 {% include_relative includes/CLI-std-options.md %}
 
@@ -103,3 +104,59 @@ greeted with a message.
 Once the application has been created, additional generators such as
 [controller generator](Controller-generator.md) can be run from the
 application's root directory to further scaffold the application.
+
+### Dockerfile Considerations
+
+The Dockerfile that is generated by the `--docker` option is based on a `slim`
+version of a `node` Docker image.
+
+Here are the first two lines of the
+[Dockerfile](https://github.com/strongloop/loopback-next/blob/master/packages/cli/generators/app/templates/Dockerfile):
+
+```
+# Check out https://hub.docker.com/_/node to select a new base image
+FROM node:10-slim
+```
+
+As the comment suggests, the Docker image name is only a default, and you are
+encouraged to select an appropriate base image for your application.
+
+If your application has a dependency on a node module that requires and invokes
+build tools during `docker build` (for example :
+[loopback-connector-db2](https://github.com/strongloop/loopback-connector-db2)
+), an error may occur due to missing libraries.
+
+Using the Docker image `node:10`, however, will allow the `docker build` step to
+complete successfully.
+
+If you intend to use a `node:alpine` Docker image, please see
+[node-gyp-alpine](https://github.com/nodejs/docker-node/blob/master/docs/BestPractices.md#node-gyp-alpine)
+for an example of how you would install dependencies for packages that require
+node-gyp support.
+
+Example compilation error when build tools/libraries are not in place:
+
+```
+...
+Downloading and extraction of DB2 ODBC CLI Driver completed successfully ...
+
+{ Error: Command failed: node-gyp configure build  --IS_DOWNLOADED=true --IBM_DB_HOME="$IBM_DB_HOME"
+gyp ERR! configure error
+gyp ERR! stack Error: Can't find Python executable "python", you can set the PYTHON env variable.
+gyp ERR! stack     at PythonFinder.failNoPython (/usr/local/lib/node_modules/npm/node_modules/node-gyp/lib/configure.js:484:19)
+gyp ERR! stack     at PythonFinder.<anonymous> (/usr/local/lib/node_modules/npm/node_modules/node-gyp/lib/configure.js:406:16)
+gyp ERR! stack     at F (/usr/local/lib/node_modules/npm/node_modules/which/which.js:68:16)
+gyp ERR! stack     at E (/usr/local/lib/node_modules/npm/node_modules/which/which.js:80:29)
+gyp ERR! stack     at /usr/local/lib/node_modules/npm/node_modules/which/which.js:89:16
+gyp ERR! stack     at /usr/local/lib/node_modules/npm/node_modules/isexe/index.js:42:5
+gyp ERR! stack     at /usr/local/lib/node_modules/npm/node_modules/isexe/mode.js:8:5
+gyp ERR! stack     at FSReqWrap.oncomplete (fs.js:152:21)
+gyp ERR! System Linux 4.9.184-linuxkit
+gyp ERR! command "/usr/local/bin/node" "/usr/local/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js" "configure" "build" "--IS_DOWNLOADED=true" "--IBM_DB_HOME=/home/node/app/node_modules/ibm_db/installer/clidriver"
+gyp ERR! cwd /home/node/app/node_modules/ibm_db
+gyp ERR! node -v v8.16.1
+gyp ERR! node-gyp -v v3.8.0
+gyp ERR! not ok
+
+    at ChildProcess.exithandler (child_process.js:281:12)
+```