added better what's next topics to point to new machine docs related to Issue #18282

updated cloud install example per Olivier's comments, added better command examples

updates per @thaJeztah comments

fixed links per @theJeztah comments, renamed cloud.md to overview.md for better URL name

updates per @moxiegirl comments, added alias for renamed file, modified links, changed a title

fixed link errors

Signed-off-by: Victoria Bialas <victoria.bialas@docker.com>

docs/installation/cloud/cloud-ex-aws.md

@@ -1,6 +1,6 @@
 <!--[metadata]>
 +++
-title = "Example: Manual install on a cloud provider"
+title = "Example: Manual install on cloud provider"
 description = "Example of a manual install of Docker Engine on a cloud provider, using Amazon Web Services (AWS) EC2. Shows how to create an EC2 instance, and install Docker Engine on it."
 keywords = ["cloud, docker, machine, documentation,  installation, AWS, EC2"]
 [menu.main]
@@ -8,7 +8,7 @@ parent = "install_cloud"
 +++
 <![end-metadata]-->
 
-# Example: Manual install on a cloud provider
+# Example: Manual install on cloud provider
 
 You can install Docker Engine directly to servers you have on cloud providers.  This example shows how to create an <a href="https://aws.amazon.com/" target="_blank"> Amazon Web Services (AWS)</a> EC2 instance, and install Docker Engine on it.
 
@@ -197,8 +197,12 @@ For Ubuntu Trusty (and some other versions), it’s recommended to install the `
 
 ## Where to go next
 
-* Would you like a quicker way to do Docker cloud installs? See [Digital Ocean Example: Use Docker Machine to provision Docker on cloud hosts](cloud-ex-aws.md).
+_Looking for a quicker way to do Docker cloud installs and provision multiple hosts?_ You can use [Docker Machine](https://docs.docker.com/machine/overview/) to provision hosts.
 
-* To learn more about options for installing Docker Engine on cloud providers, see [Understand cloud install options and choose one](cloud.md).
+  * [Use Docker Machine to provision hosts on cloud providers](https://docs.docker.com/machine/get-started-cloud/)
 
-* To get started with Docker, see <a href="https://docs.docker.com/engine/userguide/" target="_blank"> Docker User Guide </a>.
+  * [Docker Machine driver reference](https://docs.docker.com/machine/drivers/)
+
+*  [Install Docker Engine](../index.md)
+
+* [Docker User Guide](../../userguide/intro.md)

docs/installation/cloud/cloud-ex-machine-ocean.md

@@ -14,7 +14,7 @@ Docker Machine driver plugins are available for many cloud platforms, so you can
 
 You'll need to install and run Docker Machine, and create an account with the cloud provider.
 
-Then you provide account verification, security credentials, and configuration options for the providers as flags to `docker-machine create`. The flags are unique for each cloud-specific driver.  For instance, to pass a Digital Ocean access token you use the `--digitalocean-access-token` flag.
+Then you provide account verification, security credentials, and configuration options for the providers as flags to `docker-machine create`. The flags are unique for each cloud-specific driver.  For instance, to pass a Digital Ocean access token, you use the `--digitalocean-access-token` flag.
 
 As an example, let's take a look at how to create a Dockerized <a href="https://digitalocean.com" target="_blank">Digital Ocean</a> _Droplet_ (cloud server).
 
@@ -44,7 +44,7 @@ To generate your access token:
 
     This is the personal access token you'll use in the next step to create your cloud server.
 
-### Step 3. Start Docker Machine
+### Step 3. Install Docker Machine
 
 1. If you have not done so already, install Docker Machine on your local host.
 
@@ -56,30 +56,6 @@ To generate your access token:
 
 2. At a command terminal, use `docker-machine ls` to get a list of Docker Machines and their status.
 
-        $ docker-machine ls
-        NAME      ACTIVE   DRIVER       STATE     URL   SWARM
-        default   -        virtualbox   Stopped    
-
-3. If Machine is stopped, start it.
-
-        $ docker-machine start default
-        (default) OUT | Starting VM...
-        Started machines may have new IP addresses. You may need to re-run the `docker-machine env` command.
-
-4. Set environment variables to connect your shell to the local VM.
-
-        $ docker-machine env default
-        export DOCKER_TLS_VERIFY="1"
-        export DOCKER_HOST="tcp://xxx.xxx.xx.xxx:xxxx"
-        export  DOCKER_CERT_PATH="/Users/londoncalling/.docker/machine/machines/default"
-        export DOCKER_MACHINE_NAME="default"
-        # Run this command to configure your shell:
-        # eval "$(docker-machine env default)"
-
-        eval "$(docker-machine env default)"
-
-5. Re-run `docker-machine ls` to check that it's now running.
-
         $ docker-machine ls
         NAME      ACTIVE   DRIVER       STATE     URL                         SWARM
         default   *        virtualbox   Running   tcp:////xxx.xxx.xx.xxx:xxxx  
@@ -92,28 +68,15 @@ To generate your access token:
 
         Hello from Docker.
         This message shows that your installation appears to be working correctly.
+        ...
 
-        To generate this message, Docker took the following steps:
-        1. The Docker client contacted the Docker daemon.
-        2. The Docker daemon pulled the "hello-world" image from the Docker Hub.
-        3. The Docker daemon created a new container from that image which runs the executable that produces the output you are currently reading.
-        4. The Docker daemon streamed that output to the Docker client, which sent it to your terminal.
-
-        To try something more ambitious, you can run an Ubuntu container with:
-        $ docker run -it ubuntu bash
-
-        Share images, automate workflows, and more with a free Docker Hub account: https://hub.docker.com
-
-        For more examples and ideas, visit:
-        https://docs.docker.com/userguide/
-
-### Step 4. Use Docker Machine to Create the Droplet
+### Step 4. Use Machine to Create the Droplet
 
 1. Run `docker-machine create` with the `digitalocean` driver and pass your key to the `--digitalocean-access-token` flag, along with a name for the new cloud server.
 
     For this example, we'll call our new Droplet "docker-sandbox".
 
-        $ docker-machine create --driver digitalocean --digitalocean-access-token 455275108641c7716462d6f35d08b76b246b6b6151a816cf75de63c5ef918872 docker-sandbox
+        $ docker-machine create --driver digitalocean --digitalocean-access-token xxxxx docker-sandbox
         Running pre-create checks...
         Creating machine...
         (docker-sandbox) OUT | Creating SSH key...
@@ -163,45 +126,52 @@ To generate your access token:
         default          -        virtualbox     Running   tcp://192.168.99.100:2376   
         docker-sandbox   *        digitalocean   Running   tcp://45.55.222.72:2376     
 
-6. Log in to the Droplet with the `docker-machine ssh` command.
-
-        $ docker-machine ssh docker-sandbox
-        Welcome to Ubuntu 14.04.3 LTS (GNU/Linux 3.13.0-71-generic x86_64)
+6. Run some `docker-machine` commands to inspect the remote host. For example, `docker-machine ip <machine>` gets the host IP adddress and `docker-machine inspect <machine>` lists all the details.
 
-        * Documentation:  https://help.ubuntu.com/
+        $ docker-machine ip docker-sandbox
+        104.131.43.236
 
-        System information as of Mon Dec 21 21:38:53 EST 2015
+        $ docker-machine inspect docker-sandbox
+        {
+            "ConfigVersion": 3,
+            "Driver": {
+            "IPAddress": "104.131.43.236",
+            "MachineName": "docker-sandbox",
+            "SSHUser": "root",
+            "SSHPort": 22,
+            "SSHKeyPath": "/Users/samanthastevens/.docker/machine/machines/docker-sandbox/id_rsa",
+            "StorePath": "/Users/samanthastevens/.docker/machine",
+            "SwarmMaster": false,
+            "SwarmHost": "tcp://0.0.0.0:3376",
+            "SwarmDiscovery": "",
+            ...
 
-        System load:  0.77               Processes:              70
-        Usage of /:   11.4% of 19.56GB   Users logged in:        0
-        Memory usage: 15%                IP address for eth0:    45.55.139.48
-        Swap usage:   0%                 IP address for docker0: 172.17.0.1
+7. Verify Docker Engine is installed correctly by running `docker` commands.
 
-        Graph this data and manage this system at:
-        https://landscape.canonical.com/
+    Start with something basic like `docker run hello-world`, or for a more interesting test, run a Dockerized webserver on your new remote machine.
 
-7. Verify Docker Engine is installed correctly by running `docker run hello-world`.
+    In this example, the `-p` option is used to expose port 80 from the `nginx` container and make it accessible on port `8000` of the `docker-sandbox` host.
 
-          ubuntu@ip-172-31-0-151:~$ sudo docker run hello-world
-          Unable to find image 'hello-world:latest' locally
-          latest: Pulling from library/hello-world
-          b901d36b6f2f: Pull complete
-          0a6ba66e537a: Pull complete
-          Digest: sha256:8be990ef2aeb16dbcb9271ddfe2610fa6658d13f6dfb8bc72074cc1ca36966a7
-          Status: Downloaded newer image for hello-world:latest
+        $ docker run -d -p 8000:80 --name webserver kitematic/hello-world-nginx
+        Unable to find image 'kitematic/hello-world-nginx:latest' locally
+        latest: Pulling from kitematic/hello-world-nginx
+        a285d7f063ea: Pull complete
+        2d7baf27389b: Pull complete
+        ...
+        Digest: sha256:ec0ca6dcb034916784c988b4f2432716e2e92b995ac606e080c7a54b52b87066
+        Status: Downloaded newer image for kitematic/hello-world-nginx:latest
+        942dfb4a0eaae75bf26c9785ade4ff47ceb2ec2a152be82b9d7960e8b5777e65
 
-          Hello from Docker.
-          This message shows that your installation appears to be working correctly.
-          . . .
+    In a web browser, go to `http://<host_ip>:8000` to bring up the webserver home page. You got the `<host_ip>` from the output of the `docker-machine ip <machine>` command you ran in a previous step. Use the port you exposed in the `docker run` command.
 
-      You can type keyboard command Control-D or `exit` to log out of the remote server.
+    ![nginx webserver](../images/nginx-webserver.png)
 
 #### Understand the defaults and options on the create command
 
 For convenience, `docker-machine` will use sensible defaults for choosing settings such as the image that the server is based on, but you override the defaults using the respective flags (e.g. `--digitalocean-image`). This is useful if, for example, you want to create a cloud server with a lot of memory and CPUs (by default `docker-machine` creates a small server). For a full list of the flags/settings available and their defaults, see the output of `docker-machine create -h` at the command line. See also <a href="https://docs.docker.com/machine/drivers/os-base/" target="_blank">Driver options and operating system defaults</a> and information about the <a href="https://docs.docker.com/machine/reference/create/" target="_blank">create</a> command in the Docker Machine documentation.
 
 
-### Step 5. Use Docker Machine to remove the Droplet
+### Step 5. Use Machine to remove the Droplet
 
 To remove a host and all of its containers and images, first stop the machine, then use `docker-machine rm`:
 
@@ -220,8 +190,12 @@ If you create a host with Docker Machine, but remove it through the cloud provid
 
 ## Where to go next
 
-* To learn more about options for installing Docker Engine on cloud providers, see [Understand cloud install options and choose one](cloud.md).
+* [Docker Machine driver reference](https://docs.docker.com/machine/drivers/)
+
+* [Docker Machine Overview](https://docs.docker.com/machine/overview/)
+
+* [Use Docker Machine to provision hosts on cloud providers](https://docs.docker.com/machine/get-started-cloud/)
 
-* To learn more about using Docker Machine to provision cloud hosts, see <a href="https://docs.docker.com/machine/get-started-cloud/" target="_blank">Using Docker Machine with a cloud provider</a>.
+*  [Install Docker Engine](../../installation/index.md)
 
-* To get started with Docker, see <a href="https://docs.docker.com/engine/userguide/" target="_blank"> Docker User Guide</a>.
+* [Docker User Guide](../../userguide/intro.md)

docs/installation/cloud/index.md

@@ -8,7 +8,7 @@ aliases = [
   "/engine/installation/rackspace/",
   "/engine/installation/joyent/"
 ]
-title = "In the cloud"
+title = "On cloud providers"
 description = "Cloud Installations"
 keywords = ["Docker install "]
 [menu.main]
@@ -20,6 +20,6 @@ weight="-60"
 
 # Install Engine in the cloud
 
-* [Understand cloud install options and choose one](cloud.md)
-* [Example: Use Docker Machine to provision cloud hosts](cloud-ex-machine-ocean.md)
+* [Understand cloud install options and choose one](overview.md)
+* [Example: Use Machine to provision cloud hosts](cloud-ex-machine-ocean.md)
 * [Example: Manual install on a cloud provider](cloud-ex-aws.md)

docs/installation/cloud/cloud.md → docs/installation/cloud/overview.md

@@ -1,5 +1,8 @@
 <!--[metadata]>
 +++
+aliases = [
+  "/engine/installation/cloud/cloud/",
+]
 title = "Choose how to install"
 description = "Installation instructions for Docker on cloud."
 keywords = ["cloud, docker, machine, documentation,  installation"]
@@ -9,7 +12,7 @@ weight=-3
 +++
 <![end-metadata]-->
 
-# Understand cloud install options and choose one
+# Choose how to install
 
 You can install Docker Engine on any cloud platform that runs an operating system (OS) that Docker supports. This includes many flavors and versions of Linux, along with Mac and Windows.
 
@@ -26,11 +29,11 @@ To install on a cloud provider:
 
 2. Decide which OS you want to run on the cloud host.
 
-3. Understand the Docker prerequisites and install process for the chosen OS. See [Install Docker Engine](index.md) for a list of supported systems and links to the install guides.
+3. Understand the Docker prerequisites and install process for the chosen OS. See [Install Docker Engine](../index.md) for a list of supported systems and links to the install guides.
 
 4. Create a host with a Docker supported OS, and install Docker per the instructions for that OS.
 
-[Example: Manual install on a cloud provider](cloud-ex-aws.md) shows how to create an <a href="https://aws.amazon.com/" target="_blank"> Amazon Web Services (AWS)</a> EC2 instance, and install Docker Engine on it.
+[Example (AWS): Manual install on a cloud provider](cloud-ex-aws.md) shows how to create an <a href="https://aws.amazon.com/" target="_blank"> Amazon Web Services (AWS)</a> EC2 instance, and install Docker Engine on it.
 
 
 ## Use Docker Machine to provision cloud hosts
@@ -41,13 +44,13 @@ With Docker Machine, you can use the same interface to create cloud hosts with D
 
 To do this, you use the `docker-machine create` command with the driver for the cloud provider, and provider-specific flags for account verification, security credentials, and other configuration details.
 
-[Example: Use Docker Machine to provision cloud hosts](cloud-ex-machine-ocean.md) walks you through the steps to set up Docker Machine and provision a Dockerized host on [Digital Ocean](https://www.digitalocean.com/).
+[Example: Use Docker Machine to provision cloud hosts](cloud-ex-machine-ocean.md) walks you through the steps to set up Docker Machine and provision a Dockerized host on <a href="https://www.digitalocean.com/" target="_blank">Digital Ocean</a>).
 
 ## Where to go next
 * [Example: Manual install on a cloud provider](cloud-ex-aws.md) (AWS EC2)
 
 * [Example: Use Docker Machine to provision cloud hosts](cloud-ex-machine-ocean.md) (Digital Ocean)
 
-* [Using Docker Machine with a cloud provider](https://docs.docker.com/machine/get-started-cloud/)
+* For supported platforms, see [Install Docker Engine](../index.md).
 
-* <a href="https://docs.docker.com/engine/userguide/" target="_blank"> Docker User Guide </a> (after your install is complete, get started using Docker)
+* To get started with Docker post-install, see [Docker User Guide](../../userguide/intro.md).

docs/installation/index.md

@@ -30,7 +30,7 @@ Docker Engine is supported on Linux, Cloud, Windows, and OS X. Installation inst
 If your linux distribution is not listed above, don't give up yet. To try out Docker on a distribution that is not listed above, go here: [Installation from binaries](binaries.md).
 
 ## On Cloud
-* [Choose how to Install](cloud/cloud.md)
+* [Choose how to Install](cloud/overview.md)
 * [Example: Manual install on a cloud provider](cloud/cloud-ex-aws.md)
 * [Example: Use Docker Machine to provision cloud hosts](cloud/cloud-ex-machine-ocean.md)