Merge pull request #26028 from londoncalling/docs-pinata-for-swarm

Clarify how to use d4mac, d4win with swarm mode

docs/swarm/swarm-tutorial/create-swarm.md

@@ -25,6 +25,12 @@ node. For example, the tutorial uses a machine named `manager1`.
     docker swarm init --advertise-addr <MANAGER-IP>
     ```
 
+    >**Note:** If you are using Docker for Mac or Docker for Windows to test
+single-node swarm, simply run `docker swarm init` with no arguments. There is no
+need to specify ` --advertise-addr` in this case. To learn more, see the topic
+on how to [Use Docker for Mac or Docker for
+Windows](index.md#use-docker-for-mac-or-docker-for-windows) with Swarm.
+
     In the tutorial, the following command creates a swarm on the `manager1`
     machine:
 

docs/swarm/swarm-tutorial/index.md

@@ -27,7 +27,7 @@ This tutorial uses Docker Engine CLI commands entered on the command line of a
 terminal window. You should be able to install Docker on networked machines and
 be comfortable running commands in the shell of your choice.
 
-If you’re brand new to Docker, see [About Docker Engine](../../index.md).
+If you are brand new to Docker, see [About Docker Engine](../../index.md).
 
 ## Set up
 
@@ -48,37 +48,78 @@ provider. This tutorial uses the following machine names:
 * worker1
 * worker2
 
-###  Docker Engine 1.12 or later
+>**Note:** You can follow many of the tutorial steps to test single-node swarm
+as well, in which case you need only one host. Multi-node commands will not
+work, but you can initialize a swarm, create services, and scale them.
 
-To use swarm mode, you must [install Docker Engine](../../installation/index.md)
-on each one of the host machines. Alternatively, install the latest Docker for
-Mac or Docker for Windows.
+###  Docker Engine 1.12 or newer
 
->**Note**: Docker for Mac and Docker for Windows let you use single-node
-features of swarm mode, like creating a swarm and creating a service. Multi-node
-features like joining additional nodes and scaling a service are not available.
+This tutorial requires Docker Engine 1.12 or newer on each of the host machines.
+Install Docker Engine and verify that the Docker Engine daemon is running on
+each of the machines. You can get the latest version of Docker Engine as
+follows:
 
-Verify that the Docker Engine daemon is running on each of the machines.
+* [install Docker Engine on Linux machines](#install-docker-engine-on-linux-machines)
+
+* [use Docker for Mac or Docker for Windows](#use-docker-for-mac-or-docker-for-windows)
+
+#### Install Docker Engine on Linux machines
+
+If you are using Linux based physical computers or cloud-provided computers as
+hosts, simply follow the [Linux install
+instructions](../../installation/index.md) for your platform. Spin up the three
+machines, and you are ready. You can test both
+single-node and multi-node swarm scenarios on Linux machines.
+
+#### Use Docker for Mac or Docker for Windows
+
+Alternatively, install the latest [Docker for Mac](/docker-for-mac/index.md) or
+[Docker for Windows](/docker-for-windows/index.md) application on a one
+computer. You can test both single-node and multi-node swarm from this computer,
+but you will need to use Docker Machine to test the multi-node scenarios.
+
+* You can use Docker for Mac or Windows to test _single-node_ features of swarm
+mode, including initializing a swarm with a single node, creating services,
+and scaling services. Docker "Moby" on Hyperkit (Mac) or Hyper-V (Windows)
+will serve as the single swarm node.
+
+<br /><br />
+* Currently, you cannot use Docker for Mac or Windows alone to test a
+_multi-node_ swarm. However, you can use the included version of [Docker
+Machine](/machine/overview.md) to create the swarm nodes, then follow the
+tutorial for all multi-node features. For this scenario, you run commands from
+a Docker for Mac or Docker for Windows host, but that Docker host itself is
+_not_ participating in the swarm (i.e., it will not be `manager1`, `worker1`,
+or `worker2` in our example). After you create the nodes, you can run all
+swarm commands as shown from the Mac terminal or Windows PowerShell with
+Docker for Mac or Docker for Windows running.
 
 ### The IP address of the manager machine
 
-The IP address must be assigned to an a network interface available to the host
-operating system. All nodes in the swarm must be able to access the manager at the IP address.
+The IP address must be assigned to a network interface available to the host
+operating system. All nodes in the swarm must be able to access the manager at
+the IP address.
 
 Because other nodes contact the manager node on its IP address, you should use a
 fixed IP address.
 
->**Tip**: You can run `ifconfig` on Linux or Mac OS X to see a list of the
+You can run `ifconfig` on Linux or Mac OS X to see a list of the
 available network interfaces.
 
+If you are using Docker Machine, you can get the manager IP with either
+`docker-machine ls` or `docker-machine ip <MACHINE-NAME>` &#8212; for example,
+`docker-machine ip manager1`.
+
 The tutorial uses `manager1` : `192.168.99.100`.
 
 ### Open ports between the hosts
 
+The following ports must be available. On some systems, these ports are open by default.
+
 * **TCP port 2377** for cluster management communications
 * **TCP** and **UDP port 7946** for communication among nodes
 * **TCP** and **UDP port 4789** for overlay network traffic
 
 ## What's next?
 
-After you have set up your environment, you're ready to [create a swarm](create-swarm.md).
+After you have set up your environment, you are ready to [create a swarm](create-swarm.md).