Improving documentation around slim binaries

docs/content/installing.md

@@ -9,26 +9,24 @@ menu: main
 The simplest method for macOS is to use homebrew:
 
 ```console
-$ brew install hairyhenderson/tap/gomplate
+$ brew install gomplate
 ...
 ```
 
 ## Alpine Linux
 
-Currently, `gomplate` is available in the `community` repository for the `edge` release.
+`gomplate` is available in Alpine's `community` repository.
 
 ```console
-$ echo "http://dl-cdn.alpinelinux.org/alpine/edge/community/" >> /etc/apk/repositories
-$ apk update
-$ apk add gomplate
+$ apk add --no-cache gomplate
 ...
 ```
 
 _Note: the Alpine version of gomplate may lag behind the latest release of gomplate._
 
 ## use with Docker
 
-A simple way to get started is with the Docker image.
+A simple way to get started is with one of the [hairyhenderson/gomplate][] Docker images. Images containing [`slim` binaries](#slim-binaries) are tagged as `:slim` or `:vX.Y.Z-slim`.
 
 ```console
 $ docker run hairyhenderson/gomplate --version
@@ -52,9 +50,32 @@ $ gomplate --version
 gomplate version 1.2.3
 ```
 
+### use inside a container
+
+`gomplate` is often used inside Docker containers. When building images with Docker 17.05 or higher, you can use [multi-stage builds][] to easily include the `gomplate` binary in your container images.
+
+Use the `COPY` instruction's `--from` flag to accomplish this:
+
+```Dockerfile
+...
+COPY --from=hairyhenderson/gomplate:v2.5.0-slim /gomplate /bin/gomplate
+```
+
+Now, `gomplate` will be available in the `/bin` directory inside the container image.
+
+Note that when using `gomplate` with HTTPS-based datasources, you will likely need to install the `ca-certificates` package for your base distribution. Here's an example when using the [`alpine`](https://hub.docker.com/_alpine) base image:
+
+```Dockerfile
+FROM alpine
+
+COPY --from=hairyhenderson/gomplate:v2.5.0-slim /gomplate /bin/gomplate
+RUN apk add --no-cache ca-certificates
+```
+
 ## manual install
 
-1. Get the latest `gomplate` for your platform from the [releases](https://github.com/hairyhenderson/gomplate/releases) page
+1. Get the latest `gomplate` for your platform from the [releases][] page
+    - if available, you may want to download the [`-slim` variant](#slim-binaries)
 2. Store the downloaded binary somewhere in your path as `gomplate` (or `gomplate.exe`
   on Windows)
 3. Make sure it's executable (on Linux/macOS)
@@ -78,3 +99,19 @@ $ go get github.com/hairyhenderson/gomplate
 $ gomplate --help
 ...
 ```
+
+## Slim binaries
+
+As a convenience, self-extracting compressed `gomplate` binaries are available from the [releases][] page. These are named with `-slim` as a suffix (or `-slim.exe`). They are compressed with [UPX][].
+
+Generally, these binaries are ~5x smaller than the regular ones, but are otherwise exactly the same.
+
+There are a few reasons that a regular binary is also distributed:
+- UPX lacks support for some platforms
+- there's a very slight chance that the slim binary could exhibit some form of bug related to being compressed
+- there could be environments where self-extracting compressed executables are disallowed
+
+[releases]: https://github.com/hairyhenderson/gomplate/releases
+[UPX]: https://upx.github.io/
+[multi-stage builds]: https://docs.docker.com/develop/develop-images/multistage-build/
+[hairyhenderson/gomplate]: https://hub.docker.com/r/hairyhenderson/gomplate/tags/