Merge pull request docker#2042 from londoncalling/clarify-docker-stac…

…k-deploy-voting-app

clarified docker stack deploy and bundles

compose/bundles.md

@@ -5,23 +5,33 @@ keywords: documentation, docs,  docker, compose, bundles, stacks
 title: Docker stacks and distributed application bundles (experimental)
 ---
 
-> **Note**: This is a copy of the [Docker Stacks and Distributed Application
+> **Note**: This is a modified copy of the [Docker Stacks and Distributed Application
 > Bundles](https://github.com/docker/docker/blob/v1.12.0-rc4/experimental/docker-stacks-and-bundles.md)
-> document in the [docker/docker repo](https://github.com/docker/docker).
+> document in the [docker/docker repo](https://github.com/docker/docker). It's been updated to accurately reflect newer releases.
 
 ## Overview
 
-Docker Stacks and Distributed Application Bundles are experimental features
-introduced in Docker 1.12 and Docker Compose 1.8, alongside the concept of
-swarm mode, and Nodes and Services in the Engine API.
-
 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.
 
-As of Docker 1.12 and Compose 1.8, the features are experimental. Neither
-Docker Engine nor the Docker Registry support distribution of bundles.
+Docker Stacks and Distributed Application Bundles started as experimental
+features introduced in Docker 1.12 and Docker Compose 1.8, alongside the concept
+of swarm mode, and nodes and services in the Engine API. Neither Docker Engine
+nor the Docker Registry support distribution of bundles, and the concept of a
+`bundle` is not the emphasis for new releases going forward.
+
+However, [swarm mode](/engine/swarm/index.md), multi-service applications, and
+stack files now are fully supported. A stack file is a particular type of
+[version 3 Compose file](/compose/compose-file/index.md).
+
+If you are just getting started with Docker and want to learn the best way to
+deploy multi-service applications, a good place to start is the [Sample app
+tutorial](/engine/getstarted-voting-app/index.md). This shows you how to define
+a service configuration in a `docker-stack.yml` file, deploy the app, and use
+the relevant tools and commands.
+
 
 ## Producing a bundle
 
@@ -203,6 +213,8 @@ A service has the following fields:
 
 ## Related topics
 
-* [docker stack deploy] (/engine/reference/commandline/stack_deploy/) command
+* [Sample app tutorial](/engine/getstarted-voting-app/index.md)
+
+* [docker stack deploy](/engine/reference/commandline/stack_deploy/) command
 
-* [deploy](/compose/compose-file/index.md#deploy) option in [Compose files](/compose/compose-file/index.md]]
+* [deploy](/compose/compose-file/index.md#deploy) option in [Compose files](/compose/compose-file/index.md)

engine/getstarted-voting-app/deploy-app.md

@@ -53,13 +53,18 @@ The `docker-stack.yml` file must be located on a manager for the swarm where you
 
 We'll deploy the application from the manager.
 
-1.  Deploy the application stack based on the `.yml` using the command `docker stack deploy` as follows.
+1.  Deploy the application stack based on the `.yml` using the command
+[`docker stack deploy`](/engine/reference/commandline/stack_deploy.md) as follows.
 
     ```
     docker stack deploy --compose-file docker-stack.yml vote
     ```
 
-    Here is an example of the command and the output.
+    * The `--compose-file` option specifies the path to our stack file. In this case, we assume it's in the current directory so we simply name the stack file: `docker-stack.yml`.
+
+    * For the example, we name this app `vote`, but we could name it anything we want.
+
+      Here is an example of the command and the output.
 
     ```
     docker@manager:~$ docker stack deploy --compose-file docker-stack.yml vote

engine/getstarted-voting-app/index.md

@@ -219,12 +219,13 @@ volumes:
 
 ## Docker stacks and services
 
-To deploy the voting app, we will run the `docker stack deploy` command with
-this `docker-stack.yml` file to pull the referenced images and launch the
-services in a swarm.  This allows us to run the application across multiple
-servers, and use swarm mode for load balancing and performance. Rather than
-thinking about running individual containers, we can start to model deployments
-as application stacks and services.
+To deploy the voting app, we will run the [`docker stack
+deploy`](/engine/reference/commandline/stack_deploy.md) command with appropriate
+options using this `docker-stack.yml` file to pull the referenced images and
+launch the services in a swarm.  This allows us to run the application across
+multiple servers, and use swarm mode for load balancing and performance. Rather
+than thinking about running individual containers, we can start to model
+deployments as application stacks and services.
 
 If you are interested in learning more about new Compose version 3.x features, Docker Engine 1.13.x, and swarm mode integration, check out the [list of resources](customize-app.md#resources) at the end of this tutorial.