Merge pull request #1438 from alcohol/master

Update Composer documentation

composer/content.md

@@ -6,103 +6,127 @@ You can read more about Composer in our [official documentation](https://getcomp
 
 %%LOGO%%
 
-# Using
+# How to use this image
 
-Run the `composer` image:
+### Basic usage
 
-```sh
-docker run --rm --interactive --tty \
-    --volume $PWD:/app \
-    %%IMAGE%% install
+Running the `composer` image is as simple as follows:
+
+```console
+$ docker run --rm --interactive --tty \
+  --volume $PWD:/app \
+  %%IMAGE%% install
+```
+
+### Persistent cache / global configuration
+
+You can bind mount the Composer home directory from your host to the container to enable a persistent cache or share global configuration:
+
+```console
+$ docker run --rm --interactive --tty \
+  --volume $PWD:/app \
+  --volume $COMPOSER_HOME:/tmp \
+  %%IMAGE%% install
 ```
 
-You can mount the Composer home directory from your host inside the Container to share caching and configuration files:
+**Note:** this relies on the fact that the `COMPOSER_HOME` value is set to `/tmp` in the image by default.
 
-```sh
-docker run --rm --interactive --tty \
-    --volume $PWD:/app \
-    --volume $COMPOSER_HOME:/tmp \
-    %%IMAGE%% install
+Or if you are following the XDG specification:
+
+```console
+$ COMPOSER_HOME=$HOME/.config/composer \
+  COMPOSER_CACHE_DIR=$HOME/.cache/composer \
+  docker run --rm --interactive --tty \
+  --env COMPOSER_HOME \
+  --env COMPOSER_CACHE_DIR \
+  --volume $COMPOSER_HOME:$COMPOSER_HOME \
+  --volume $COMPOSER_CACHE_DIR:$COMPOSER_CACHE_DIR \
+  --volume $PWD:/app \
+  %%IMAGE%% install
 ```
 
-By default, Composer runs as root inside the container. This can lead to permission issues on your host filesystem. You can run Composer as your local user:
+### Filesystem permissions
+
+By default, Composer runs as root inside the container. This can lead to permission issues on your host filesystem. You can work around this by running the container with a different user:
 
-```sh
-docker run --rm --interactive --tty \
-    --volume $PWD:/app \
-    --user $(id -u):$(id -g) \
-    %%IMAGE%% install
+```console
+$ docker run --rm --interactive --tty \
+  --volume $PWD:/app \
+  --user $(id -u):$(id -g) \
+  %%IMAGE%% install
 ```
 
+### Private repositories / SSH agent
+
 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:
 
+```console
+$ docker run --rm --interactive --tty \
+  --volume $PWD:/app \
+  --volume $SSH_AUTH_SOCK:/ssh-auth.sock \
+  --env SSH_AUTH_SOCK=/ssh-auth.sock \
+  %%IMAGE%% install
+```
+
 **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 \
-    --volume $SSH_AUTH_SOCK:/ssh-auth.sock \
-    --env SSH_AUTH_SOCK=/ssh-auth.sock \
-    %%IMAGE%% install
+When combining the use of private repositories with running Composer as another user, you might run into non-existent user errors (thrown by ssh). To work around this, simply mount the host passwd and group files (read-only) into the container:
+
+```console
+$ docker run --rm --interactive --tty \
+  --volume $PWD:/app \
+  --volume $SSH_AUTH_SOCK:/ssh-auth.sock \
+  --volume /etc/passwd:/etc/passwd:ro \
+  --volume /etc/group:/etc/group:ro \
+  --env SSH_AUTH_SOCK=/ssh-auth.sock \
+  --user $(id -u):$(id -g) \
+  %%IMAGE%% install
 ```
 
-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 \
-    --volume $PWD:/app \
-    --volume $SSH_AUTH_SOCK:/ssh-auth.sock \
-    --volume /etc/passwd:/etc/passwd:ro \
-    --volume /etc/group:/etc/group:ro \
-    --user $(id -u):$(id -g) \
-    --env SSH_AUTH_SOCK=/ssh-auth.sock \
-    %%IMAGE%% install
-```
+# Troubleshooting
+
+### PHP versions
 
-## Suggestions
+Our image is aimed at quickly running Composer without the need for having a PHP runtime installed. You should not rely on the PHP version in our container. We do not provide a Composer image for each supported PHP version because we do not want to encourage using Composer as a base image or a production image.
 
-### PHP Extensions
+Suggestions:
 
-We aim to deliver an image that is as lean as possible, built for running Composer only.
+-	use [`--ignore-platform-reqs`](https://getcomposer.org/doc/03-cli.md#install-i):
 
-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:
+	```console
+	$ composer install --ignore-platform-reqs
+	```
 
--	Pass the `--ignore-platform-reqs` and `--no-scripts` flags to `install` or `update`:
+-	specify the target [platform](https://getcomposer.org/doc/06-config.md#platform) in your `composer.json`:
 
-	```sh
-	docker run --rm --interactive --tty \
-	    --volume $PWD:/app \
-	    %%IMAGE%% install --ignore-platform-reqs --no-scripts
+	```json
+	{
+	  "config": {
+	    "platform": {
+	      "php": "7.1.3"
+	    }
+	  }
+	}
 	```
 
--	Create your own image (possibly by extending `FROM composer`).
+### PHP extensions
 
-**Note:** Docker introduced [multi-stage](https://docs.docker.com/engine/userguide/eng-image/multistage-build/) builds in 17.05:
+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.
 
--	Create your own image, and copy Composer from the official image into it:
+Suggestions:
 
-	```dockerfile
-	COPY --from=%%IMAGE%%:1.5 /usr/bin/composer /usr/bin/composer
+-	pass the `--ignore-platform-reqs` and / or `--no-scripts` flags to `install` or `update`:
+
+	```console
+	$ docker run --rm --interactive --tty \
+	  --volume $PWD:/app \
+	  %%IMAGE%% install --ignore-platform-reqs --no-scripts
 	```
 
-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:
-
-```sh
-composer () {
-    tty=
-    tty -s && tty=--tty
-    docker run \
-        $tty \
-        --interactive \
-        --rm \
-        --user $(id -u):$(id -g) \
-        --volume /etc/passwd:/etc/passwd:ro \
-        --volume /etc/group:/etc/group:ro \
-        --volume $(pwd):/app \
-        %%IMAGE%% "$@"
-}
-```
+-	create your own buid image and [install](https://getcomposer.org/doc/faqs/how-to-install-composer-programmatically.md) Composer inside it.
+
+	**Note:** Docker 17.05 introduced [multi-stage builds](https://docs.docker.com/develop/develop-images/multistage-build/), simplifying this enormously:
+
+	```dockerfile
+	COPY --from=%%IMAGE%% /usr/bin/composer /usr/bin/composer
+	```