Merge pull request #14565 from moxiegirl/14561-mac-rewrite

Docker Toolbox Updates fixes #14561

docs/installation/mac.md

@@ -10,37 +10,34 @@ parent = "smn_engine"
 
 # Mac OS X
 
-You can install Docker using Boot2Docker to run `docker` commands at your command-line.
-Choose this installation if you are familiar with the command-line or plan to
-contribute to the Docker project on GitHub.
+> **Note**: This release of Docker deprecates the Boot2Docker command line in
+> favor of Docker Machine.  Use the Docker Toolbox to install Docker Machine as
+> well as the other Docker tools.
 
-[<img src="/installation/images/kitematic.png" alt="Download Kitematic"
-style="float:right;">](https://kitematic.com/download)
+You install Docker using Docker Toolbox. Docker Toolbox includes the following Docker tools:
 
-Alternatively, you may want to try <a id="inlinelink" href="https://kitematic.com/"
-target="_blank">Kitematic</a>, an application that lets you set up Docker and
-run containers using a graphical user interface (GUI).
-
-## Command-line Docker with Boot2Docker
+* Docker Machine for running the `docker-machine` binary
+* Docker Engine for running the `docker` binary
+* Docker Compose for running the `docker-compose` binary
+* Kitematic, the Docker GUI
+* a shell preconfigured for a Docker command-line environment
+* Oracle VM VirtualBox 
 
 Because the Docker daemon uses Linux-specific kernel features, you can't run
-Docker natively in OS X. Instead, you must install the Boot2Docker application.
-The application includes a VirtualBox Virtual Machine (VM), Docker itself, and the
-Boot2Docker management tool.
-
-The Boot2Docker management tool is a lightweight Linux virtual machine made
-specifically to run the Docker daemon on Mac OS X. The VirtualBox VM runs
-completely from RAM, is a small ~24MB download, and boots in approximately 5s.
+Docker natively in OS X. Instead, you must use `docker-machine` to create and
+attach to a virtual machine (VM). This machine is a Linux VM that hosts Docker
+for you on your Mac.
 
 **Requirements**
 
-Your Mac must be running OS X 10.6 "Snow Leopard" or newer to run Boot2Docker.
+Your Mac must be running OS X 10.8 "Mountain Lion" or newer to install the
+Docker Toolbox.
 
 ### Learn the key concepts before installing
 
-In a Docker installation on Linux, your machine is both the localhost and the
-Docker host. In networking, localhost means your computer. The Docker host is
-the machine on which the containers run.
+In a Docker installation on Linux, your physical machine is both the localhost
+and the Docker host. In networking, localhost means your computer. The Docker
+host is the computer on which the containers run.
 
 On a typical Linux installation, the Docker client, the Docker daemon, and any
 containers run directly on your localhost. This means you can address ports on a
@@ -49,135 +46,229 @@ Docker container using standard localhost addressing such as `localhost:8000` or
 
 ![Linux Architecture Diagram](/installation/images/linux_docker_host.svg)
 
-In an OS X installation, the `docker` daemon is running inside a Linux virtual
-machine provided by Boot2Docker.
+In an OS X installation, the `docker` daemon is running inside a Linux VM called
+`docker-vm`. The `docker-vm` is a lightweight Linux VM made specifically to run
+the Docker daemon on Mac OS X. The VM runs completely from RAM, is a small ~24MB
+download, and boots in approximately 5s.
 
 ![OSX Architecture Diagram](/installation/images/mac_docker_host.svg)
 
-In OS X, the Docker host address is the address of the Linux VM.
-When you start the `boot2docker` process, the VM is assigned an IP address. Under
-`boot2docker` ports on a container map to ports on the VM. To see this in
+In OS X, the Docker host address is the address of the Linux VM. When you start
+the VM with `docker-machine` it is assigned an IP address. When you start a
+container, the ports on a container map to ports on the VM. To see this in
 practice, work through the exercises on this page.
 
 
 ### Installation
 
-1. Go to the [boot2docker/osx-installer ](
-   https://github.com/boot2docker/osx-installer/releases/latest) release page.
-
-4. Download Boot2Docker by clicking `Boot2Docker-x.x.x.pkg` in the "Downloads"
-   section.
-
-3. Install Boot2Docker by double-clicking the package.
-
-    The installer places Boot2Docker and VirtualBox in your "Applications" folder.
-
-The installation places the `docker` and `boot2docker` binaries in your
-`/usr/local/bin` directory.
-
-
-## Start the Boot2Docker Application
-
-To run a Docker container, you first start the `boot2docker` VM and then issue
-`docker` commands to create, load, and manage containers. You can launch
-`boot2docker` from your Applications folder or from the command line.
+If you have VirtualBox running, you must shut it down before running the
+installer. 
 
-> **NOTE**: Boot2Docker is designed as a development tool. You should not use
->  it in production environments.
+1. Go to the [Docker Toolbox](https://www.docker.com/toolbox) page.
 
-### From the Applications folder
+2. Click the installer link to download.
 
-When you launch the "Boot2Docker" application from your "Applications" folder, the
-application:
+3. Install Docker Toolbox by double-clicking the package or by right-clicking
+and choosing "Open" from the pop-up menu.
 
-* opens a terminal window
+    The installer launches the "Install Docker Toolbox" dialog.
+    
+    ![Install Docker Toolbox](/installation/images/mac-welcome-page.png)
 
-* creates a $HOME/.boot2docker directory
+4. Press "Continue" to install the toolbox.
 
-* creates a VirtualBox ISO and certs
+    The installer presents you with options to customize the standard
+    installation. 
+  
+    ![Standard install](/installation/images/mac-page-two.png)
+  
+    By default, the standard Docker Toolbox installation:
+  
+    * installs binaries for the Docker tools in `/usr/local/bin` 
+    * makes these binaries available to all users 
+    * updates any existing VirtualBox installation 
+  
+    Change these defaults by pressing "Customize" or "Change
+    Install Location."  
 
-* starts a VirtualBox VM running the `docker` daemon
+5. Press "Install" to perform the standard installation.
 
-Once the launch completes, you can run `docker` commands. A good way to verify
-your setup succeeded is to run the `hello-world` container.
+     The system prompts you for your password.
+   
+     ![Password prompt](/installation/images/mac-password-prompt.png)
+   
+6. Provide your password to continue with the installation.
 
-    $ docker run hello-world
-    Unable to find image 'hello-world:latest' locally
-    511136ea3c5a: Pull complete
-    31cbccb51277: Pull complete
-    e45a5af57b00: Pull complete
-    hello-world:latest: The image you are pulling has been verified.
-    Important: image verification is a tech preview feature and should not be
-    relied on to provide security.
-    Status: Downloaded newer image for hello-world:latest
-    Hello from Docker.
-    This message shows that your installation appears to be working correctly.
+     When it completes, the installer provides you with some information you can
+     use to complete some common tasks.
+   
+     ![All finished](/installation/images/mac-page-finished.png)
+   
+7. Press "Close" to exit.
 
-    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.
-       (Assuming it was not already locally available.)
-    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
+## Running a Docker Container
 
-    For more examples and ideas, visit:
-    http://docs.docker.com/userguide/
+To run a Docker container, you:
 
+* create a new (or start an existing) Docker virtual machine 
+* switch your environment to your new VM
+* use the `docker` client to create, load, and manage containers
 
-A more typical way to start and stop `boot2docker` is using the command line.
+Once you create a machine, you can reuse it as often as you like. Like any
+VirtualBox VM, it maintains its configuration between uses.
 
-### From your command line
+There are two ways to use the installed tools, from the Docker Quickstart Terminal or
+[from your shell](#from-your-shell).
 
-Initialize and run `boot2docker` from the command line, do the following:
+### From the Docker Quickstart Terminal
 
-1. Create a new Boot2Docker VM.
+1. Open the "Applications" folder or the "Launchpad".
 
-        $ boot2docker init
+2. Find the Docker Quickstart Terminal  and double-click to launch it.
 
-    This creates a new virtual machine. You only need to run this command once.
+    The application:
 
-2. Start the `boot2docker` VM.
+    * opens a terminal window
+    * creates a VM called `docker-vm` if it doesn't exists, starts the VM if it does
+    * points the terminal environment to this VM
 
-        $ boot2docker start
+    Once the launch completes, the Docker Quickstart Terminal reports:
+    
+     ![All finished](/installation/images/mac-success.png)
+     
+    Now, you can run `docker` commands. 
 
-3. Display the environment variables for the Docker client.
+3. Verify your setup succeeded by running the `hello-world` container.
 
-        $ boot2docker shellinit
-        Writing /Users/mary/.boot2docker/certs/boot2docker-vm/ca.pem
-        Writing /Users/mary/.boot2docker/certs/boot2docker-vm/cert.pem
-        Writing /Users/mary/.boot2docker/certs/boot2docker-vm/key.pem
-            export DOCKER_HOST=tcp://192.168.59.103:2376
-            export DOCKER_CERT_PATH=/Users/mary/.boot2docker/certs/boot2docker-vm
-            export DOCKER_TLS_VERIFY=1
-
-    The specific paths and address on your machine will be different.
-
-4. To set the environment variables in your shell do the following:
-
-        $ eval "$(boot2docker shellinit)"
-
-    You can also set them manually by using the `export` commands `boot2docker`
-    returns.
+        $ docker run hello-world
+        Unable to find image 'hello-world:latest' locally
+        511136ea3c5a: Pull complete
+        31cbccb51277: Pull complete
+        e45a5af57b00: Pull complete
+        hello-world:latest: The image you are pulling has been verified.
+        Important: image verification is a tech preview feature and should not be
+        relied on to provide security.
+        Status: Downloaded newer image for hello-world:latest
+        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.
+           (Assuming it was not already locally available.)
+        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
+
+        For more examples and ideas, visit:
+        http://docs.docker.com/userguide/
+
+
+A more typical way to interact with the Docker tools is from your regular shell command line.
+
+### From your shell
+
+This section assumes you are running a Bash shell. You may be running a
+different shell such as C Shell but the commands are the same.
+
+1. Create a new Docker VM.
+
+        $ docker-machine create --driver virtualbox docker-vm
+        Creating VirtualBox VM...
+        Creating SSH key...
+        Starting VirtualBox VM...
+        Starting VM...
+        To see how to connect Docker to this machine, run: docker-machine env docker-vm
+
+    This creates a new `docker-vm` in VirtualBox.
+    
+    ![docker-vm](/installation/images/docker-vm.png)
+
+    The command also creates a machine configuration in the
+    `~/.docker/machine/machines/docker-vm` directory. You only need to run the
+    `create` command once. Then, you can use `docker-machine` to start, stop,
+    query, and otherwise manage the VM from the command line.
+    
+2. List your available machines.
+
+        $ docker-machine ls
+        NAME                ACTIVE   DRIVER       STATE     URL                         SWARM
+        docker-vm        *        virtualbox   Running   tcp://192.168.99.101:2376  
+        
+    If you have previously installed the deprecated Boot2Docker application or
+    run the Docker Quickstart Terminal, you may have a `dev` VM as well.  When you
+    created `docker-vm`, the `docker-machine` command provided instructions
+    for learning how to connect the VM.
+
+3. Get the environment commands for your new VM.
+
+        $ docker-machine env docker-vm
+        export DOCKER_TLS_VERIFY="1"
+        export DOCKER_HOST="tcp://192.168.99.101:2376"
+        export DOCKER_CERT_PATH="/Users/mary/.docker/machine/machines/docker-vm"
+        export DOCKER_MACHINE_NAME="docker-vm"
+        # Run this command to configure your shell: 
+        # eval "$(docker-machine env docker-vm)"
+    
+4. Connect your shell to the `docker-vm` machine.
+
+        $ eval "$(docker-machine env docker-vm)"
 
 5. Run the `hello-world` container to verify your setup.
 
         $ docker run hello-world
 
 
-## Basic Boot2Docker exercises
-
-At this point, you should have `boot2docker` running and the `docker` client
-environment initialized. To verify this, run the following commands:
-
-    $ boot2docker status
-    $ docker version
-
-Work through this section to try some practical container tasks using `boot2docker` VM.
+## Learn about your Toolbox installation
+
+Toolbox installs the Docker Engine binary, the Docker binary on your system. When you
+use the Docker Quickstart Terminal or create a `docker-vm` manually, Docker
+Machine updates the `~/.docker/machine/machines/docker-vm` folder to your
+system. This folder contains the configuration for the VM.
+
+You can create multiple VMs on your system with Docker Machine. So, you may have
+more than one VM folder if you have more than one VM. To remove a VM, use the
+`docker-machine rm <machine-name>` command.
+      
+The `docker-machine` subcommands are slightly different than the `boot2docker`
+subcommands. The table below lists the equivalent `docker-machine` subcommand
+and what it does:
+
+|  `boot2docker` | `docker-machine` | `docker-machine` description                             |
+|----------------|------------------|----------------------------------------------------------|
+| init           | create           | Creates a new docker host.                               |
+| up             | start            | Starts a stopped machine.                                |
+| ssh            | ssh              | Runs a command or interactive ssh session on the machine.|
+| save           | -                | Not applicable.                                          |
+| down           | stop             | Stops a running machine.                                 |
+| poweroff       | stop             | Stops a running machine.                                 |
+| reset          | restart          | Restarts a running machine.                              |
+| config         | inspect          | Prints machine configuration details.                    |
+| status         | ls               | Lists all machines and their status.                     |
+| info           | inspect          | Displays a machine's details.                            |
+| ip             | ip               | Displays the machine's ip address.                       |
+| shellinit      | env              | Displays shell commands needed to configure your shell to interact with a machine |
+| delete         | rm               | Removes a machine.                                       |
+| download       | -                | Not applicable.                                          |
+| upgrade        | upgrade          | Upgrades a machine's Docker client to the latest stable release. |
+
+
+## Example of Docker on Mac OS X
+
+Work through this section to try some practical container tasks on a VM. At this
+point, you should have a VM running and be connected to it through your shell.
+To verify this, run the following commands:
+
+    $ docker-machine ls
+    NAME                ACTIVE   DRIVER       STATE     URL                         SWARM
+    dev                 *        virtualbox   Running   tcp://192.168.99.100:2376   
+
+The `ACTIVE` machine, in this case `dev`, is the one your environment is pointing to.
 
 ### Access container ports
 
@@ -212,11 +303,11 @@ Work through this section to try some practical container tasks using `boot2dock
 
     This didn't work. The reason it doesn't work is your `DOCKER_HOST` address is
     not the localhost address (0.0.0.0) but is instead the address of the
-    `boot2docker` VM.
+    your Docker VM.
 
-5. Get the address of the `boot2docker` VM.
+5. Get the address of the `dev` VM.
 
-        $ boot2docker ip
+        $ docker-machine ip dev
         192.168.59.103
 
 6. Enter the `http://192.168.59.103:49157` address in your browser:
@@ -232,7 +323,7 @@ Work through this section to try some practical container tasks using `boot2dock
 
 ### Mount a volume on the container
 
-When you start `boot2docker`, it automatically shares your `/Users` directory
+When you start a container it automatically shares your `/Users/username` directory
 with the VM. You can use this share point to mount directories onto your container.
 The next exercise demonstrates how to do this.
 
@@ -274,85 +365,53 @@ The next exercise demonstrates how to do this.
 
     ![Cool page](/installation/images/cool_view.png)
 
-9. Stop and then remove your running `mysite` container.
+10. Stop and then remove your running `mysite` container.
 
         $ docker stop mysite
         $ docker rm mysite
 
-## Upgrade Boot2Docker
-
-If you running Boot2Docker 1.4.1 or greater, you can upgrade Boot2Docker from
-the command line. If you are running an older version, you should use the
-package provided by the `boot2docker` repository.
-
-### From the command line
-
-To upgrade from 1.4.1 or greater, you can do this:
-
-1. Open a terminal on your local machine.
-
-2. Stop the `boot2docker` application.
-
-        $ boot2docker stop
-
-3. Run the upgrade command.
-
-        $ boot2docker upgrade
-
-
-### Use the installer
-
-To upgrade any version of Boot2Docker, do this:
-
-1. Open a terminal on your local machine.
-
-2. Stop the `boot2docker` application.
-
-        $ boot2docker stop
-
-3. Go to the [boot2docker/osx-installer ](
-   https://github.com/boot2docker/osx-installer/releases/latest) release page.
-
-4. Download Boot2Docker by clicking `Boot2Docker-x.x.x.pkg` in the "Downloads"
-   section.
-
-2. Install Boot2Docker by double-clicking the package.
-
-    The installer places Boot2Docker in your "Applications" folder.
-
 
-## Uninstallation 
+## Upgrade Docker Toolbox
 
-1. Go to the [boot2docker/osx-installer ](
-   https://github.com/boot2docker/osx-installer/releases/latest) release page. 
+To upgrade Docker Toolbox, download an re-run [the Docker Toolbox
+installer](https://docker.com/toolbox/).
 
-2. Download the source code by clicking `Source code (zip)` or
-   `Source code (tar.gz)` in the "Downloads" section.
 
-3. Extract the source code.
+## Uninstall Docker Toolbox 
 
-4. Open a terminal on your local machine.
+To uninstall, do the following:
 
-5. Change to the directory where you extracted the source code:
+1. List your machines.
 
-        $ cd <path to extracted source code>
+        $ docker-machine ls
+        NAME                ACTIVE   DRIVER       STATE     URL                         SWARM
+        dev                 *        virtualbox   Running   tcp://192.168.99.100:2376   
+        my-docker-machine            virtualbox   Stopped                               
+        docker-vm                 virtualbox   Stopped  
 
-6. Make sure the uninstall.sh script is executable:
+2. Remove each machine.
 
-        $ chmod +x uninstall.sh
+        $ docker-machine rm dev
+        Successfully removed dev
+    
+     Removing a machine deletes its VM from VirtualBox and from the
+     `~/.docker/machine/machines` directory.
 
-7. Run the uninstall.sh script:
+3. Remove the Docker Quickstart Terminal and Kitematic from your "Applications" folder.
 
-        $ ./uninstall.sh
+4. Remove the `docker`, `docker-compose`, and `docker-machine` commands from the `/usr/local/bin` folder.
 
+        $ rm /usr/local/bin/docker
+      
+5. Delete the `~/.docker` folder from your system.
 
-## Learning more and acknowledgement
 
-Use `boot2docker help` to list the full command line reference. For more
-information about using SSH or SCP to access the Boot2Docker VM, see the README
-at  [Boot2Docker repository](https://github.com/boot2docker/boot2docker).
+## Learning more 
 
-Thanks to Chris Jones whose [blog](http://viget.com/extend/how-to-use-docker-on-os-x-the-missing-guide)  
-inspired me to redo this page.
+Use `docker-machine help` to list the full command line reference for Docker Machine. For more
+information about using SSH or SCP to access a VM, see [the Docker Machine
+documentation](https://docs.docker.com/machine/).
 
-Continue with the [Docker User Guide](/userguide).
+You can continue with the [Docker User Guide](/userguide). If you are
+interested in using the Kitematic GUI, see the [Kitermatic user
+guide](/kitematic/userguide/).

docs/installation/windows.md

@@ -9,122 +9,309 @@ parent = "smn_engine"
 <![end-metadata]-->
 
 # Windows
-> **Note:**
-> Docker has been tested on Windows 7 and 8.1; it may also run on older versions.
-> Your processor needs to support hardware virtualization.
 
-The Docker Engine uses Linux-specific kernel features, so to run it on Windows
-we need to use a lightweight virtual machine (VM).  You use the **Windows Docker
-Client** to control the virtualized Docker Engine to build, run, and manage
-Docker containers.
+> **Note**: This release of Docker deprecates the Boot2Docker command line in
+> favor of Docker Machine.  Use the Docker Toolbox to install Docker Machine as
+> well as the other Docker tools.
 
-To make this process easier, we've designed a helper application called
-[Boot2Docker](https://github.com/boot2docker/boot2docker) which creates a Linux virtual
-machine on Windows to run Docker on a Linux operating system.
+You install Docker using Docker Toolbox. Docker Toolbox includes the following Docker tools:
 
-Although you will be using Windows Docker client, the docker engine hosting the
-containers will still be running on Linux. Until the Docker engine for Windows
-is developed, you can launch only Linux containers from your Windows machine.
+* Docker Machine for running the `docker-machine` binary
+* Docker Engine for running the `docker` binary
+* Kitematic, the Docker GUI
+* a shell preconfigured for a Docker command-line environment
+* Oracle VM VirtualBox 
+
+Because the Docker daemon uses Linux-specific kernel features, you can't run
+Docker natively in Windows. Instead, you must use `docker-machine` to create and attach to a Docker VM on your machine. This VM hosts Docker for you on your Windows system.
+
+The Docker VM is lightweight Linux virtual machine made specifically to run the
+Docker daemon on Windows. The VirtualBox VM runs completely from RAM, is a
+small ~24MB download, and boots in approximately 5s.
+
+
+
+## Requirements
+
+Your machine must be running Windows 7.1, 8/8.1 or newer to run Docker. 
+To find out what version of Windows you have:
+
+1. Right click the Windows message and choose **System**. 
+
+    ![Which version](/installation/images/win_ver.png)
+    
+    If you aren't using a supported version, you could consider upgrading your
+    operating system.
+
+2. Make sure your Windows system supports Hardware Virtualization Technology and that virtualization is enabled.
+
+    #### For Windows 8 or 8.1
+
+	  Choose **Start > Task Manager** and navigate to the **Performance** tab.          
+	  Under **CPU** you should see the following:
+
+      ![Release page](/installation/images/virtualization.png)
+    
+    If virtualization is not enabled on your system, follow the manufacturer's instructions for enabling it.
+    
+    ### For Windows 7 
+    
+	  Run the <a
+	  href="http://www.microsoft.com/en-us/download/details.aspx?id=592"
+	  target="_blank"> Microsoft® Hardware-Assisted Virtualization Detection
+	  Tool</a> and follow the on-screen instructions.
+
+
+> **Note**: If you have Docker hosts running and you don't wish to do a Docker Toolbox
+installation, you can install the `docker.exe` using the *unofficial* Windows package
+manager Chocolately. For information on how to do this, see [Docker package on
+Chocolatey](http://chocolatey.org/packages/docker).
+
+### Learn the key concepts before installing
+
+In a Docker installation on Linux, your machine is both the localhost and the
+Docker host. In networking, localhost means your computer. The Docker host is
+the machine on which the containers run.
+
+On a typical Linux installation, the Docker client, the Docker daemon, and any
+containers run directly on your localhost. This means you can address ports on a
+Docker container using standard localhost addressing such as `localhost:8000` or
+`0.0.0.0:8376`.
+
+![Linux Architecture Diagram](/installation/images/linux_docker_host.svg)
+
+In an Windows installation, the `docker` daemon is running inside a Linux virtual
+machine. You use the Windows Docker client to talk to the Docker host VM. Your
+Docker containers run inside this host. 
 
 ![Windows Architecture Diagram](/installation/images/win_docker_host.svg)
 
-## Demonstration
+In Windows, the Docker host address is the address of the Linux VM. When you
+start the VM with `docker-machine` it is assigned an IP address. When you start
+a container, the ports on a container map to ports on the VM. To see this in
+practice, work through the exercises on this page.
+
+
+### Installation
+
+If you have VirtualBox running, you must shut it down before running the
+installer. 
+
+1. Go to the [Docker Toolbox](https://www.docker.com/toolbox) page.
+
+2. Click the installer link to download.
+
+3. Install Docker Toolbox by double-clicking the installer.
 
-<iframe width="640" height="480" src="//www.youtube.com/embed/TjMU3bDX4vo?rel=0" frameborder="0" allowfullscreen></iframe>
+    The installer launches the "Setup - Docker Toolbox" dialog.
+    
+    ![Install Docker Toolbox](/installation/images/win-welcome.png)
 
-## Installation
+4. Press "Next" to install the toolbox.
 
-1. Download the latest release of the
-   [Docker for Windows Installer](https://github.com/boot2docker/windows-installer/releases/latest).
-2. Run the installer, which will install Docker Client for Windows, VirtualBox,
-   Git for Windows (MSYS-git), the boot2docker Linux ISO, and the Boot2Docker
-   management tool.
-   ![](/installation/images/windows-installer.png)
-3. Run the **Boot2Docker Start** shortcut from your Desktop or “Program Files →
-   Boot2Docker for Windows”.
-   The Start script will ask you to enter an ssh key passphrase - the simplest
-   (but least secure) is to just hit [Enter].
+    The installer presents you with options to customize the standard
+    installation. By default, the standard Docker Toolbox installation:
+  
+    * installs executables for the Docker tools in `C:\Program Files\Docker Toolbox` 
+    * updates any existing VirtualBox installation 
+    * adds a Docker Inc. folder to your program shortcuts
+    * updates your `PATH` environment variable
+    * adds desktop icons for the Docker Quickstart Terminal and Kitematic
 
-4. The **Boot2Docker Start** will start a unix shell already configured to manage
-   Docker running inside the virtual machine. Run `docker version` to see
-   if it is working correctly:
+    This installation assumes the defaults are acceptable.
 
-![](/installation/images/windows-boot2docker-start.png)
+5. Press "Next" until you reach the "Ready to Install" page.
 
-## Running Docker
+     The system prompts you for your password.
+   
+     ![Install](/installation/images/win-page-6.png)
+     
+6. Press "Install"  to continue with the installation.
 
-> **Note:** if you are using a remote Docker daemon, such as Boot2Docker, 
-> then _do not_ type the `sudo` before the `docker` commands shown in the
-> documentation's examples.
+     When it completes, the installer provides you with some information you can
+     use to complete some common tasks.
+   
+     ![All finished](/installation/images/windows-finish.png)
+   
+7. Press "Close" to exit.
 
-**Boot2Docker Start** will automatically start a shell with environment variables
-correctly set so you can start using Docker right away:
 
-Let's try the `hello-world` example image. Run
+## Running a Docker Container
 
-    $ docker run hello-world
+To run a Docker container, you:
+
+* create a new (or start an existing) Docker virtual machine 
+* switch your environment to your new VM
+* use the `docker` client to create, load, and manage containers
+
+Once you create a machine, you can reuse it as often as you like. Like any
+VirtualBox VM, it maintains its configuration between uses.
+
+There are several ways to use the installed tools, from the Docker Quickstart Terminal or
+[from your shell](#from-your-shell).
+
+### From the Docker Quickstart Terminal
+
+1. Find the Docker Quickstart Terminal icon on your Desktop and double-click to launch it.
+
+    The application:
+
+    * opens a terminal window
+    * creates a `docker-vm` if it doesn't exist, starts the VM if it does
+    * points the terminal environment to this VM
+
+    Once the launch completes, you can run `docker` commands. 
+
+3. Verify your setup succeeded by running the `hello-world` container.
+
+        $ docker run hello-world
+        Unable to find image 'hello-world:latest' locally
+        511136ea3c5a: Pull complete
+        31cbccb51277: Pull complete
+        e45a5af57b00: Pull complete
+        hello-world:latest: The image you are pulling has been verified.
+        Important: image verification is a tech preview feature and should not be
+        relied on to provide security.
+        Status: Downloaded newer image for hello-world:latest
+        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.
+           (Assuming it was not already locally available.)
+        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
+
+        For more examples and ideas, visit:
+        http://docs.docker.com/userguide/
 
-This should download the very small `hello-world` image and print a
-`Hello from Docker.` message.
 
 ## Using Docker from Windows Command Line Prompt (cmd.exe)
 
-Launch a Windows Command Line Prompt (cmd.exe).
+1. Launch a Windows Command Line Prompt (cmd.exe).
+
+    The `docker-machine` command requires `ssh.exe` in your `PATH` environment
+    variable. This `.exe` is in the MsysGit `bin` folder. 
+
+2. Add this to the `%PATH%` environment variable by running:
+
+        set PATH=%PATH%;"c:\Program Files (x86)\Git\bin"
+        
+3. Create a new Docker VM.
+
+        docker-machine create --driver virtualbox my-docker-vm
+        Creating VirtualBox VM...
+        Creating SSH key...
+        Starting VirtualBox VM...
+        Starting VM...
+        To see how to connect Docker to this machine, run: docker-machine env my-docker-vm
+
+    The command also creates a machine configuration in the
+    `C:\USERS\USERNAME\.docker\machine\machines` directory. You only need to run the `create`
+    command once. Then, you can use `docker-machine` to start, stop, query, and
+    otherwise manage the VM from the command line.
+    
+4. List your available machines.
 
-Boot2Docker command requires `ssh.exe` to be in the PATH, therefore we need to
-include `bin` folder of the Git installation (which has ssh.exe) to the `%PATH%`
-environment variable by running:
+        C:\Users\mary> docker-machine ls
+        NAME                ACTIVE   DRIVER       STATE     URL                         SWARM
+        my-docker-vm        *        virtualbox   Running   tcp://192.168.99.101:2376  
+        
+    If you have previously installed the deprecated Boot2Docker application or
+    run the Docker Quickstart Terminal, you may have a `dev` VM as well.  
 
-    set PATH=%PATH%;"c:\Program Files (x86)\Git\bin"
+5. Get the environment commands for your new VM.
 
-and then we can run the `boot2docker start` command to start the Boot2Docker VM.
-(Run `boot2docker init` command if you get an error saying machine does not
-exist.) Then copy the instructions for cmd.exe to set the environment variables
-to your console window and you are ready to run docker commands such as
-`docker ps`:
+        C:\Users\mary> docker-machine env --shell cmd my-docker-vm
+    
+6. Connect your shell to the `my-docker-vm` machine.
 
-![](/installation/images/windows-boot2docker-cmd.png)
+        C:\Users\mary> eval "$(docker-machine env my-docker-vm)"
+
+7. Run the `hello-world` container to verify your setup.
+
+        C:\Users\mary> docker run hello-world
 
 ## Using Docker from PowerShell
 
-Launch a PowerShell window, then add `ssh.exe` to your PATH:
+1. Launch a Windows PowerShell window.
+
+2. Add `ssh.exe` to your PATH:
+
+        PS C:\Users\mary> $Env:Path = "${Env:Path};c:\Program Files (x86)\Git\bin"
+        
+3. Create a new Docker VM.
+
+        PS C:\Users\mary> docker-machine create --driver virtualbox my-docker-vm
+    
+4. List your available machines.
+
+        C:\Users\mary> docker-machine ls
+        NAME                ACTIVE   DRIVER       STATE     URL                         SWARM
+        my-docker-vm        *        virtualbox   Running   tcp://192.168.99.101:2376  
+      
+5. Get the environment commands for your new VM.
 
-    $Env:Path = "${Env:Path};c:\Program Files (x86)\Git\bin"
+        C:\Users\mary> docker-machine env --shell powershell my-docker-vm
+    
+6. Connect your shell to the `my-docker-vm` machine.
 
-and after running the `boot2docker start` command it will print PowerShell
-commands to set the environment variables to connect to the Docker daemon
-running inside the VM. Run these commands and you are ready to run docker
-commands such as `docker ps`:
+        C:\Users\mary> eval "$(docker-machine env my-docker-vm)"
 
-![](/installation/images/windows-boot2docker-powershell.png)
+7. Run the `hello-world` container to verify your setup.
 
-> NOTE: You can alternatively run `boot2docker shellinit | Invoke-Expression`
-> command to set the environment variables instead of copying and pasting on
-> PowerShell.
+        C:\Users\mary> docker run hello-world
 
-# Further Details
 
-The Boot2Docker management tool provides several commands:
+## Learn about your Toolbox installation
 
-    $ boot2docker
-    Usage: boot2docker.exe [<options>] {help|init|up|ssh|save|down|poweroff|reset|restart|config|status|info|ip|shellinit|delete|download|upgrade|version} [<args>]
+Toolbox installs the Docker Engine binary in the `C:\Program Files\Docker
+Toolbox` directory. When you use the Docker Quickstart Terminal or create a
+`docker-vm` manually, Docker Machine updates the
+`C:\USERS\USERNAME\.docker\machine\machines\docker-vm` folder to your
+system. This folder contains the configuration for the VM.
 
-## Upgrading
+You can create multiple VMs on your system with Docker Machine. So, you may have
+more than one VM folder if you have more than one VM. To remove a VM, use the
+`docker-machine rm <machine-name>` command.
+      
+The `docker-machine` subcommands are slightly different than the `boot2docker`
+subcommands. The table below lists the equivalent `docker-machine` subcommand
+and what it does:
 
-1. Download the latest release of the [Docker for Windows Installer](
-   https://github.com/boot2docker/windows-installer/releases/latest)
+|  `boot2docker` | `docker-machine` | `docker-machine` description                             |
+|----------------|------------------|----------------------------------------------------------|
+| init           | create           | Creates a new docker host.                               |
+| up             | start            | Starts a stopped machine.                                |
+| ssh            | ssh              | Runs a command or interactive ssh session on the machine.|
+| save           | -                | Not applicable.                                          |
+| down           | stop             | Stops a running machine.                                 |
+| poweroff       | stop             | Stops a running machine.                                 |
+| reset          | restart          | Restarts a running machine.                              |
+| config         | inspect          | Prints machine configuration details.                    |
+| status         | ls               | Lists all machines and their status.                     |
+| info           | inspect          | Displays a machine's details.                            |
+| ip             | ip               | Displays the machine's ip address.                       |
+| shellinit      | env              | Displays shell commands needed to configure your shell to interact with a machine |
+| delete         | rm               | Removes a machine.                                       |
+| download       | -                | Not applicable.                                          |
+| upgrade        | upgrade          | Upgrades a machine's Docker client to the latest stable release. |
 
-2. Run the installer, which will update the Boot2Docker management tool.
 
-3. To upgrade your existing virtual machine, open a terminal and run:
+## Upgrade Docker Toolbox
 
-        boot2docker stop
-        boot2docker download
-        boot2docker start
+To upgrade Docker Toolbox, download an re-run [the Docker Toolbox
+installer](https://www.docker.com/toolbox).
 
 ## Container port redirection
 
-If you are curious, the username for the boot2docker default user is `docker`
+If you are curious, the username for the Docker default user is `docker`
 and the password is `tcuser`.
 
 The latest version of `boot2docker` sets up a host only network adaptor which
@@ -161,13 +348,12 @@ You can do this with
 
 ## Uninstallation
 
-You can uninstall Boot2Docker using Window's standard process for removing programs.
-This process does not remove the `docker-install.exe` file. You must delete that file
-yourself.
+You can uninstall Docker Toolbox using Window's standard process for removing
+programs. This process does not remove the `docker-install.exe` file. You must
+delete that file yourself.
 
-## References
+## Learn more
 
-If you have Docker hosts running and if you don't wish to do a 
-Boot2Docker installation, you can install the docker.exe using
-unofficial Windows package manager Chocolately. For information
-on how to do this, see [Docker package on Chocolatey](http://chocolatey.org/packages/docker).
+You can continue with the [Docker User Guide](/userguide). If you are
+interested in using the Kitematic GUI, see the [Kitermatic user
+guide](/kitematic/userguide/).