beenull/moby
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

install mac and win pared down, link to d4mac, d4win, getting started improved, added menu.md's

Browse source 
fixing links to d4mac and d4win

updates per @Sven and @theJeztah, fixing links, typos, menu definitions, etc.

updates per Sven's comments in the PR

removed duplicate line in tutorials menu.md

Signed-off-by: Victoria Bialas <victoria.bialas@docker.com>
(cherry picked from commit 5bc730eda7)
This commit is contained in:
Victoria Bialas 2016-06-16 22:29:56 -07:00 committed by Tibor Vass
parent 906eacd586
commit d1c91b41e1
21 changed files with 133 additions and 778 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

32
docs/getstarted/index.md
View file

@ -10,15 +10,30 @@ description = "Getting started with Docker"
keywords = ["beginner, getting started, Docker"]
[menu.main]
identifier = "getstart_all"
parent = "engine_use"
weight="-80"
parent = "tutorial_getstart_menu"
weight="-1"
+++
<![end-metadata]-->
# Get Started with Docker
This tutorial is a for non-technical users who are interested in learning more about Docker. By following these steps, you'll learn fundamental Docker features while working through some simple tasks. You'll learn how to:
This tutorial is a for non-technical users who are interested in learning more about Docker. By following these steps, you'll learn fundamental Docker features while working through some simple tasks.
Depending on how you got here, you may or may not have already downloaded Docker for your platform and installed it.
## Got Docker?
If you haven't yet downloaded Docker for your platform or installed it, go to [Get Docker](step_one.md#step-1-get-docker).
## Ready to start working with Docker?
If you have already downloaded and installed Docker, you are ready to run Docker commands! Go to [Verify your installation](step_one.md#step-3-verify-your-installation).
### What you'll learn and do
You'll learn how to:
* install Docker software for your platform
* run a software image in a container
@ -30,10 +45,17 @@ This tutorial is a for non-technical users who are interested in learning more a
The getting started was user tested to reduce the chance of users having problems. For the best chance of success, follow the steps as written the first time before exploring on your own. It takes approximately 45 minutes to complete.
## Flavors of Docker
### Make sure you understand...
This tutorial is designed as a getting started with Docker, and works the same whether you are using Docker for Mac, Docker for Windows, Docker on Linux, or Docker Toolbox (for older Mac and Windows systems).
This getting started uses Docker Engine CLI commands entered on the command line of a terminal window. You don't need to be a wizard at the command line, but you should be familiar with how to open your favorite shell or terminal, and run basic commands in that environment. It helps (but isn't required) to know how to navigate a directory tree, manipulate files, list running process, and so forth.
If you are using Docker Toolbox, you can use the Docker Quickstart Terminal to run Docker commands in a pre-configured environment instead of opening a command line terminal.
If you are using Docker for Mac, Docker for Windows, or Docker on Linux, you will have Docker running in the background, and your standard command line terminal is already set up to run Docker commands.
## How much command line savvy do I need?
The getting started tour uses Docker Engine CLI commands entered on the command line of a terminal window. You don't need to be a wizard at the command line, but you should be familiar with how to open your favorite shell or terminal, and run basic commands in that environment. It helps (but isn't required) to know how to navigate a directory tree, manipulate files, list running process, and so forth.
Go to [the next page to install](step_one.md).

6
docs/getstarted/last_page.md
View file

@ -10,7 +10,7 @@ description = "Getting started with Docker"
keywords = ["beginner, getting started, Docker"]
[menu.main]
identifier = "getstart_learn_more"
parent = "getstart_all"
parent = "tutorial_getstart_menu"
weight = 7
+++
<![end-metadata]-->
@ -33,8 +33,8 @@ Depending on your interest, the Docker documentation contains a wealth of inform
<td class="tg-031e">[Getting Started with Docker for Mac](/docker-for-mac/index.md)</td>
</tr>
<tr>
<td class="tg-031e">More about Docker for Windows, More about Docker for Windows, features, examples, FAQs, relationship to Docker Machine and Docker Toolbox, and how this fits in the Docker ecosystem</td>
<td class="tg-031e">[Getting Started with Docker for Windows](/docker-for-mac/index.md)</td>
<td class="tg-031e">More about Docker for Windows, features, examples, FAQs, relationship to Docker Machine and Docker Toolbox, and how this fits in the Docker ecosystem</td>
<td class="tg-031e">[Getting Started with Docker for Windows](/docker-for-windows/index.md)</td>
</tr>
<tr>
<td class="tg-031e">More about Docker Toolbox</td>

2
docs/getstarted/linux_install_help.md
View file

@ -5,7 +5,7 @@ title = "Install Docker and run hello-world"
description = "Getting started with Docker"
keywords = ["beginner, getting started, Docker, install"]
identifier = "getstart_linux_install"
parent = "getstart_all"
parent = "tutorial_getstart_menu"
weight="-80"
+++
<![end-metadata]-->

16
docs/getstarted/menu.md Normal file
View file

@ -0,0 +1,16 @@
<!--[metadata]>
+++
aliases = [
]
title = "Get Started with Docker"
description = "Docker Mac"
keywords = ["beginner, getting started, Docker"]
type = "menu"
[menu.main]
identifier = "tutorial_getstart_menu"
parent = "engine_use"
weight = -80
+++
<![end-metadata]-->
# Get Started with Docker

2
docs/getstarted/step_five.md
View file

@ -10,7 +10,7 @@ description = "Getting started with Docker"
keywords = ["beginner, getting started, Docker"]
[menu.main]
identifier = "getstart_docker_hub"
parent = "getstart_all"
parent = "tutorial_getstart_menu"
weight = 5
+++
<![end-metadata]-->

2
docs/getstarted/step_four.md
View file

@ -10,7 +10,7 @@ description = "Getting started with Docker"
keywords = ["beginner, getting started, Docker"]
[menu.main]
identifier = "getstart_build_image"
parent = "getstart_all"
parent = "tutorial_getstart_menu"
weight = 4
+++
<![end-metadata]-->

22
docs/getstarted/step_one.md
View file

@ -10,13 +10,17 @@ description = "Getting started with Docker"
keywords = ["beginner, getting started, Docker, install"]
[menu.main]
identifier = "getstart_all_install"
parent = "getstart_all"
parent = "tutorial_getstart_menu"
weight = 1
+++
<![end-metadata]-->
# Install Docker
- [Step 1: Get Docker](#step-1-get-docker)
- [Step 2: Install Docker](#step-2-install-docker)
- [Step 3: Verify your installation](#step-3-verify-your-installation)
## Step 1: Get Docker
### Docker for Mac
@ -25,7 +29,7 @@ Docker for Mac is our newest offering for the Mac. It runs as a native Mac appli
<a class="button" href="https://download.docker.com/mac/beta/Docker.dmg">Get Docker for Mac</a>
#### Install Prequisites
**Requirements**
- Mac must be a 2010 or newer model, with Intel's hardware support for memory management unit (MMU) virtualization; i.e., Extended Page Tables (EPT)
@ -47,7 +51,7 @@ Docker for Windows is our newest offering for PCs. It runs as a native Windows a
<a class="button" href="https://download.docker.com/win/beta/InstallDocker.msi">Get Docker for Windows</a>
#### Install Prequisites
**Requirements**
* 64bit Windows 10 Pro, Enterprise and Education (1511 November update, Build 10586 or later). In the future we will support more versions of Windows 10.
@ -66,21 +70,19 @@ For full instructions on getting Docker for various Linux distributions, see [In
## Step 2: Install Docker
* For install instructions for Docker for Mac, see [Getting Started with Docker for Mac](/docker-for-mac/index.md).
- **Docker for Mac** - Install instructions are at [Getting Started with Docker for Mac](/docker-for-mac/index.md).
* For install instructions for Docker for Windows, see [Getting Started with Docker for Windows](/docker-for-windows/index.md).
- **Docker for Windows** - Install instructions are at [Getting Started with Docker for Windows](/docker-for-windows/index.md).
* For install instructions for Docker Toolbox, see [Docker Toolbox Overview](/toolbox/overview.md).
- **Docker Toolbox** - Install instructions are at [Docker Toolbox Overview](/toolbox/overview.md).
* For a simple example of installing Docker on Ubuntu Linux so that you can work through this tutorial, see [Installing Docker on Ubuntu Linux (Example)](linux_install_help.md).
For full install instructions for Docker on Linux, see [Install Docker Engine](/engine/installation/index.md) and select the flavor of Linux you want to use.
- **Docker on Linux** - For a simple example of installing Docker on Ubuntu Linux so that you can work through this tutorial, see [Installing Docker on Ubuntu Linux (Example)](linux_install_help.md). Full install instructions for all flavors of Linux we support are at [Install Docker Engine](/engine/installation/index.md).
## Step 3: Verify your installation
1. Open a command-line terminal, and run some Docker commands to verify that Docker is working as expected.
Some good commands to try are `docker version` to check that you have the latest release installed and `docker ps` to see if you have any running containers. (Probably not, since you just started.)
Some good commands to try are `docker version` to check that you have the latest release installed and `docker ps` to see if you have any running containers. (Probably not, since you just started.)
2. Type the `docker run hello-world` command and press RETURN.

2
docs/getstarted/step_six.md
View file

@ -10,7 +10,7 @@ description = "Getting started with Docker"
keywords = ["beginner, getting started, Docker"]
[menu.main]
identifier = "getstart_tag_push_pull"
parent = "getstart_all"
parent = "tutorial_getstart_menu"
weight = 6
+++
<![end-metadata]-->

2
docs/getstarted/step_three.md
View file

@ -10,7 +10,7 @@ description = "Getting started with Docker"
keywords = ["beginner, getting started, Docker"]
[menu.main]
identifier = "getstart_locate"
parent = "getstart_all"
parent = "tutorial_getstart_menu"
weight = 3
+++
<![end-metadata]-->

2
docs/getstarted/step_two.md
View file

@ -10,7 +10,7 @@ description = "Getting started with Docker"
keywords = ["beginner, getting started, Docker"]
[menu.main]
identifier = "getstart_understand"
parent = "getstart_all"
parent = "tutorial_getstart_menu"
weight = 2
+++
<![end-metadata]-->

420
docs/installation/mac.md
View file

@ -11,418 +11,46 @@ weight="-90"
# Mac OS X
You install Docker using Docker Toolbox. Docker Toolbox includes the following Docker tools:
You have two options for installing Docker on Mac:
* 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
- [Docker for Mac](#docker-for-mac)
- [Docker Toolbox](#docker-toolbox)
Because the Docker daemon uses Linux-specific kernel features, you can't run
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.
## Docker for Mac
Docker for Mac is our newest offering for the Mac. It runs as a native Mac application and uses <a href="https://github.com/mist64/xhyve/" target="_blank">xhyve</a> to virtualize the Docker Engine environment and Linux kernel-specific features for the Docker daemon.
Go to [Getting Started with Docker for Mac](/docker-for-mac/index.md) for download and install instructions, and to learn all about Docker for Mac.
**Requirements**
Your Mac must be running OS X 10.8 "Mountain Lion" or newer to install the
Docker Toolbox.
- Mac must be a 2010 or newer model, with Intel's hardware support for memory management unit (MMU) virtualization; i.e., Extended Page Tables (EPT)
### Learn the key concepts before installing
- OS X 10.10.3 Yosemite or newer
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.
- At least 4GB of RAM
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`.
- VirtualBox prior to version 4.3.30 must NOT be installed (it is incompatible with Docker for Mac). Docker for Mac will error out on install in this case. Uninstall the older version of VirtualBox and re-try the install.
![Linux Architecture Diagram](images/linux_docker_host.svg)
## Docker Toolbox
In an OS X installation, the `docker` daemon is running inside a Linux VM called
`default`. The `default` 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.
If you have an earlier Mac that doesn't meet the Docker for Mac requirements, <a href="https://www.docker.com/products/docker-toolbox" target="_blank">get Docker Toolbox</a> for the Mac.
![OSX Architecture Diagram](images/mac_docker_host.svg)
See [Docker Toolbox Overview](/toolbox/overview.md) for help on installing Docker with Toolbox.
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.
The Docker Toolbox setup does not run Docker natively in OS X. Instead, it uses `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**
### 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 Download link.
3. Install Docker Toolbox by double-clicking the package or by right-clicking
and choosing "Open" from the pop-up menu.
The installer launches the "Install Docker Toolbox" dialog.
![Install Docker Toolbox](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](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
* installs VirtualBox; or updates any existing installation
To change these defaults, press "Customize" or "Change
Install Location."
5. Press "Install" to perform the standard installation.
The system prompts you for your password.
![Password prompt](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](images/mac-page-finished.png)
7. Press "Close" to exit.
## Running a Docker Container
To run a Docker container, you:
* Create a new (or start an existing) virtual machine
* Switch your environment to your new VM
* Use the `docker` client to create, load, and manage containers
You can reuse this virtual machine as often as you like. Like any
VirtualBox VM, it maintains its configuration between uses.
There are two ways to use the installed tools, from the Docker Quickstart Terminal or
[from your shell](#from-your-shell).
### From the Docker Quickstart Terminal
1. Open the "Applications" folder or the "Launchpad".
2. Find the Docker Quickstart Terminal and double-click to launch it.
The application:
* Opens a terminal window
* Creates a `default` VM if it doesn't exists, and starts the VM after
* Points the terminal environment to this VM
Once the launch completes, the Docker Quickstart Terminal reports:
![All finished](images/mac-success.png)
Now, 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/
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 default
Creating VirtualBox VM...
Creating SSH key...
Starting VirtualBox VM...
Starting VM...
To see how to connect Docker to this machine, run: docker-machine env default
This creates a new `default` VM in VirtualBox.
The command also creates a machine configuration in the
`~/.docker/machine/machines/default` 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
default * 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 `default` 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 default
export DOCKER_TLS_VERIFY="1"
export DOCKER_HOST="tcp://192.168.99.101:2376"
export DOCKER_CERT_PATH="/Users/mary/.docker/machine/machines/default"
export DOCKER_MACHINE_NAME="default"
# Run this command to configure your shell:
# eval "$(docker-machine env default)"
4. Connect your shell to the `default` machine.
$ eval "$(docker-machine env default)"
5. Run the `hello-world` container to verify your setup.
$ docker run hello-world
## 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 `default` VM manually, Docker
Machine updates the `~/.docker/machine/machines/default` folder to your
system. This folder contains the configuration for the VM.
You can create multiple VMs on your system with Docker Machine. Therefore, you
may end up with multiple VM folders if you have more than one VM. To remove a
VM, use the `docker-machine rm <machine-name>` command.
## Migrate from Boot2Docker
If you were using Boot2Docker previously, you have a pre-existing Docker
`boot2docker-vm` VM on your local system. To allow Docker Machine to manage
this older VM, you can migrate it.
1. Open a terminal or the Docker CLI on your system.
2. Type the following command.
$ docker-machine create -d virtualbox --virtualbox-import-boot2docker-vm boot2docker-vm docker-vm
3. Use the `docker-machine` command to interact with the migrated VM.
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. |
## Examples 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
default * virtualbox Running tcp://192.168.99.100:2376
The `ACTIVE` machine, in this case `default`, is the one your environment is pointing to.
### Access container ports
1. Start an NGINX container on the DOCKER_HOST.
$ docker run -d -P --name web nginx
Normally, the `docker run` commands starts a container, runs it, and then
exits. The `-d` flag keeps the container running in the background
after the `docker run` command completes. The `-P` flag publishes exposed ports from the
container to your local host; this lets you access them from your Mac.
2. Display your running container with `docker ps` command
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
5fb65ff765e9 nginx:latest "nginx -g 'daemon of 3 minutes ago Up 3 minutes 0.0.0.0:49156->443/tcp, 0.0.0.0:49157->80/tcp web
At this point, you can see `nginx` is running as a daemon.
3. View just the container's ports.
$ docker port web
443/tcp -> 0.0.0.0:49156
80/tcp -> 0.0.0.0:49157
This tells you that the `web` container's port `80` is mapped to port
`49157` on your Docker host.
4. Enter the `http://localhost:49157` address (`localhost` is `0.0.0.0`) in your browser:
![Bad Address](images/bad_host.png)
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 your Docker VM.
5. Get the address of the `default` VM.
$ docker-machine ip default
192.168.59.103
6. Enter the `http://192.168.59.103:49157` address in your browser:
![Correct Addressing](images/good_host.png)
Success!
7. To stop and then remove your running `nginx` container, do the following:
$ docker stop web
$ docker rm web
### Mount a volume on the container
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.
1. Change to your user `$HOME` directory.
$ cd $HOME
2. Make a new `site` directory.
$ mkdir site
3. Change into the `site` directory.
$ cd site
4. Create a new `index.html` file.
$ echo "my new site" > index.html
5. Start a new `nginx` container and replace the `html` folder with your `site` directory.
$ docker run -d -P -v $HOME/site:/usr/share/nginx/html \
--name mysite nginx
6. View the `mysite` container's port.
$ docker port mysite
80/tcp -> 0.0.0.0:49166
443/tcp -> 0.0.0.0:49165
7. Open the site in a browser:
![My site page](images/newsite_view.png)
8. Add a page to your `$HOME/site` in real time.
$ echo "This is cool" > cool.html
9. Open the new page in the browser.
![Cool page](images/cool_view.png)
10. Stop and then remove your running `mysite` container.
$ docker stop mysite
$ docker rm mysite
> **Note**: There is a [known
> issue](https://docs.docker.com/machine/drivers/virtualbox/#known-issues) that
> may cause files shared with your nginx container to not update correctly as you
> modify them on your host.
## Upgrade Docker Toolbox
To upgrade Docker Toolbox, download and re-run the [Docker Toolbox
installer](https://docker.com/toolbox/).
## Uninstall Docker Toolbox
To uninstall, do the following:
1. List your machines.
$ docker-machine ls
NAME ACTIVE DRIVER STATE URL SWARM
dev * virtualbox Running tcp://192.168.99.100:2376
my-docker-machine virtualbox Stopped
default virtualbox Stopped
2. Remove each machine.
$ docker-machine rm dev
Successfully removed dev
Removing a machine deletes its VM from VirtualBox and from the
`~/.docker/machine/machines` directory.
3. Remove the Docker Quickstart Terminal and Kitematic from your "Applications" folder.
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.
Your Mac must be running OS X 10.8 "Mountain Lion" or newer to install the Docker Toolbox. Full install instructions are at [Toolbox install instructions for Mac](/toolbox/toolbox_install_mac.md).
## Learning more
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/).
* If you are new to Docker, try out the [Getting Started](../getstarted/index.md) tutorial for a hands-on tour, including using Docker commands, running containers, building images, and working with Docker Hub.
You can continue with the [Docker Engine User Guide](../userguide/index.md). If you are
interested in using the Kitematic GUI, see the [Kitematic user
guide](https://docs.docker.com/kitematic/userguide/).
* You can find more extensive examples in [Learn by example](../tutorials/index.md) and in the [Docker Engine User Guide](../userguide/index.md).
* If you are interested in using the Kitematic GUI, see the [Kitematic user guide](https:docs.docker.com/kitematic/userguide/).
> **Note**: The Boot2Docker command line was deprecated several releases > back in favor of Docker Machine, and now Docker for Windows.

368
docs/installation/windows.md
View file

@ -11,369 +11,41 @@ weight="-80"
# 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 have two options for installing Docker on Windows:
You install Docker using Docker Toolbox. Docker Toolbox includes the following Docker tools:
- [Docker for Windows](#docker-for-windows)
- [Docker Toolbox](#docker-toolbox)
* 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
## Docker for Windows
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.
Docker for Windows is our newest offering for PCs. It runs as a native Windows application and uses Hyper-V to virtualize the Docker Engine environment and Linux kernel-specific features for the Docker daemon.
The virtual machine runs a lightweight Linux distribution made specifically to
run the Docker daemon. The VirtualBox VM runs completely from RAM, is a small
~24MB download, and boots in approximately 5s.
Go to [Getting Started with Docker for Windows](/docker-for-windows/index.md) for download and install instructions, and to learn all about Docker for Windows.
## Requirements
**Requirements**
To run Docker, your machine must have a 64-bit operating system running Windows 7 or higher. Additionally, you must make sure that virtualization is enabled on your machine.
To verify your machine meets these requirements, do the following:
* 64bit Windows 10 Pro, Enterprise and Education (1511 November update, Build 10586 or later). In the future we will support more versions of Windows 10.
1. Right click the Windows Start Menu and choose **System**.
* The Hyper-V package must be enabled. The Docker for Windows installer will enable it for you, if needed. (This requires a reboot).
![Which version](images/win_ver.png)
## Docker Toolbox
If you are using an unsupported version of Windows, you should consider
upgrading your operating system in order to try out Docker.
If you have an earlier Windows system that doesn't meet the Docker for Windows requirements, <a href="https://www.docker.com/products/docker-toolbox" target="_blank">get Docker Toolbox</a>.
2. Make sure your CPU supports [virtualization technology](https://en.wikipedia.org/wiki/X86_virtualization)
and virtualization support is enabled in BIOS and recognized by Windows.
See [Docker Toolbox Overview](/toolbox/overview.md) for help on installing Docker with Toolbox.
#### For Windows 8, 8.1 or 10
The Docker Toolbox setup does not run Docker natively in OS X. Instead, it uses `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.
Choose **Start > Task Manager**. On Windows 10, click more details. Navigate to the **Performance** tab.
Under **CPU** you should see the following:
**Requirements**
![Release page](images/virtualization.png)
To run Docker, your machine must have a 64-bit operating system running Windows 7 or higher. Additionally, you must make sure that virtualization is enabled on your machine. For details, see the [Toolbox install instructions for Windows](/toolbox/toolbox_install_windows.md).
If virtualization is not enabled on your system, follow the manufacturer's instructions for enabling it.
## Learning more
#### For Windows 7
* If you are new to Docker, try out the [Getting Started](../getstarted/index.md) tutorial for a hands-on tour, including using Docker commands, running containers, building images, and working with Docker Hub.
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.
* You can find more extensive examples in [Learn by example](../tutorials/index.md) and in the [Docker Engine User Guide](../userguide/index.md).
3. Verify your Windows OS is 64-bit (x64)
* If you are interested in using the Kitematic GUI, see the [Kitematic user guide](https://docs.docker.com/kitematic/userguide/).
How you do this verification depends on your Windows version. For details, see the Windows
article [How to determine whether a computer is running a 32-bit version or 64-bit version
of the Windows operating system](https://support.microsoft.com/en-us/kb/827218).
> **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 Chocolatey. 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](images/linux_docker_host.svg)
In a 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](images/win_docker_host.svg)
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.
The installer launches the "Setup - Docker Toolbox" dialog.
![Install Docker Toolbox](images/win-welcome.png)
4. 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`
* install VirtualBox; or updates any existing 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.
5. Press "Next" until you reach the "Ready to Install" page.
The system prompts you for your password.
![Install](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](images/windows-finish.png)
7. Press "Finish" 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).
### Using 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 `default` VM if it doesn't exist, and starts the VM after
* 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/
### Using Docker from Windows Command Prompt (cmd.exe)
1. Launch a Windows Command 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-default
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-default
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-default * 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-default
6. Connect your shell to the `my-default` machine.
C:\Users\mary> eval "$(docker-machine env my-default)"
7. Run the `hello-world` container to verify your setup.
C:\Users\mary> docker run hello-world
### Using Docker from PowerShell
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-default
4. List your available machines.
C:\Users\mary> docker-machine ls
NAME ACTIVE DRIVER STATE URL SWARM
my-default * virtualbox Running tcp://192.168.99.101:2376
5. Get the environment commands for your new VM.
C:\Users\mary> docker-machine env --shell powershell my-default
6. Connect your shell to the `my-default` machine.
C:\Users\mary> eval "$(docker-machine env my-default)"
7. 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
`default` VM manually, Docker Machine updates the
`C:\USERS\USERNAME\.docker\machine\machines\default` folder to your
system. This folder contains the configuration for the VM.
You can create multiple VMs on your system with Docker Machine. Therefore, you
may end up with multiple VM folders if you have created more than one VM. To
remove a VM, use the `docker-machine rm <machine-name>` command.
## Migrate from Boot2Docker
If you were using Boot2Docker previously, you have a pre-existing Docker
`boot2docker-vm` VM on your local system. To allow Docker Machine to manage
this older VM, you can migrate it.
1. Open a terminal or the Docker CLI on your system.
2. Type the following command.
$ docker-machine create -d virtualbox --virtualbox-import-boot2docker-vm boot2docker-vm docker-vm
3. Use the `docker-machine` command to interact with the migrated VM.
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 and re-run [the Docker Toolbox
installer](https://www.docker.com/toolbox).
## Container port redirection
If you are curious, the username for the Docker default VM is `docker` and the
password is `tcuser`. The latest version of `docker-machine` sets up a host only
network adaptor which provides access to the container's ports.
If you run a container with a published 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:
$ docker-machine ip
Typically, the IP is 192.168.59.103, but it could get changed by VirtualBox's
DHCP implementation.
> **Note**: There is a [known
> issue](https://docs.docker.com/machine/drivers/virtualbox/#known-issues) that
> may cause files shared with your nginx container to not update correctly as you
> modify them on your host.
## Login with PUTTY instead of using the CMD
Docker Machine generates and uses the public/private key pair in your
`%USERPROFILE%\.docker\machine\machines\<name_of_your_machine>` directory. 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](http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html):
1. Open `puttygen.exe` and load ("File"->"Load" menu) the private key from (you may need to change to the `All Files (*.*)` filter)
%USERPROFILE%\.docker\machine\machines\<name_of_your_machine>\id_rsa
2. Click "Save Private Key".
3. 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 Engine User Guide](../userguide/index.md). If you are
interested in using the Kitematic GUI, see the [Kitematic user
guide](https://docs.docker.com/kitematic/userguide/).
> **Note**: The Boot2Docker command line was deprecated several releases > back in favor of Docker Machine, and now Docker for Windows.

2
docs/tutorials/dockerimages.md
View file

@ -8,7 +8,7 @@ title = "Build your own images"
description = "How to work with Docker images."
keywords = ["documentation, docs, the docker guide, docker guide, docker, docker platform, docker.io, Docker images, Docker image, image management, Docker repos, Docker repositories, docker, docker tag, docker tags, Docker Hub, collaboration"]
[menu.main]
parent = "engine_learn"
parent = "engine_learn_menu"
weight = -4
+++
<![end-metadata]-->

2
docs/tutorials/dockerizing.md
View file

@ -8,7 +8,7 @@ title = "Hello world in a container"
description = "A simple 'Hello world' exercise that introduced you to Docker."
keywords = ["docker guide, docker, docker platform, how to, dockerize, dockerizing apps, dockerizing applications, container, containers"]
[menu.main]
parent = "engine_learn"
parent = "engine_learn_menu"
weight=-6
+++
<![end-metadata]-->

2
docs/tutorials/dockerrepos.md
View file

@ -8,7 +8,7 @@ title = "Store images on Docker Hub"
description = "Learn how to use the Docker Hub to manage Docker images and work flow"
keywords = ["repo, Docker Hub, Docker Hub, registry, index, repositories, usage, pull image, push image, image, documentation"]
[menu.main]
parent = "engine_learn"
parent = "engine_learn_menu"
+++
<![end-metadata]-->

2
docs/tutorials/dockervolumes.md
View file

@ -8,7 +8,7 @@ title = "Manage data in containers"
description = "How to manage data inside your Docker containers."
keywords = ["Examples, Usage, volume, docker, documentation, user guide, data, volumes"]
[menu.main]
parent = "engine_learn"
parent = "engine_learn_menu"
+++
<![end-metadata]-->

3
docs/tutorials/index.md
View file

@ -6,9 +6,8 @@ aliases = [
title = "Learn by example"
description = "Explains how to work with containers"
keywords = ["docker, introduction, documentation, about, technology, docker.io, user, guide, user's, manual, platform, framework, home, intro"]
[menu.main]
identifier="engine_learn"
parent = "engine_use"
parent = "engine_learn_menu"
weight="-80"
+++
<![end-metadata]-->

16
docs/tutorials/menu.md Normal file
View file

@ -0,0 +1,16 @@
<!--[metadata]>
+++
aliases = [
]
title = "Learn by example"
description = "Explains how to work with containers"
keywords = ["docker, introduction, documentation, about, technology, docker.io, user, guide, user's, manual, platform, framework, home, intro"]
type = "menu"
[menu.main]
identifier = "engine_learn_menu"
parent = "engine_use"
weight = -79
+++
<![end-metadata]-->
# Learn by example

2
docs/tutorials/networkingcontainers.md
View file

@ -8,7 +8,7 @@ title = "Network containers"
description = "How to network Docker containers."
keywords = ["Examples, Usage, volume, docker, documentation, user guide, data, volumes"]
[menu.main]
parent = "engine_learn"
parent = "engine_learn_menu"
weight = -3
+++
<![end-metadata]-->

2
docs/tutorials/usingdocker.md
View file

@ -7,7 +7,7 @@ title = "Run a simple application"
description = "Learn how to manage and operate Docker containers."
keywords = ["docker, the docker guide, documentation, docker.io, monitoring containers, docker top, docker inspect, docker port, ports, docker logs, log, Logs"]
[menu.main]
parent = "engine_learn"
parent = "engine_learn_menu"
weight=-5
+++
<![end-metadata]-->

4
docs/userguide/index.md
View file

@ -1,12 +1,12 @@
<!--[metadata]>
+++
title = "User guide"
title = "User Guide"
description = "How to use the Docker Engine user guide"
keywords = ["engine, introduction, documentation, about, technology, docker, user, guide, framework, home, intro"]
[menu.main]
parent="engine_use"
identifier = "engine_guide"
weight="-79"
weight="-78"
+++
<![end-metadata]-->