Skip to content

Commit

Permalink
update Composer readme, rephrasing, partitioning and additions/removals
Browse files Browse the repository at this point in the history
  • Loading branch information
@alcohol
alcohol committed Feb 26, 2019
1 parent 994b15a commit bc5cd48
Showing 1 changed file with 90 additions and 66 deletions.
156 changes: 90 additions & 66 deletions composer/content.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
```

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:
### Filesystem permissions

**Note:** This currently does not work on OSX, see [docker/for-mac#410](https://github.com/docker/for-mac/issues/410).
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
```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 \
--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:
### 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:

```sh
```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 \
--user $(id -u):$(id -g) \
--env SSH_AUTH_SOCK=/ssh-auth.sock \
%%IMAGE%% install
--volume $PWD:/app \
--volume $SSH_AUTH_SOCK:/ssh-auth.sock \
--env SSH_AUTH_SOCK=/ssh-auth.sock \
%%IMAGE%% install
```

## Suggestions
**Note:** This currently does not work on OSX, see [docker/for-mac#410](https://github.com/docker/for-mac/issues/410).

### PHP Extensions
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:

We aim to deliver an image that is as lean as possible, built for running Composer only.
```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
```

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:
# Troubleshooting

- Pass the `--ignore-platform-reqs` and `--no-scripts` flags to `install` or `update`:
### PHP versions

```sh
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.

Suggestions:

* use [`--ignore-platform-reqs`](https://getcomposer.org/doc/03-cli.md#install-i):

```console
composer install --ignore-platform-reqs
```

* specify the target [platform](https://getcomposer.org/doc/06-config.md#platform) in your `composer.json`:

```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%% "$@"
}
```

0 comments on commit bc5cd48

Please sign in to comment.