"What Compose Does" document

[aanand]

Prompted partly by @thaJeztah's remarks in #1356 (comment), I think it'd be good to have a high-level document that described:

1. What Compose does: where in the stack it fits, which problems it solves (or plans to eventually solve) and which ones it doesn't.
2. How it works: not delving beneath Docker's abstraction layer, but explaining how Compose decides what to do (build/pull images, create/start/stop/remove containers), when to do it, and salient details (How do we generate the container configuration? How do we keep track of containers and images? etc)

Thoughts?

[aanm]

I think it would be useful to have a list of docker commands that are executed per each compose commands.
For example:

compose up results on the following:
  - containers = docker ps -a
  [for each container in containers]:
     - docker stop $container
     - docker rm $container
     - docker create $container
     - docker start $container

[thaJeztah]

@aanm I can see that as part of the second bullet.

A nice diagram would make a nice addition there, I think. See for example, this: moby/moby#12164

[thaJeztah]

For the "high level" description, I regularly see people that don't understand that it's Docker that runs the containers, and compose "only" instructs Docker how to create and start the containers so yes, it's needed.

[aanm]

@thaJeztah nice diagram! thanks for the link

[dnephin]

+1 for this document. I think it'll help a lot

[dnephin]

For "what problems does it not solve" I think we should have a section about "Building Images".

There are frequently requests for more complex build pipelines, but this isn't really a problem which is related to composition. There are existing tools (https://github.com/6si/shipwright, https://github.com/openshift/source-to-image) for dealing with building images.

Considering #693, compose could actually be made to only work off of images. Building images could be a completely separate tool, but most likely docker-compose build will be kept around for the immediate future for backwards compatibility.

[ijc]

Issue grooming: I confess I've not actually checked against the specifics here but the state of the world of documentation for compose is very different to May 2015 so I think it can be assumed that at a high level this issue is obsolete. If not then I think bugs for docs are now tracked on https://github.com/docker/docker.github.io/ so any further improvements ought to be tracked there.