- Tested Mac/iterated with Jeff on fixes - Waiting on formal uninstall;manual now - 4 hour work - Fixe #14562 converting Windows to Mac - Found errors in installer need fixes/another iteration - Updated as far as possible with limited installation - 3 Hours work - Entering comments from PR review - New screen captures and migration material - Entering Sven's comment - Testing with powershell, Seb's comments - Fix link in upgrade - Minor tweaks to http and typos - Adding deprecation note Signed-off-by: Mary Anthony <mary@docker.com>
14 KiB
Windows
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.
You install Docker using Docker Toolbox. Docker Toolbox includes the following Docker tools:
- 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:
-
Right click the Windows message and choose System.
If you aren't using a supported version, you could consider upgrading your operating system.
-
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: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.
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
.
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.
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.
-
Go to the Docker Toolbox page.
-
Click the installer link to download.
-
Install Docker Toolbox by double-clicking the installer.
The installer launches the "Setup - Docker Toolbox" dialog.
-
Press "Next" to install the toolbox.
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
This installation assumes the defaults are acceptable.
- installs executables for the Docker tools in
-
Press "Next" until you reach the "Ready to Install" page.
The system prompts you for your password.
-
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.
-
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 the Docker Quickstart Terminal
-
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. -
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/
Using Docker from Windows Command Line Prompt (cmd.exe)
-
Launch a Windows Command Line Prompt (cmd.exe).
The
docker-machine
command requiresssh.exe
in yourPATH
environment variable. This.exe
is in the MsysGitbin
folder. -
Add this to the
%PATH%
environment variable by running:set PATH=%PATH%;"c:\Program Files (x86)\Git\bin"
-
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 thecreate
command once. Then, you can usedocker-machine
to start, stop, query, and otherwise manage the VM from the command line. -
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. -
Get the environment commands for your new VM.
C:\Users\mary> docker-machine env --shell cmd my-docker-vm
-
Connect your shell to the
my-docker-vm
machine.C:\Users\mary> eval "$(docker-machine env my-docker-vm)"
-
Run the
hello-world
container to verify your setup.C:\Users\mary> docker run hello-world
Using Docker from PowerShell
-
Launch a Windows PowerShell window.
-
Add
ssh.exe
to your PATH:PS C:\Users\mary> $Env:Path = "${Env:Path};c:\Program Files (x86)\Git\bin"
-
Create a new Docker VM.
PS C:\Users\mary> docker-machine create --driver virtualbox my-docker-vm
-
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
-
Get the environment commands for your new VM.
C:\Users\mary> docker-machine env --shell powershell my-docker-vm
-
Connect your shell to the
my-docker-vm
machine.C:\Users\mary> eval "$(docker-machine env my-docker-vm)"
-
Run the
hello-world
container to verify your setup.C:\Users\mary> docker run hello-world
Learn about your Toolbox installation
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.
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. |
Upgrade Docker Toolbox
To upgrade Docker Toolbox, download an re-run the Docker Toolbox installer.
Container port redirection
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
provides access to the container's ports.
If you run a container with an exposed port:
docker run --rm -i -t -p 80:80 nginx
Then you should be able to access that nginx server using the IP address reported to you using:
boot2docker ip
Typically, it is 192.168.59.103, but it could get changed by VirtualBox's DHCP implementation.
For further information or to report issues, please see the Boot2Docker site
Login with PUTTY instead of using the CMD
Boot2Docker generates and uses the public/private key pair in your %USERPROFILE%\.ssh
directory so to log in you need to use the private key from this same directory.
The private key needs to be converted into the format PuTTY uses.
You can do this with puttygen:
- Open
puttygen.exe
and load ("File"->"Load" menu) the private key from%USERPROFILE%\.ssh\id_boot2docker
- then click: "Save Private Key".
- Then use the saved file to login with PuTTY using
docker@127.0.0.1:2022
.
Uninstallation
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.
Learn more
You can continue with the Docker User Guide. If you are interested in using the Kitematic GUI, see the Kitermatic user guide.