Adds Docker Image v1 Spec Documention

Docker-DCO-1.1-Signed-off-by: Josh Hawn <josh.hawn@docker.com> (github: jlhawn)
@mmdriley wrote:
> What does it mean to "run" a Docker container? Are all containers "runnable"? You claim all ancestors of a Docker container are runnable, but some may not include the "CMD" or "ENTRYPOINT" commands added in later layers.

Any layer of an image is still runnable. It's ultimately up to the users to either set valid defaults for the entry point and/or command and they can always set a command to run upon creating the container with any image - and they must if one isn't specified. It's also dependent upon the user to execute a command that is valid in the first place, e.g., trying to run anything in an image with an empty filesystem would simply result in an error - "file not found".

> I'm worried that the goal of this effort -- adding a rigorous specification that enables independent implementations -- is at risk if we start off already assuming tons of context about how the official Docker client works in December 2014.

A lot of things in Docker seem to have traditionally been implementation driven: "Got an idea? It's useful? Great! Got a patch? Does it work? Cool, it's in! What's next?". I'm glad to see the project now moving towards a more specification/open-design driven way of doing things. While I think the project does a good job of documenting how to *use* Docker, unfortunately many details on how some components are currently designed and implemented have always been spread across various parts of the code or distributed in the knowledge of maintainers and experts of different subsystems. So, I'm not quite sure how to answer this part of your question other than by just pointing out that this isn't meant to be a rigorous new specification but just description of how it already works.

@nathanleclaire I'll switch to use your suggested intro for now. @mmdriley do you have a suggestion for an abstract description of a container image that we could use as an introduction?