Merge pull request #853 from carolynvs/doc-base-image

Doc that custom dockerfiles must have apt

docs/content/custom-dockerfile.md

@@ -13,12 +13,12 @@ When you run `porter create` template Dockerfile is created for you
 in the current directory named **Dockerfile.tmpl**:
 
 ```Dockerfile
-FROM quay.io/deis/lightweight-docker-go:v0.2.0
 FROM debian:stretch
-COPY --from=0 /etc/ssl/certs/ca-certificates.crt /etc/ssl/certs/ca-certificates.crt
 
 ARG BUNDLE_DIR
 
+RUN apt-get update && apt-get install -y ca-certificates
+
 # This is a template Dockerfile for the bundle's invocation image
 # You can customize it to use different base images, install tools and copy configuration files.
 #
@@ -33,7 +33,8 @@ ARG BUNDLE_DIR
 # PORTER_MIXINS
 
 # Use the BUNDLE_DIR build argument to copy files into the bundle
-# COPY . $BUNDLE_DIR
+COPY . $BUNDLE_DIR
+
 ```
 
 Add the following line to your **porter.yaml** file to instruct porter to use
@@ -44,9 +45,13 @@ dockerfile: Dockerfile.tmpl
 ```
 
 It is your responsibility to provide a suitable base image, for example one that
-has root ssl certificates installed. When using a Dockerfile template, you must
-manually copy any files you need in your bundle using COPY statements. A few
-conventions are followed by Porter to help with this task:
+has root ssl certificates installed. *You must use a base image that is
+debian-based, such as `debian` or `ubuntu` with apt installed.* Mixins assume
+that apt is available to install packages.
+
+When using a Dockerfile template, you must manually copy any files you need in
+your bundle using COPY statements. A few conventions are followed by Porter to
+help with this task:
 
 ## BUNDLE_DIR
 

docs/content/troubleshooting.md

@@ -6,6 +6,7 @@ description: Error messages you may see from Porter and how to handle them
 With any porter error, it can really help to re-run the command again with the `--debug` flag.
 
 * [mapping values are not allowed in this context](#mapping-values-are-not-allowed-in-this-context)
+* [you see apt errors when you use a custom Dockerfile](#)
 
 ## mapping values are not allowed in this context
 
@@ -78,4 +79,17 @@ install:
       command: bash
       flags:
         c: "echo {{ bundle.parameters.test}}"
-```
+```
+
+## you see apt errors when you use a custom Dockerfile
+
+When you use a custom Dockerfile you see `apt` errors even though you did not use apt in your Dockerfile. This is because
+Porter assumes a debian-based base image that has apt available. Many of the mixins use apt to install the dependencies
+and the binary that they shim.
+
+```
+Starting Invocation Image Build =======>
+Error: unable to build CNAB invocation image: failed to stream docker build output: The command '/bin/sh -c apt-get update && apt-get install -y apt-transport-https curl && curl -o kubectl https://storage.googleapis.com/kubernetes-release/release/v1.15.5/bin/linux/amd64/kubectl && mv kubectl /usr/local/bin && chmod a+x /usr/local/bin/kubectl' returned a non-zero code: 127
+```
+
+For now you must base your custom Dockerfile on debian or ubuntu.