Feedback for: compose/bundles.md

[stefanoborini]

File: compose/bundles.md, CC: @londoncalling

I think you should explain better what they are, and which problem they want to solve. As a person who has no idea about it and came to this page, after reading it I still don't have an answer.

[londoncalling]

@stefanoborini Thanks for the feedback.

I've added some "related topics" at the end of this page (processing now, should publish soon). The answer to your question is essentially in this paragraph near the top of the page you referenced:

A Dockerfile can be built into an image, and containers can be created from
that image. Similarly, a docker-compose.yml can be built into a distributed
application bundle, and stacks can be created from that bundle. In that
sense, the bundle is a multi-services distributable image format.

Bundles are a method of packaging up and distributing multi-service apps. However, I believe the related topics links I've included should help put DAB files in context, if the above explanation was not enough. This packaging mechanism is experimental, and we may not emphasize it going forward, so I hesitate putting more detail in it at this point.

@ManoMarks @nathanleclaire @joaofnfernandes any thoughts on this?

[joaofnfernandes]

I definitely share @stefanoborini feeling. Since the feedback is too high level, let me try to break down a bit.

Similarly, a docker-compose.yml can be built into a distributed application bundle, and stacks can be created from that bundle.

Our explanation about bundles is rooted on docker-compose.yml. If I don't know what a docker-compose.yml is, then I'm in a worst shape than when I started reading. I came here searching for answers and now I have two questions.

We also use the word "stack" to explain what a bundle is. The problem is that stack is a really ambiguous word so there's lots of room for interpretation. In Docker core "stack" means one thing, in Docker Cloud another. Also, other products have different names for the same concept, so we can't assume someone reading this knows what we mean. "Pod" and "application" come to mind.

A diagram with the concepts and workflow how to get from a Dockerfile to a running stack would literally be worth a thousand words.

The easiest way to produce a bundle is to generate it using docker-compose

We jump to explain how to generate a bundle, but it's not yet clear what's the difference between a docker-compose.yml and an application bundle definition. If I can generate a DAB from a docker-compose.yml, it seems that they are exactly the same, in which case why should I ever create a DAB?

From what I understand the current official way is to create docker-compose-yml files and use docker-compose up or docker stack deploy --compose-file <file>, so I'm not sure we should invest in updating this article.

Given that with 1.13 there's a huge overlap between the two operations above, I think a better investment would be to explain upfront that:

1. There's this file format docker-compose.yml that allows you to describe a set of containers/services that work together
2. There are several tools that can consume this file. docker stack deploy and docker-compose up are two of them
3. If you're just getting started with Docker, start by learning docker stack deploy since it seems that eventually all of docker-compose functionality will be part Docker.

[londoncalling]

@joaofnfernandes makes sense, and sounds like we are in agreement that a) we shouldn't continue to emphasize DAB/bundles, and b) the best direction is to point folks to docker stack deploy and related concepts.

@stefanoborini I'll update this topic further when I get a chance to fully explain docker-compose.yml, docker stack deploy and docker-compose. My idea of adding those as "Related topics" was a shortcut to that for the moment. I'll flesh this out as soon as I can. I hope this discussion and those links I added helps for now.

[londoncalling]

@stefanoborini The updates to the topic you asked about are now published.

In Docker stacks and distributed application bundles (experimental), please have a look at the Overview and Related topics sections.

Closing this issue. Thanks for your feedback, and please send more comments if needed.

[docker-robott]

Closed issues are locked after 30 days of inactivity.
This helps our team focus on active issues.

If you have found a problem that seems similar to this, please open a new issue.

/lifecycle locked