Proposal: Docker Compose

[aanand]

This proposal, deprecating #9459, is for a command-line tool for orchestration of multi-container apps, suitable for development environments, automated CI setups and staging and production deployments, and working fluidly with Docker Machine and Docker Swarm.

Based in large part on feedback to #9459 from the Docker community, we propose the following:

• Compose is a standalone command-line tool, rather than built into the Docker client binary.
• The initial release of Compose is directly based on the Fig codebase, rather than written from scratch, and focused around cleanup and any backwards-incompatible changes from Fig.
• A roadmap of features for Compose and (if deemed appropriate) the Docker engine, so as to achieve production-suitability and seamless integration with Swarm, is planned.

Separate tool

The arguments in favour of building Compose directly into the Docker client are based on usability issues we’ve observed with Fig:

• Newcomers to Docker find Fig more immediately easy to understand and relevant to their needs, so it makes sense for them to have that benefit out-of-the-box.
• People are often confused about the distinction between Fig and Docker, so it would be beneficial from a UX perspective if there were no distinction.
• Fig is “one more thing to install” that prevents users from getting up and running.
• Problems arise when versions of Fig and Docker are incompatible.

However, there are also usability arguments against building it in:

• The various Docker commands become context-sensitive (i.e. they behave differently based on the contents of the current directory) and overloaded with meaning (arguments can either designate literal container names or names in the configuration file).
• Docker users who aren’t interested in Compose’s features will nonetheless have to live with a tool that’s both physically and conceptually larger.

Furthermore, technical and social arguments strongly favour separation: the responsibilities of Compose and those of the current Docker client don’t overlap, and it’s better to avoid conflating non-coupled concerns in one codebase, because:

• It’ll make the codebase even larger.
• It’ll force both projects to share a release cycle, making it harder to experiment on Compose and to make changes to either one.
• It’ll put extra burden on the core maintainers.
• It’ll be harder to find issues and PRs if they all live in the same GitHub repository.

Furthermore, a separate tool will help guide the definition and maintenance of the Docker API(s), keeping the door open for a healthy ecosystem of alternatives.

Finally, it’s still possible to go carefully from a separate tool to an integrated one in the future; extracting a separate tool back out again, however, is much harder.

Based on Fig

Fig in its current state is a great orchestration tool for development/CI, and a usable one for simple production deployments. Its codebase is mature and well-understood, and doesn’t carry a lot of technical debt (though there are improvements which can and should be made!)

It would make an excellent starting point - and, given Compose is a new tool, we’d be free to make breaking changes from Fig’s logic for the first release.

Features roadmap

As well as a number of smaller features that have been requested for Fig (which will still be triaged and implemented where appropriate), several high-level features are needed to get Compose to a state where it’s suitable for multi-host production deploys. Compose’s priorities after the initial release will be identifying, designing and implementing these in collaboration with the community and users. Discussion for many of these is already ongoing on the Fig GitHub project.

[jokeyrhyme]

As mentioned in #9459:

• I'd like the option of using a less ambiguous definition format: TOML or JSON are less "magical" than YAML
• it'd be terrific if every docker CLI option was able to be handled in the definition: there are loads of things I end up needing external scripts for with fig, where crane covers everything I can think of

[pkieltyka]

I like the idea of a Stackfile in TOML. Anyone else?

[dnephin]

I personally really prefer YAML, but I don't see a need to restrict it to just one format. All of these formats should be able to map to a common representation internally.

[aanand]

I like the reduced ambiguity/size of TOML. My main complaint is that nesting is more verbose. Translating the group.yml example from #9459:

name = "rails_example"

[containers]

  [containers.db]
  image = "postgres:latest"

  [containers.web]
  build = "."
  command = "bundle exec rackup -p 3000"
  volumes = [".:/myapp"]
  ports = ["3000:3000"]
  links = ["db"]

I'm not a huge fan of how the containers key is repeated for every sub-dictionary. If another level of nesting were introduced for some reason, the whole file would get yet more verbose.

This might not end up being an issue, but it warrants consideration.

[aanand]

@jokeyrhyme: yes, Compose should aim to cover every Docker CLI option.

[pkieltyka]

@aanand you can make this work too:

name = "rails_example"

[containers.db]
image = "postgres:latest"

[containers.web]
build = "."
command = "bundle exec rackup -p 3000"
volumes = [".:/myapp"]
ports = ["3000:3000"]
links = ["db"]

I do something similar in a project conf.

I think YAML is also fine though, I just would really prefer not to see the .yml extension on the filename.. even .conf would make me happier. Just my 2cents.

[tianon]

One issue I've seen with YAML in the wild (specifically in fig.yml) is that things like an environment: value of true have to be quoted or they become True (thanks to true -> True -> True.to_s).

[ewindisch]

Not suggesting we solve every use case, but one major limitation of most of the proposals I've seen is the lack of piping. I want a compose framework which pipes containers together. Currently, I've been using shell scripts wrapping the client...

[softprops]

One + for json is that it's extremely easy to consume due to ubiquity in json parsers for every flavor of programming language. It's designed for both humans and machines to read. Yaml is easy for humans to read ( sometimes... if you can eye up your whitespace ) but deceptively hard for machines. Compare it's spec with json's if you disagree :).

I would prefer a format that makes it easy to build new tooling on top of rather than encouraging a single project to have different descriptions of the same information for different tools.

[xiaods]

just like boot2docker, docker is already the owner of fig, why not enhance the fig to implement the docker compose feature?

[thaJeztah]

+1 on supporting multiple formats. Depending on your case, JSON, TOML or YAML could be prefered. Since all formats should be easy to map to the same "internal" format, I don't see a reason to not support them.

Should there be a "default" format? (Thinking of what format to use for examples in the documentation)

[xiaods]

share the fig multi host patch
Enable services to use different Docker Hosts
docker/compose#607

[mkawalec]

If we are requesting features, docker exec is immensly important to me for debugging (sometimes you just want to tinker with a raw source file), I would love to see it in an exposed place.

[thaJeztah]

share the fig multi host patch
Enable services to use different Docker Hosts

I don't think that is nescessary to implement in Compose; Compose should be able to talk to Swarm and have Swarm take care of which host a service will be deployed to.

The only thing that compose has to take care of, is passing the constraints (ie, ports, memory etc) to Swarm to act on.

[aanand]

@xiaods, @thaJeztah: Correct. Multi-host deployment should be Swarm's responsibility, not Compose's - although if Swarm makes changes to the Docker API to allow for e.g. scheduling hints, Compose should support them.

The multi-host patch is a good solution for simple cases, but we need to solve this issue more comprehensively, taking into account difficult stuff like volumes and links.

[nathanleclaire]

+1 external tool

IMO, the overarching goal for compose should be : Fig with better concurrency, some of the known issues sanded off, and multi-host support. "Don't get too smart", and provide useful building blocks for others to play with in next-order tools. I think this proposal heads in a direction which can meet those goals quite well.

On the matter of various serialization formats: In an ideal world we'd have plugins that allow users to use whichever they want (YAML, JSON, TOML, XML) that gets serialized down to a common format (perhaps JSON due to its ubiquity and ease of demarshalling into a Go struct).

In reality, JSON is very close to a subset of YAML for many of the cases which are covered by a fig-like tool (see https://github.com/nathanleclaire/jsonfig/blob/master/fig.yml for an example of writing JSON for fig, no mods needed). So I think that starting with a YAML parser which has some implicit JSON support is pretty reasonable. I used to really hate YAML but once I saw a 100+ line fig.yml I really appreciated its terseness a lot more. A huge variety of easily available conversion tools exist too.

One thing I'd really like to see is something like this (maybe it'd be built into up etc.):

$ compose validate Dockergroup.yml
err: line 15: value for key "links" is not an array.  Perhaps it should look more like
links:
 - redis
$ vi Dockergroup.yml
$ compose validate Dockergroup.yml
Everything looks good!
$

I think it'd go a long way towards cutting down on YAML confusion. Some such error messages in fig today exist but they can be a little esoteric.

[aanand]

@nathanleclaire Agreed on validation, it's been needed for ages (docker/compose#129). It should always run when reading fig.yml, and there should also be a way to just validate a file and exit, as in your example.

[pkieltyka]

I think supporting so many file formats for the compose configuration is over board and you guys should pick just one. I hope that'll be TOML, but whatever the authors decide is cool.

On Dec 17, 2014, at 9:08 PM, Nathan LeClaire notifications@github.com wrote:

+1 external tool

IMO, the overarching goal for compose should be : Fig with better concurrency, some of the known issues sanded off, and multi-host support. "Don't get too smart", and provide useful building blocks for others to play with in next-order tools. I think this proposal heads in a direction which can meet those goals quite well.

On the matter of various serialization formats: In an ideal world we'd have plugins that allow users to use whichever they want (YAML, JSON, TOML, XML) that gets serialized down to a common format (perhaps JSON due to its ubiquity and ease of demarshalling into a Go struct).

In reality, JSON is very close to a subset of YAML for many cases are covered by a fig-like tool (see https://github.com/nathanleclaire/jsonfig/blob/master/fig.yml for an example of writing JSON for fig, no mods needed), so I think starting with a YAML parser that has some implicit JSON support is pretty reasonable. I used to really hate YAML but once I saw a 100+ line fig.yml I really appreciated its terseness a lot more. A huge variety of easily available conversion tools exist too.

One thing I'd really like to see is something like this (maybe it'd be built into up etc.):

$ compose validate Dockergroup.yml
err: line 15: value for key "links" is not an array. Perhaps is should look more like
links:

• redis
  $ vi Dockergroup.yml
  $ compose validate Dockergroup.yml
  Everything looks good!
  $
  I think it'd go a long way towards cutting down on YAML confusion.

—
Reply to this email directly or view it on GitHub.

[marcellodesales]

+1 for multiple file formats... As long as they are all fully supported... Coming from Node.js and Java, I would be just easily generating JSON/YAML files...

[burnzoire]

Pick a single format to keep things simple for new users. We don't need projects and examples fragmented across different syntaxes. Happy with yaml as per fig, although I miss the flexibility of ruby ala Vagrantfile.

[vaceletm]

+1 fort single end user format. Like Nathan said, with a bit of syntax
check, it's very readable as of today (despite I'm not a huge fan of yaml)

The argument for doc fragmentation is very relevant. Ppl will copy/paste
things from various sources (tuto, blog, doc, stack overflow, gist). This
is the way we work nowadays so it should be easy and straightforward.

More formats, more code, more bugs less features.
Le 18 déc. 2014 06:53, "Nathan Burns" notifications@github.com a écrit :

Pick a single format to keep things simple for new users. We don't need
projects and examples fragmented across different syntaxes. Happy with yaml
as per fig, although I miss the flexibility of ruby ala Vagrantfile.

—
Reply to this email directly or view it on GitHub
#9694 (comment).

[Ragsboss]

Has anyone looked at existing state-of-art around composition? For example, TOSCA (Topology and Orchestration Specification for Cloud Applications) is a standard that defines a generic meta-model for composition. They use YAML too and refer to Open Stack HEAT as the reference implementation. https://www.oasis-open.org/committees/download.php/52571/TOSCA-Simple-Profile-YAML-v1.0-wd01-Rev-38.pdf. This gives a portable way (backed by standards body) to build composition manifests and users don't need to learn multiple languages/frameworks.

I haven't analyzed use of TOSCA or HEAT to model multi-container apps but given the domain agnosticity behind these tools, that (in theory) shouldn't be an issue. http://getcloudify.org/guide/3.0/understanding-blueprints.html is an open-source implementation of TOSCA standard.

[gabrielgrant]

Echoing @craftgear in #9459 : If this is simply a proposal to improve fig, why create a new tool, rather than just ... improve fig?

[marcellodesales]

+1 to improve Fig! and integrate it into Docker.

[scottstamp]

If the idea in question is really whether or not to merge Fig into the standard CLI, why not just give it a command namespace? docker compose ... for composition-specific tasks and docker ... for everything else? Also, I'm not sure how feasible this would actually be, but if keeping the codebase clean is of a paramount concern, maybe it could be added as an optional "plugin" for the client.

Think:

• Install Docker (just docker)
• Implement a docker plugins ... namespace
• Global plugin registry (or git integration) to allow for something like docker install compose
• Compose becomes available through the docker compose ... namespace.

Not sure if this might be too heavy of a solution but I could see it being beneficial to new users. Personally I'm fine with installing fig through pip and calling it a day.

[huslage]

IMO, TOSCA is a standard in search of a reason to exist. It is overly complex for a Docker multi-container environment and adds a ridiculous amount of XML-like overhead. The fig.yml + broader support for Docker options is the right way to go, I think.

[pkieltyka]

Agreed

On Dec 23, 2014, at 6:28 PM, Aaron Huslage notifications@github.com wrote:

IMO, TOSCA is a standard in search of a reason to exist. It is overly complex for a Docker multi-container environment and adds a ridiculous amount of XML-like overhead. The fig.yml + broader support for Docker options is the right way to go, I think.

—
Reply to this email directly or view it on GitHub.

[noirbizarre]

Yep, that's what I did but it's kind of hackish, no ?
And, it breaks projects still using fig (I have some)

[Stono]

I have this as part of my cookbook which configures the box for dockerness

ln -s /usr/bin/docker-compose /bin/fig

[funkyfuture]

it should be ln -s … /usr/local/bin/fig

[ferdynice]

I think it is silly to use 'fig' as a recommended alias, because this will confuse anyone not familiar with the project's origin.

Since 'compose' and 'dc' already seem to be existing commands and 'dcom' is too Microsofty, I'm in favor of 'dcomp'.

On second thoughts 'doco' is really fast to type, beats 'dcomp' by a mile. Anyway just my 2 cents.

[olalonde]

Some name inspiration:

• Crane: machine used to place containers on cargos

[thaJeztah]

I'm in favor of 'dcomp'.

That sounds like "de-comp" / "de-compose". I don't like the smell of that :)

@olalonde you realize "Crane" is an existing product? Similar to docker-compose, but (iirc) communicates with docker via the CLI in stead of the API

[ferdynice]

@thaJeztah
Good point. For now I am using 'doco'.

[almereyda]

When I look at crane and fig and (RIP) gaudi, I really want to see this kind of orchestration minimally standardized.

[olalonde]

@olalonde you realize "Crane" is an existing product?

@thaJeztah no I didn't :)

Personally, dcomp also make me think of de-compose. doco is not bad but it is very similar to docco which is a widely used documentation generator for Javascript code (http://jashkenas.github.io/docco/). I think docko would be better if anything.

[wernight]

"Crane" even taken, sounds really good (and since Fig and Crane and Docker Compose seem to try going the same thing the same way, why not have a good strong official one doing that).

[madwire]

@wernight thats what this proposal is about, also fig is docker compose as its undergoing a name change.

[marcellodesales]

+1 on Crane!

[almereyda]

As in

docker crane mv sdc:local sdc:almereyda@remote.host.tld --verbose

which initiates a move, for example? Does this require we're all using ZFS soon*?

Just want to keep up on the direction we're taking here. Especially also in terms of CoreOS' and btrfs plus the APIs to generalize able interfaces like Panamax, ex-Gaudi, Cockpit, dockerboard and the likes?

---

*Where sdc stands for a vocabulary that defines a Secure Docker Crane at the endpoint.

[alexisvincent]

In terms of the arguments to keep compose separate from docker cli. Can we not do the following:

• Keep them separate -> All the benefits of a separate codebase.
• Have a 'docker compose / docker up' command which forwards to compose -> better ux
• This could also check compose versions and prompt the user to update compose if outdated.

This type of rig makes more sense to me.

[aanand]

Attention, all: work is progressing on Docker Compose, based on the Fig codebase. A release candidate is out.

https://github.com/docker/fig/releases/tag/1.1.0-rc2

[wernight]

I found docker-compose requires Docker 1.4+. This wasn't for Fig. Should
probably be written somewhere if that's the case, no?

On Mon Feb 16 2015 at 5:33:59 PM Aanand Prasad notifications@github.com
wrote:

Attention, all: work is progressing on Docker Compose, based on the Fig
codebase. A release candidate is out.

https://github.com/docker/fig/releases/tag/1.1.0-rc2

—
Reply to this email directly or view it on GitHub
#9694 (comment).

[aanand]

@wernight Compose should work with Docker 1.3 - if it doesn't, please open an issue!

[jghibiki]

Another idea for a name:

docker shipment

or for short

docker ship

Rationale: A fig.yml comprises of a "shipment" of services.

[baptistedonaux]

@aanand I use Compose 1.1.0-rc2 with 1.3.3. It works

[bfirsh]

Compose has now been released and is available here: http://docs.docker.com/compose/

[bfirsh]

Thanks all for your feedback!

[thaJeztah]

@sanchitiks the GitHub issue tracker is not a support forum. If you need support using docker or docker-compose, please ask you question in the #docker-compose or #docker IRC channel, on https://forums.docker.com or the docker-user group on Google Groups.

[JemiloII]

I'm posting my bit of knowledge here. Don't worry about the tcp ports. Just locate your docker.sock file. Mine was in /run/ others could be in /var/run and use that path for DOCKER_HOST

export DOCKER_HOST=/run/docker.sock worked for me
export DOCKER_HOST=/path/to/docker.sock should work for you.