This is a really good question which describes a principle that I've faced a few times now, actually two separate but related issues:

1.) How To Best Deal With Transient Files in Docker

Docker is great at encapsulating the total and utter recreation of an environment. If you handle part of the process 'outside' the container i.e. you run composer install outside of the docker build process then you have a less portable build process because you may have introduced machine/environment dependencies that you are not aware of.

If you always rebuild the full environment within Docker then you are guaranteeing that your dependencies are always satisfied and that you could give the dockerfile to anyone else and they too will have a high confidence of being able to rebuild locally without issue.

Transient files are ideal for building within Docker ! So I would try to build them within the container whenever possible.

2.) How to de-couple authorisation from Docker build process

Which leads us on to the second issue, how to de-couple authorisation from build?

Option 1 - Bake In composer auth.json with creds for a dedicated build user:

As other answers have said you could 'bake in' the credentials and then remove them again. However you wouldn't want to 'bake in' something as sensitive as your ssh keys. Composer supports an auth.json file so why not create a dedicated build user and store its creds (instead of yours) in the auth.json file? If it is ever compromised you can change the password. Once composer install has finished remove or overwrite the file.

COPY . ./
RUN composer install --no-dev --no-interaction -o
RUN rm -f ./auth.json

Option 2 - Make the creds themselves transient and pass them into the Docker container using docker exec:

I haven't completely tested this approach but I can't see why something like this wouldn't work.

1.) You build a base PHP container which is capable of running 'composer install' (or use one from docker hub)

2.) You spin up this base container so that it is running

3.) You use docker exec to pass in your creds to a wrapper script which is already baked into your container. The wrapper scripts will run composer install using HTTP basic authentication - it will already have the username baked in so you'll just need to provide the password as per the http-basic technique

docker exec -d my_base_php_container php -f /my_wrapper_script.php ${PASSWORD}

4.) You commit this container as a new image

docker commit --change "composer install" ${CONTAINER_ID} my_installed_image:1.0

Funny. Only a few days after posting this question, Docker 17.05 was released and brought a solution for that: multistage builds. Just put your composer stuff inside your dockerfile and build your app. then, start a 2nd stage and copy your app as the build artifact of the 1st stage.

I think in the case you are describing it makes sense to do the composer install outside of the docker build.

You would normally have an initial build process that builds your app code. This build might run some linting or automated testing, and then generate an artifact containing all of the code needed to run your app. This would comprise of your source code, plus your vendor folder and any auto-generated code (ORM classes, caches, etc). These artifacts are typically tar files.

You would then copy that code artifact into your docker container in your subsequent docker build.