Merge pull request #1017 from alcohol/master

amend Composer documentation

composer/content.md

@@ -36,6 +36,8 @@ docker run --rm --interactive --tty \
 
 When you need to access private repositories, you will either need to share your configured credentials, or mount your `ssh-agent` socket inside the running container:
 
+**Note:** This currently does not work on OSX, see [docker/for-mac#410](https://github.com/docker/for-mac/issues/410).
+
 ```sh
 docker run --rm --interactive --tty \
     --volume $PWD:/app \
@@ -44,7 +46,7 @@ docker run --rm --interactive --tty \
     composer install
 ```
 
-When combining the use of private repositories with running Composer as another (local) user, you might run into non-existant user errors. To work around this, simply mount the host passwd and group files (read-only) into the container:
+When combining the use of private repositories with running Composer as another (local) user, you might run into non-existant user errors (thrown by ssh). To work around this, simply mount the host passwd and group files (read-only) into the container:
 
 ```sh
 docker run --rm --interactive --tty \
@@ -63,7 +65,7 @@ docker run --rm --interactive --tty \
 
 We aim to deliver an image that is as lean as possible, built for running Composer only.
 
-Sometimes dependencies or Composer [scripts](https://getcomposer.org/doc/articles/scripts.md) require the availability of certain PHP extensions. In this scenario, you have two options:
+Sometimes dependencies or Composer [scripts](https://getcomposer.org/doc/articles/scripts.md) require the availability of certain PHP extensions. You can work around this as follows:
 
 -	Pass the `--ignore-platform-reqs` and `--no-scripts` flags to `install` or `update`:
 
@@ -75,6 +77,16 @@ Sometimes dependencies or Composer [scripts](https://getcomposer.org/doc/article
 
 -	Create your own image (possibly by extending `FROM composer`).
 
+**Note:** Docker introduced [multi-stage](https://docs.docker.com/engine/userguide/eng-image/multistage-build/) builds in 17.05:
+
+-	Create your own image, and copy Composer from the official image into it:
+
+	```dockerfile
+	COPY --from=composer:1.5 /usr/bin/composer /usr/bin/composer
+	```
+
+It is highly recommended that you create a "build" image that extends from your baseline production image. Binaries such as Composer should not end up in your production environment.
+
 ### Local runtime/binary
 
 If you want to be able to run `composer` as if it was installed on your host locally, you can define the following function in your `~/.bashrc`, `~/.zshrc` or similar: