From bc5cd482ec8fa73dba63f12ffecb1f9253b513a3 Mon Sep 17 00:00:00 2001 From: Rob Bast Date: Tue, 26 Feb 2019 13:51:16 +0100 Subject: [PATCH 1/2] update Composer readme, rephrasing, partitioning and additions/removals --- composer/content.md | 156 +++++++++++++++++++++++++------------------- 1 file changed, 90 insertions(+), 66 deletions(-) diff --git a/composer/content.md b/composer/content.md index 13c1eb243..4b12dc3ec 100644 --- a/composer/content.md +++ b/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 +Running the `composer` image is as simple as follows: + +```console docker run --rm --interactive --tty \ - --volume $PWD:/app \ - %%IMAGE%% install + --volume $PWD:/app \ + %%IMAGE%% install ``` -You can mount the Composer home directory from your host inside the Container to share caching and configuration files: +### Persistent cache / global configuration -```sh +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 + --volume $PWD:/app \ + --volume $COMPOSER_HOME:/tmp \ + %%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: +**Note:** this relies on the fact that the `COMPOSER_HOME` value is set to `/tmp` in the image by default. -```sh +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 \ - --volume $PWD:/app \ - --user $(id -u):$(id -g) \ - %%IMAGE%% install + --env COMPOSER_HOME \ + --env COMPOSER_CACHE_DIR \ + --volume $COMPOSER_HOME:$COMPOSER_HOME \ + --volume $COMPOSER_CACHE_DIR:$COMPOSER_CACHE_DIR \ + --volume $PWD:/app \ + %%IMAGE%% install ``` +### 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: + +```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 +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 \ - --env SSH_AUTH_SOCK=/ssh-auth.sock \ - %%IMAGE%% install + --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: +# Troubleshooting -```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 -``` +### 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 + ```json + { + "config": { + "platform": { + "php": "7.1.3" + } + } + } + ``` + +### PHP extensions + +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. + +Suggestions: + +- 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 + --volume $PWD:/app \ + %%IMAGE%% install --ignore-platform-reqs --no-scripts ``` -- Create your own image (possibly by extending `FROM composer`). +- create your own buid image and [install](https://getcomposer.org/doc/faqs/how-to-install-composer-programmatically.md) Composer inside it. -**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: + **Note:** Docker 17.05 introduced [multi-stage builds](https://docs.docker.com/develop/develop-images/multistage-build/), simplifying this enormously: ```dockerfile - COPY --from=%%IMAGE%%:1.5 /usr/bin/composer /usr/bin/composer + COPY --from=%%IMAGE%% /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: - -```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%% "$@" -} -``` From 5accd167e886ebb1a8bfee95f470068edc114f97 Mon Sep 17 00:00:00 2001 From: Tianon Gravi Date: Tue, 26 Feb 2019 12:20:42 -0800 Subject: [PATCH 2/2] Apply markdownfmt --- composer/content.md | 52 ++++++++++++++++++++++----------------------- 1 file changed, 26 insertions(+), 26 deletions(-) diff --git a/composer/content.md b/composer/content.md index 4b12dc3ec..dd893a379 100644 --- a/composer/content.md +++ b/composer/content.md @@ -13,7 +13,7 @@ You can read more about Composer in our [official documentation](https://getcomp Running the `composer` image is as simple as follows: ```console -docker run --rm --interactive --tty \ +$ docker run --rm --interactive --tty \ --volume $PWD:/app \ %%IMAGE%% install ``` @@ -23,7 +23,7 @@ docker run --rm --interactive --tty \ 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 \ +$ docker run --rm --interactive --tty \ --volume $PWD:/app \ --volume $COMPOSER_HOME:/tmp \ %%IMAGE%% install @@ -34,9 +34,9 @@ docker run --rm --interactive --tty \ 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 \ +$ 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 \ @@ -50,7 +50,7 @@ docker run --rm --interactive --tty \ 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: ```console -docker run --rm --interactive --tty \ +$ docker run --rm --interactive --tty \ --volume $PWD:/app \ --user $(id -u):$(id -g) \ %%IMAGE%% install @@ -61,7 +61,7 @@ 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: ```console -docker run --rm --interactive --tty \ +$ docker run --rm --interactive --tty \ --volume $PWD:/app \ --volume $SSH_AUTH_SOCK:/ssh-auth.sock \ --env SSH_AUTH_SOCK=/ssh-auth.sock \ @@ -73,7 +73,7 @@ docker run --rm --interactive --tty \ 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 \ +$ docker run --rm --interactive --tty \ --volume $PWD:/app \ --volume $SSH_AUTH_SOCK:/ssh-auth.sock \ --volume /etc/passwd:/etc/passwd:ro \ @@ -91,23 +91,23 @@ Our image is aimed at quickly running Composer without the need for having a PHP Suggestions: -* use [`--ignore-platform-reqs`](https://getcomposer.org/doc/03-cli.md#install-i): +- use [`--ignore-platform-reqs`](https://getcomposer.org/doc/03-cli.md#install-i): - ```console - composer install --ignore-platform-reqs - ``` + ```console + $ composer install --ignore-platform-reqs + ``` -* specify the target [platform](https://getcomposer.org/doc/06-config.md#platform) in your `composer.json`: +- specify the target [platform](https://getcomposer.org/doc/06-config.md#platform) in your `composer.json`: - ```json - { - "config": { - "platform": { - "php": "7.1.3" - } - } - } - ``` + ```json + { + "config": { + "platform": { + "php": "7.1.3" + } + } + } + ``` ### PHP extensions @@ -118,14 +118,14 @@ Suggestions: - 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 + $ docker run --rm --interactive --tty \ + --volume $PWD:/app \ + %%IMAGE%% install --ignore-platform-reqs --no-scripts ``` - 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: + **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