diff --git a/components/engine/docs/installation/images/mac-page-finished.png b/components/engine/docs/installation/images/mac-page-finished.png new file mode 100644 index 0000000000..7055a92fdf Binary files /dev/null and b/components/engine/docs/installation/images/mac-page-finished.png differ diff --git a/components/engine/docs/installation/images/mac-page-two.png b/components/engine/docs/installation/images/mac-page-two.png new file mode 100644 index 0000000000..bd08ca1522 Binary files /dev/null and b/components/engine/docs/installation/images/mac-page-two.png differ diff --git a/components/engine/docs/installation/images/mac-password-prompt.png b/components/engine/docs/installation/images/mac-password-prompt.png new file mode 100644 index 0000000000..f29afe8b22 Binary files /dev/null and b/components/engine/docs/installation/images/mac-password-prompt.png differ diff --git a/components/engine/docs/installation/images/mac-success.png b/components/engine/docs/installation/images/mac-success.png new file mode 100644 index 0000000000..8b9b6b7f4b Binary files /dev/null and b/components/engine/docs/installation/images/mac-success.png differ diff --git a/components/engine/docs/installation/images/mac-welcome-page.png b/components/engine/docs/installation/images/mac-welcome-page.png new file mode 100644 index 0000000000..6f4501fc9e Binary files /dev/null and b/components/engine/docs/installation/images/mac-welcome-page.png differ diff --git a/components/engine/docs/installation/images/my-docker-vm.png b/components/engine/docs/installation/images/my-docker-vm.png new file mode 100644 index 0000000000..f7073eebfe Binary files /dev/null and b/components/engine/docs/installation/images/my-docker-vm.png differ diff --git a/components/engine/docs/installation/images/osx-installer.png b/components/engine/docs/installation/images/osx-installer.png deleted file mode 100644 index 15eb40839f..0000000000 Binary files a/components/engine/docs/installation/images/osx-installer.png and /dev/null differ diff --git a/components/engine/docs/installation/images/virtualization.png b/components/engine/docs/installation/images/virtualization.png new file mode 100644 index 0000000000..cd2ec08b42 Binary files /dev/null and b/components/engine/docs/installation/images/virtualization.png differ diff --git a/components/engine/docs/installation/images/win-page-6.png b/components/engine/docs/installation/images/win-page-6.png new file mode 100644 index 0000000000..2420b497ab Binary files /dev/null and b/components/engine/docs/installation/images/win-page-6.png differ diff --git a/components/engine/docs/installation/images/win-welcome.png b/components/engine/docs/installation/images/win-welcome.png new file mode 100644 index 0000000000..0c1d3079bb Binary files /dev/null and b/components/engine/docs/installation/images/win-welcome.png differ diff --git a/components/engine/docs/installation/images/win_ver.png b/components/engine/docs/installation/images/win_ver.png new file mode 100644 index 0000000000..2a8fd9035b Binary files /dev/null and b/components/engine/docs/installation/images/win_ver.png differ diff --git a/components/engine/docs/installation/images/windows-finish.png b/components/engine/docs/installation/images/windows-finish.png new file mode 100644 index 0000000000..f1a831d489 Binary files /dev/null and b/components/engine/docs/installation/images/windows-finish.png differ diff --git a/components/engine/docs/installation/images/windows-installer.png b/components/engine/docs/installation/images/windows-installer.png deleted file mode 100644 index 7cf9b0d778..0000000000 Binary files a/components/engine/docs/installation/images/windows-installer.png and /dev/null differ diff --git a/components/engine/docs/installation/mac.md b/components/engine/docs/installation/mac.md index ee5fcaaef9..d958a9a687 100644 --- a/components/engine/docs/installation/mac.md +++ b/components/engine/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. -[Download Kitematic](https://kitematic.com/download) +You install Docker using Docker Toolbox. Docker Toolbox includes the following Docker tools: -Alternatively, you may want to try Kitematic, 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. +If you have VirtualBox running, you must shut it down before running the +installer. -4. Download Boot2Docker by clicking `Boot2Docker-x.x.x.pkg` in the "Downloads" - section. +1. Go to the [Docker Toolbox](https://www.docker.com/toolbox) page. -3. Install Boot2Docker by double-clicking the package. +2. Click the installer link to download. - The installer places Boot2Docker and VirtualBox in your "Applications" folder. +3. Install Docker Toolbox by double-clicking the package or by right-clicking +and choosing "Open" from the pop-up menu. -The installation places the `docker` and `boot2docker` binaries in your -`/usr/local/bin` directory. + The installer launches the "Install Docker Toolbox" dialog. + + ![Install Docker Toolbox](/installation/images/mac-welcome-page.png) + +4. Press "Continue" to install the toolbox. + + 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." + +5. Press "Install" to perform the standard installation. + + The system prompts you for your password. + + ![Password prompt](/installation/images/mac-password-prompt.png) + +6. Provide your password to continue with the installation. + + 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. -## Start the Boot2Docker Application +## Running a Docker Container -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. +To run a Docker container, you: -> **NOTE**: Boot2Docker is designed as a development tool. You should not use -> it in production environments. +* 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 -### From the Applications folder +Once you create a machine, you can reuse it as often as you like. Like any +VirtualBox VM, it maintains its configuration between uses. -When you launch the "Boot2Docker" application from your "Applications" folder, the -application: +There are two ways to use the installed tools, from the Docker Quickstart Terminal or +[from your shell](#from-your-shell). -* opens a terminal window +### From the Docker Quickstart Terminal -* creates a $HOME/.boot2docker directory +1. Open the "Applications" folder or the "Launchpad". -* creates a VirtualBox ISO and certs +2. Find the Docker Quickstart Terminal and double-click to launch it. -* starts a VirtualBox VM running the `docker` daemon + The application: -Once the launch completes, you can run `docker` commands. A good way to verify -your setup succeeded is to run the `hello-world` container. + * 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 - $ 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. + Once the launch completes, the Docker Quickstart Terminal reports: + + ![All finished](/installation/images/mac-success.png) + + Now, you can run `docker` commands. - 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. +3. Verify your setup succeeded by running the `hello-world` container. - To try something more ambitious, you can run an Ubuntu container with: - $ docker run -it ubuntu bash + $ 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. - For more examples and ideas, visit: - http://docs.docker.com/userguide/ + 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 start and stop `boot2docker` is using the command line. +A more typical way to interact with the Docker tools is from your regular shell command line. -### From your command line +### From your shell -Initialize and run `boot2docker` from the command line, do the following: +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 Boot2Docker VM. +1. Create a new Docker VM. - $ boot2docker init + $ 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 virtual machine. You only need to run this command once. + This creates a new `docker-vm` in VirtualBox. + + ![docker-vm](/installation/images/docker-vm.png) -2. Start the `boot2docker` VM. + 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. - $ boot2docker start + $ 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. Display the environment variables for the Docker client. +3. Get the environment commands for your new VM. - $ 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 + $ 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. - 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. + $ eval "$(docker-machine env docker-vm)" 5. Run the `hello-world` container to verify your setup. $ docker run hello-world -## Basic Boot2Docker exercises +## Learn about your Toolbox installation -At this point, you should have `boot2docker` running and the `docker` client -environment initialized. To verify this, run the following commands: +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. - $ boot2docker status - $ docker version +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 ` 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: -Work through this section to try some practical container tasks using `boot2docker` VM. +| `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. +## Upgrade Docker Toolbox -### 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 +To upgrade Docker Toolbox, download an re-run [the Docker Toolbox +installer](https://docker.com/toolbox/). -### Use the installer +## Uninstall Docker Toolbox -To upgrade any version of Boot2Docker, do this: +To uninstall, do the following: -1. Open a terminal on your local machine. +1. List your machines. -2. Stop the `boot2docker` application. + $ 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 - $ boot2docker stop +2. Remove each machine. -3. Go to the [boot2docker/osx-installer ]( - https://github.com/boot2docker/osx-installer/releases/latest) release page. + $ docker-machine rm dev + Successfully removed dev + + Removing a machine deletes its VM from VirtualBox and from the + `~/.docker/machine/machines` directory. -4. Download Boot2Docker by clicking `Boot2Docker-x.x.x.pkg` in the "Downloads" - section. +3. Remove the Docker Quickstart Terminal and Kitematic from your "Applications" folder. -2. Install Boot2Docker by double-clicking the package. +4. Remove the `docker`, `docker-compose`, and `docker-machine` commands from the `/usr/local/bin` folder. - The installer places Boot2Docker in your "Applications" folder. + $ rm /usr/local/bin/docker + +5. Delete the `~/.docker` folder from your system. -## Uninstallation +## Learning more -1. Go to the [boot2docker/osx-installer ]( - https://github.com/boot2docker/osx-installer/releases/latest) release 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/). -2. Download the source code by clicking `Source code (zip)` or - `Source code (tar.gz)` in the "Downloads" section. - -3. Extract the source code. - -4. Open a terminal on your local machine. - -5. Change to the directory where you extracted the source code: - - $ cd - -6. Make sure the uninstall.sh script is executable: - - $ chmod +x uninstall.sh - -7. Run the uninstall.sh script: - - $ ./uninstall.sh - - -## 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). - -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. - -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/). diff --git a/components/engine/docs/installation/windows.md b/components/engine/docs/installation/windows.md index 64ed93939e..622ed82492 100644 --- a/components/engine/docs/installation/windows.md +++ b/components/engine/docs/installation/windows.md @@ -9,122 +9,309 @@ parent = "smn_engine" # 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 Microsoft® Hardware-Assisted Virtualization Detection + Tool 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 +### Installation -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]. +If you have VirtualBox running, you must shut it down before running the +installer. -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: +1. Go to the [Docker Toolbox](https://www.docker.com/toolbox) page. -![](/installation/images/windows-boot2docker-start.png) +2. Click the installer link to download. -## Running Docker +3. Install Docker Toolbox by double-clicking the installer. -> **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. + The installer launches the "Setup - Docker Toolbox" dialog. + + ![Install Docker Toolbox](/installation/images/win-welcome.png) -**Boot2Docker Start** will automatically start a shell with environment variables -correctly set so you can start using Docker right away: +4. Press "Next" to install the toolbox. -Let's try the `hello-world` example image. Run + 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 - $ docker run hello-world + This installation assumes the defaults are acceptable. + +5. Press "Next" until you reach the "Ready to Install" page. + + The system prompts you for your password. + + ![Install](/installation/images/win-page-6.png) + +6. Press "Install" to continue with the installation. + + 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. + + +## Running a Docker Container + +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). -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: + The `docker-machine` command requires `ssh.exe` in your `PATH` environment + variable. This `.exe` is in the MsysGit `bin` folder. - set PATH=%PATH%;"c:\Program Files (x86)\Git\bin" +2. Add this to the `%PATH%` environment variable by running: -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`: + set PATH=%PATH%;"c:\Program Files (x86)\Git\bin" + +3. Create a new Docker VM. -![](/installation/images/windows-boot2docker-cmd.png) + 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. + + 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. + +5. Get the environment commands for your new VM. + + C:\Users\mary> docker-machine env --shell cmd my-docker-vm + +6. Connect your shell to the `my-docker-vm` machine. + + 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. - $Env:Path = "${Env:Path};c:\Program Files (x86)\Git\bin" +2. Add `ssh.exe` to your PATH: -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`: + PS C:\Users\mary> $Env:Path = "${Env:Path};c:\Program Files (x86)\Git\bin" + +3. Create a new Docker VM. -![](/installation/images/windows-boot2docker-powershell.png) + PS C:\Users\mary> docker-machine create --driver virtualbox my-docker-vm + +4. List your available machines. -> 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-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. -# Further Details + C:\Users\mary> docker-machine env --shell powershell my-docker-vm + +6. Connect your shell to the `my-docker-vm` machine. -The Boot2Docker management tool provides several commands: + C:\Users\mary> eval "$(docker-machine env my-docker-vm)" - $ boot2docker - Usage: boot2docker.exe [] {help|init|up|ssh|save|down|poweroff|reset|restart|config|status|info|ip|shellinit|delete|download|upgrade|version} [] +7. Run the `hello-world` container to verify your setup. -## Upgrading + C:\Users\mary> docker run hello-world -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 update the Boot2Docker management tool. +## Learn about your Toolbox installation -3. To upgrade your existing virtual machine, open a terminal and run: +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. - boot2docker stop - boot2docker download - boot2docker start +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 ` 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. | + + +## Upgrade Docker Toolbox + +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/).