docker
/
docs
mirror of https://github.com/docker/docs.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

WIP: improve intro to machine docs 

WIP: rewrite of Machine overview for clarity, add diagrams

rewrite/re-organize Machine topics; incl. get started on local VM, menu order, titles

replaced Swarm info in cloud doc to reference new Swarm provisioning topic per @moxigirl, incorporated review comments per Chanwit into Concepts topic

added mention of Swarm clusters to Overview, and links to Swarm topics in What's next for Overview and Concepts

updates to concepts per @bfirsh comments

updated cloud provisioning topic to illustrated, step-by-step version added for cloud installs per issue #18282

cleanup of links, copy-edits

update to concepts, added link to boot2docker repo and re-worded per Nathan's comments

updates to concepts and cloud example per @dmp42 comments

updated for links and improved intro content for cloud topic

Signed-off-by: Victoria Bialas <victoria.bialas@docker.com>
This commit is contained in:
Victoria Bialas 2016-01-28 13:05:21 -08:00
parent 279fd7ca3f
commit 63f8f1fb48
18 changed files with 471 additions and 362 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
docs/completion.md
View File

@ -57,7 +57,8 @@ Then reload your shell
exec $SHELL -l exec $SHELL -l
--> -->
<!--[metadata]>
## Available completions ## Available completions
**TODO** **TODO**
<![end-metadata]-->

88
docs/concepts.md Normal file
View File

@ -0,0 +1,88 @@
<!--[metadata]>
+++
title = "Machine concepts and help"
description = "Understand concepts for Docker Machine, including drivers, base OS, IP addresses, environment variables"
keywords = ["docker, machine, amazonec2, azure, digitalocean, google, openstack, rackspace, softlayer, virtualbox, vmwarefusion, vmwarevcloudair, vmwarevsphere, exoscale"]
[menu.main]
parent="workw_machine"
weight=3
+++
<![end-metadata]-->
# Understand Machine concepts and get help
Docker Machine allows you to provision Docker machines in a variety of environments, including virtual machines that reside on your local system, on cloud providers, or on bare metal servers (physical computers). Docker Machine creates a Docker host, and you use the Docker Engine client as needed to build images and create containers on the host.
## Drivers for creating machines
To create a virtual machine, you supply Docker Machine with the name of the driver you want use. The driver determines where the virtual machine is created. For example, on a local Mac or Windows system, the driver is typically Oracle VirtualBox. For provisioning physical machines, a generic driver is provided. For cloud providers, Docker Machine supports drivers such as AWS, Microsoft Azure, Digital Ocean, and many more. The Docker Machine reference includes a complete [list of supported drivers](drivers/index.md).
## Default base operating systems for local and cloud hosts
Since Docker runs on Linux, each VM that Docker Machine provisions relies on a
base operating system. For convenience, there are default base operating
systems. For the Oracle Virtual Box driver, this base operating system is <a href="https://github.com/boot2docker/boot2docker" target="_blank">boot2docker</a>. For drivers used to connect to cloud providers, the base operating system is Ubuntu 12.04+. You can change this default when you create a machine. The Docker Machine reference includes a complete [list of
supported operating systems](drivers/os-base.md).
## IP addresses for Docker hosts
For each machine you create, the Docker host address is the IP address of the
Linux VM. This address is assigned by the `docker-machine create` subcommand.
You use the `docker-machine ls` command to list the machines you have created.
The `docker-machine ip <machine-name>` command returns a specific host's IP
address.
## Configuring CLI environment variables for a Docker host
Before you can run a `docker` command on a machine, you need to configure your
command-line to point to that machine. The `docker-machine env <machine-name>`
subcommand outputs the configuration command you should use.
For a complete list of `docker-machine` subcommands, see the [Docker Machine subcommand reference](reference/index.md).
## Crash Reporting
Provisioning a host is a complex matter that can fail for a lot of reasons. Your
workstation may have a wide variety of shell, network configuration, VPN, proxy
or firewall issues. There are also reasons from the other end of the chain:
your cloud provider or the network in between.
To help `docker-machine` be as stable as possible, we added a monitoring of
crashes whenever you try to `create` or `upgrade` a host. This will send, over
HTTPS, to Bugsnag some information about your `docker-machine` version, build,
OS, ARCH, the path to your current shell and, the history of the last command as
you could see it with a `--debug` option. This data is sent to help us pinpoint
recurring issues with `docker-machine` and will only be transmitted in the case
of a crash of `docker-machine`.
If you wish to opt out of error reporting, you can create a `no-error-report`
file in your `$HOME/.docker/machine` directory, and Docker Machine will disable
this behavior. e.g.:
$ mkdir -p ~/.docker/machine && touch ~/.docker/machine/no-error-report
Leaving the file empty is fine -- Docker Machine just checks for its presence.
## Getting help
Docker Machine is still in its infancy and under active development. If you need
help, would like to contribute, or simply want to talk about the project with
like-minded individuals, we have a number of open channels for communication.
- To report bugs or file feature requests: please use the [issue tracker on
Github](https://github.com/docker/machine/issues).
- To talk about the project with people in real time: please join the
`#docker-machine` channel on IRC.
- To contribute code or documentation changes: please [submit a pull request on
Github](https://github.com/docker/machine/pulls).
For more information and resources, please visit
[our help page](https://docs.docker.com/project/get-help/).
## Where to go next
- Create and run a Docker host on your [local system using VirtualBox](get-started.md)
- Provision multiple Docker hosts [on your cloud provider](get-started-cloud.md)
- <a href="../drivers/" target="_blank">Docker Machine driver reference</a>
- <a href="../reference/" target="_blank">Docker Machine subcommand reference</a>

292
docs/get-started-cloud.md
View File

@ -1,7 +1,7 @@
<!--[metadata]> <!--[metadata]>
+++ +++
title = "Use Machine with a cloud provider" title = "Provision hosts on a cloud provider"
description = "Using Docker Machine with a cloud provider" description = "Using Docker Machine to provision hosts on cloud providers"
keywords = ["docker, machine, amazonec2, azure, digitalocean, google, openstack, rackspace, softlayer, virtualbox, vmwarefusion, vmwarevcloudair, vmwarevsphere, exoscale"] keywords = ["docker, machine, amazonec2, azure, digitalocean, google, openstack, rackspace, softlayer, virtualbox, vmwarefusion, vmwarevcloudair, vmwarevsphere, exoscale"]
[menu.main] [menu.main]
parent="workw_machine" parent="workw_machine"
@ -9,176 +9,214 @@ weight=2
+++ +++
<![end-metadata]--> <![end-metadata]-->
## Use Docker Machine with a cloud provider ## Use Docker Machine to provision hosts on a cloud provider
Creating a local virtual machine running Docker is useful and fun, but it isn't the only thing Docker Machine can do. Docker Machine supports several Docker Machine driver plugins are available for many cloud platforms, so you can use Machine to provision cloud hosts. When you use Docker Machine for provisioning, you create cloud hosts with Docker Engine installed on them.
“drivers” which let you use the same interface to create hosts on many different
cloud or local virtualization platforms.
To provision hosts, you use the You'll need to install and run Docker Machine, and create an account with the cloud provider.
`docker-machine create` command with the `--driver` flag. Here is example of using the [Digital Ocean](https://digitalocean.com) driver (`digitalocean`) to provision a host on that platform, but there are drivers included for several providers including
Amazon Web Services, Google Compute Engine, and Microsoft Azure.
Typically, you provide account verification and security credentials for these providers as flags to `docker-machine create`. These flags are unique for each Then you provide account verification, security credentials, and configuration options for the providers as flags to `docker-machine create`. The flags are unique for each cloud-specific driver. For instance, to pass a Digital Ocean access token you use the `--digitalocean-access-token` flag.
driver. For instance, to pass a Digital Ocean access token you use the
`--digitalocean-access-token` flag.
Let's take a look at how to do this on Digital Ocean. ## The docker-machine create command
The `docker-machine create` command typically requires that you specify, at a minimum:
* `--driver` - to indicate the provider on which to create the machine (VirtualBox, DigitalOcean, AWS, and so on)
* Account verification and security credentials (for cloud providers), specific to the cloud service you are using
* `<machine>` - name of the host you want to create
See the <a href="../reference/create/" target="_blank">create</a> command in the Machine <a href="../reference/" target="_blank">command line reference</a> for more information.
## Drivers for providers
When you install Docker Machine, you get a set of drivers for various cloud providers (like Amazon Web Services, Digital Ocean, or Microsoft Azure) and local providers (like Oracle VirtualBox, VMWare Fusion, or Microsoft Hyper-V).
See <a href="../drivers/" target="_blank">Docker Machine driver reference</a> for details on the drivers, including required flags and configuration options (which vary by provider).
## Digital Ocean example ## Digital Ocean example
As an example, let's take a look at how to create a Dockerized <a href="https://digitalocean.com" target="_blank">Digital Ocean</a> _Droplet_ (cloud server).
### Step 1. Create a Digital Ocean account and log in
If you have not done so already, go to <a href="https://digitalocean.com" target="_blank">Digital Ocean</a>, create an account, and log in.
### Step 2. Generate a personal access token
To generate your access token: To generate your access token:
1. Go to the Digital Ocean administrator console and click on "API" in the header. 1. Go to the Digital Ocean administrator console and click **API** in the header.
2. Click on "Generate New Token".
3. Give the token a clever name (e.g. "machine"), make sure the "Write" checkbox
is checked, and click on "Generate Token".
4. Grab the big long hex string that is generated (this is your token) and store
it somewhere safe.
Now, run `docker-machine create` with the `digitalocean` driver and pass your key to ![Click API in Digital Ocean console](img/ocean_click_api.png)
the `--digitalocean-access-token` flag.
Example: 2. Click **Generate New Token** to get to the token generator.
$ docker-machine create \ ![Generate token](img/ocean_gen_token.png)
--driver digitalocean \
--digitalocean-access-token 0ab77166d407f479c6701652cee3a46830fef88b8199722b87821621736ab2d4 \
staging
Creating SSH key...
Creating Digital Ocean droplet...
To see how to connect Docker to this machine, run: docker-machine env staging
For convenience, `docker-machine` will use sensible defaults for choosing 3. Give the token a clever name (e.g. "machine"), make sure the **Write (Optional)** checkbox is checked, and click **Generate Token**.
settings such as the image that the VPS is based on, but they can also be
overridden using their respective flags (e.g. `--digitalocean-image`). This is
useful if, for instance, you want to create a nice large instance with a lot of
memory and CPUs (by default `docker-machine` creates a small VPS). For a full
list of the flags/settings available and their defaults, see the output of
`docker-machine create -h`.
When the creation of a host is initiated, a unique SSH key for accessing the ![Name and generate token](img/ocean_token_create.png)
host (initially for provisioning, then directly later if the user runs the
`docker-machine ssh` command) will be created automatically and stored in the
client's directory in `~/.docker/machines`. After the creation of the SSH key,
Docker will be installed on the remote machine and the daemon will be configured
to accept remote connections over TCP using TLS for authentication. Once this
is finished, the host is ready for connection.
To prepare the Docker client to send commands to the remote server we have 4. Grab (copy to clipboard) the generated big long hex string and store it somewhere safe.
created, we can use the subshell method again:
$ eval "$(docker-machine env staging)" ![Copy and save personal access token](img/ocean_save_token.png)
From this point, the remote host behaves much like the local host we created in the last section. If we look at `docker-machine ls`, we'll see it is now the This is the personal access token you'll use in the next step to create your cloud server.
"active" host, indicated by an asterisk (`*`) in that column:
### Step 3. Use Machine to Create the Droplet
1. Run `docker-machine create` with the `digitalocean` driver and pass your key to the `--digitalocean-access-token` flag, along with a name for the new cloud server.
For this example, we'll call our new Droplet "docker-sandbox".
$ docker-machine create --driver digitalocean --digitalocean-access-token xxxxx docker-sandbox
Running pre-create checks...
Creating machine...
(docker-sandbox) OUT | Creating SSH key...
(docker-sandbox) OUT | Creating Digital Ocean droplet...
(docker-sandbox) OUT | Waiting for IP address to be assigned to the Droplet...
Waiting for machine to be running, this may take a few minutes...
Machine is running, waiting for SSH to be available...
Detecting operating system of created instance...
Detecting the provisioner...
Provisioning created instance...
Copying certs to the local machine directory...
Copying certs to the remote machine...
Setting Docker configuration on the remote daemon...
To see how to connect Docker to this machine, run: docker-machine env docker-sandbox
When the Droplet is created, Docker generates a unique SSH key and stores it on your local system in `~/.docker/machines`. Initially, this is used to provision the host. Later, it's used under the hood to access the Droplet directly with the `docker-machine ssh` command. Docker Engine is installed on the cloud server and the daemon is configured to accept remote connections over TCP using TLS for authentication.
2. Go to the Digital Ocean console to view the new Droplet.
![Droplet in Digital Ocean created with Machine](img/ocean_droplet.png)
3. At the command terminal, run `docker-machine ls`.
$ docker-machine ls $ docker-machine ls
NAME ACTIVE DRIVER STATE URL NAME ACTIVE DRIVER STATE URL SWARM
dev - virtualbox Running tcp://192.168.99.103:2376 default * virtualbox Running tcp://192.168.99.100:2376
staging * digitalocean Running tcp://203.0.113.81:2376 docker-sandbox - digitalocean Running tcp://45.55.139.48:2376
To remove a host and all of its containers and images, use `docker-machine rm`: Notice that the new cloud server is running but is not the active host. Our command shell is still connected to the default machine, which is currently the active host as indicated by the asterisk (*).
$ docker-machine rm dev staging 4. Run `docker-machine env docker-sandbox` to get the environment commands for the new remote host, then run `eval` as directed to re-configure the shell to connect to `docker-sandbox`.
Do you really want to remove "dev"? (y/n): y
Successfully removed dev $ docker-machine env docker-sandbox
Do you really want to remove "staging"? (y/n): y export DOCKER_TLS_VERIFY="1"
Successfully removed staging export DOCKER_HOST="tcp://45.55.222.72:2376"
export DOCKER_CERT_PATH="/Users/victoriabialas/.docker/machine/machines/docker-sandbox"
export DOCKER_MACHINE_NAME="docker-sandbox"
# Run this command to configure your shell:
# eval "$(docker-machine env docker-sandbox)"
5. Re-run `docker-machine ls` to verify that our new server is the active machine, as indicated by the asterisk (*) in the ACTIVE column.
$ docker-machine ls $ docker-machine ls
NAME ACTIVE DRIVER STATE URL NAME ACTIVE DRIVER STATE URL SWARM
default - virtualbox Running tcp://192.168.99.100:2376
docker-sandbox * digitalocean Running tcp://45.55.222.72:2376
6. Run some `docker-machine` commands to inspect the remote host. For example, `docker-machine ip <machine>` gets the host IP adddress and `docker-machine inspect <machine>` lists all the details.
$ docker-machine ip docker-sandbox
104.131.43.236
$ docker-machine inspect docker-sandbox
{
"ConfigVersion": 3,
"Driver": {
"IPAddress": "104.131.43.236",
"MachineName": "docker-sandbox",
"SSHUser": "root",
"SSHPort": 22,
"SSHKeyPath": "/Users/samanthastevens/.docker/machine/machines/docker-sandbox/id_rsa",
"StorePath": "/Users/samanthastevens/.docker/machine",
"SwarmMaster": false,
"SwarmHost": "tcp://0.0.0.0:3376",
"SwarmDiscovery": "",
...
7. Verify Docker Engine is installed correctly by running `docker` commands.
Start with something basic like `docker run hello-world`, or for a more interesting test, run a Dockerized webserver on your new remote machine.
In this example, the `-p` option is used to expose port 80 from the `nginx` container and make it accessible on port `8000` of the `docker-sandbox` host.
$ docker run -d -p 8000:80 --name webserver kitematic/hello-world-nginx
Unable to find image 'kitematic/hello-world-nginx:latest' locally
latest: Pulling from kitematic/hello-world-nginx
a285d7f063ea: Pull complete
2d7baf27389b: Pull complete
...
Digest: sha256:ec0ca6dcb034916784c988b4f2432716e2e92b995ac606e080c7a54b52b87066
Status: Downloaded newer image for kitematic/hello-world-nginx:latest
942dfb4a0eaae75bf26c9785ade4ff47ceb2ec2a152be82b9d7960e8b5777e65
In a web browser, go to `http://<host_ip>:8000` to bring up the webserver home page. You got the `<host_ip>` from the output of the `docker-machine ip <machine>` command you ran in a previous step. Use the port you exposed in the `docker run` command.
![nginx webserver](img/nginx-webserver.png)
#### Understand the defaults and options on the create command
For convenience, `docker-machine` will use sensible defaults for choosing settings such as the image that the server is based on, but you override the defaults using the respective flags (e.g. `--digitalocean-image`). This is useful if, for example, you want to create a cloud server with a lot of memory and CPUs (by default `docker-machine` creates a small server). For a full list of the flags/settings available and their defaults, see the output of `docker-machine create -h` at the command line. See also <a href="https://docs.docker.com/machine/drivers/os-base/" target="_blank">Driver options and operating system defaults</a> and information about the <a href="https://docs.docker.com/machine/reference/create/" target="_blank">create</a> command in the Docker Machine documentation.
### Step 4. Use Machine to remove the Droplet
To remove a host and all of its containers and images, first stop the machine, then use `docker-machine rm`:
$ docker-machine stop docker-sandbox
$ docker-machine rm docker-sandbox
Do you really want to remove "docker-sandbox"? (y/n): y
Successfully removed docker-sandbox
$ docker-machine ls
NAME ACTIVE DRIVER STATE URL SWARM
default * virtualbox Running tcp:////xxx.xxx.xx.xxx:xxxx
If you monitor the Digital Ocean console while you run these commands, you will see it update first to reflect that the Droplet was stopped, and then removed.
If you create a host with Docker Machine, but remove it through the cloud provider console, Machine will lose track of the server status. So please use the `docker-machine rm` command for hosts you create with `docker-machine --create`.
### Docker supported drivers ### Docker supported drivers
Docker Machine drivers are available for several other cloud providers. For a full list, see [Supported Drivers](https://docs.docker.com/machine/drivers/). Docker Machine drivers are available for several other cloud providers. For a full list, see <a href="https://docs.docker.com/machine/drivers/" target="_blank">Supported Drivers</a>.
### Docker Machine command and driver reference ### Docker Machine command and driver reference
- `docker-machine` [create](https://docs.docker.com/machine/reference/create/) command - `docker-machine` <a href="https://docs.docker.com/machine/reference/create/" target="_blank">create</a> command
- [Driver options and operating system defaults](https://docs.docker.com/machine/drivers/os-base/) - <a href="https://docs.docker.com/machine/drivers/os-base/" target="_blank">Driver options and operating system defaults</a>
### 3rd-party driver plugins ### 3rd-party driver plugins
Several Docker Machine driver plugins for use with other cloud platforms are available from 3rd party contributors. These are use-at-your-own-risk plugins, not maintained by or formally associated with Docker. Several Docker Machine driver plugins for use with other cloud platforms are available from 3rd party contributors. These are use-at-your-own-risk plugins, not maintained by or formally associated with Docker.
See [Available driver plugins](https://github.com/docker/machine/blob/master/docs/AVAILABLE_DRIVER_PLUGINS.md) in the docker/machine repo on GitHub. See <a href="https://github.com/docker/machine/blob/master/docs/AVAILABLE_DRIVER_PLUGINS.md" target="_blank">Available driver plugins</a> in the docker/machine repo on GitHub.
## Adding a host without a driver ## Adding a host without a driver
You can add a host to Docker which only has a URL and no driver. Therefore it can be used an alias for an existing host so you don’t have to type out the URL every time you run a Docker command. You can add a host to Docker which only has a URL and no driver. Then you can use the machine name you provide here for an existing host so you don’t have to type out the URL every time you run a Docker command.
$ docker-machine create --url=tcp://50.134.234.20:2376 custombox $ docker-machine create --url=tcp://50.134.234.20:2376 custombox
$ docker-machine ls $ docker-machine ls
NAME ACTIVE DRIVER STATE URL NAME ACTIVE DRIVER STATE URL
custombox * none Running tcp://50.134.234.20:2376 custombox * none Running tcp://50.134.234.20:2376
## Using Docker Machine with Docker Swarm ## Using Machine to provision Docker Swarm clusters
Docker Machine can also provision [Swarm](https://github.com/docker/swarm) Docker Machine can also provision <a href="https://docs.docker.com/swarm/" target="_blank">Docker Swarm</a> clusters. This can be used with any driver and will be secured with TLS.
clusters. This can be used with any driver and will be secured with TLS.
First, create a Swarm token. Optionally, you can use another discovery service. * To get started with Swarm, see <a href="https://docs.docker.com/swarm/machine-provisioning/how-to-get-swarm/" target="_blank">Get and run the Swarm software</a>.
See the Swarm docs for details.
To create the token, first create a Machine. This example will use VirtualBox. * To learn how to use Machine to provision a Swarm cluster, see <a href="https://docs.docker.com/swarm/machine-provisioning/provision-w-machine/" target="_blank">Provision a Swarm cluster with Docker Machine</a>.
$ docker-machine create -d virtualbox local ## Where to go next
Load the Machine configuration into your shell: - [Understand Machine concepts](concepts.md)
- <a href="../drivers/" target="_blank">Docker Machine driver reference</a>
$ eval "$(docker-machine env local)" - <a href="../reference/" target="_blank">Docker Machine subcommand reference</a>
- <a href="https://docs.docker.com/swarm/machine-provisioning/provision-w-machine/" target="_blank">Provision a Docker Swarm cluster with Docker Machine</a>
Then run generate the token using the Swarm Docker image:
$ docker run swarm create
1257e0f0bbb499b5cd04b4c9bdb2dab3
Once you have the token, you can create the cluster.
### Swarm master
Create the Swarm master:
docker-machine create \
-d virtualbox \
--swarm \
--swarm-master \
--swarm-discovery token://<TOKEN-FROM-ABOVE> \
swarm-master
Replace `<TOKEN-FROM-ABOVE>` with your random token.
This will create the Swarm master and add itself as a Swarm node.
### Swarm nodes
Now, create more Swarm nodes:
docker-machine create \
-d virtualbox \
--swarm \
--swarm-discovery token://<TOKEN-FROM-ABOVE> \
swarm-node-00
You now have a Swarm cluster across two nodes.
To connect to the Swarm master, use `eval $(docker-machine env --swarm swarm-master)`
For example:
$ docker-machine env --swarm swarm-master
export DOCKER_TLS_VERIFY=1
export DOCKER_CERT_PATH="/home/ehazlett/.docker/machines/.client"
export DOCKER_HOST=tcp://192.168.99.100:3376
You can load this into your environment using
`eval "$(docker-machine env --swarm swarm-master)"`.
Now you can use the Docker CLI to query:
$ docker info
Containers: 1
Nodes: 1
swarm-master: 192.168.99.100:2376
└ Containers: 2
└ Reserved CPUs: 0 / 4
└ Reserved Memory: 0 B / 999.9 MiB

139
docs/get-started.md
View File

@ -1,6 +1,6 @@
<!--[metadata]> <!--[metadata]>
+++ +++
title = "Get started with Machine and a local VM" title = "Get started with a local VM"
description = "Get started with Docker Machine and a local VM" description = "Get started with Docker Machine and a local VM"
keywords = ["docker, machine, virtualbox, local"] keywords = ["docker, machine, virtualbox, local"]
[menu.main] [menu.main]
@ -12,33 +12,53 @@ weight=1
# Get started with Docker Machine and a local VM # Get started with Docker Machine and a local VM
Let's take a look at using `docker-machine` for creating, using, and managing a Let's take a look at using `docker-machine` for creating, using, and managing a
Docker host inside of [VirtualBox](https://www.virtualbox.org/). Docker host inside of <a href=
"https://www.virtualbox.org/" target="_blank">VirtualBox</a>.
First, ensure that [the latest ## Prerequisites
VirtualBox](https://www.virtualbox.org/wiki/Downloads) is correctly installed
on your system.
If you run the `docker-machine ls` command to show all available machines, you * Make sure you have <a href="https://www.virtualbox.org/wiki/Downloads" target="_blank">the latest VirtualBox</a> correctly installed
will see that none have been created so far. on your system. If you used <a href="https://www.docker.com/products/docker-toolbox" target="_blank">Toolbox</a> for <a href="https://docs.docker.com/engine/installation/mac/" target="_blank">Mac</a> or <a href="https://docs.docker.com/engine/installation/windows/" target="_blank">Windows</a> to install Docker Machine, VirtualBox is automatically installed.
* If you used the Quickstart Terminal to launch your first machine and set your terminal environment to point to it, a default machine was automatically created. If this is the case, you can still follow along with these steps, but create another machine and name it something other than "default" (e.g., staging or sandbox).
## Use Machine to run Docker containers
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.
The examples here show how to create and start a machine, run Docker commands, and work with containers.
## Create a machine
1. Open a command shell or terminal window.
These command examples shows a Bash shell. For a different shell, such as C Shell, the same commands are the same except where noted.
2. Use `docker-machine ls` to list available machines.
In this example, no machines have been created yet.
$ docker-machine ls $ docker-machine ls
NAME ACTIVE DRIVER STATE URL SWARM DOCKER ERRORS NAME ACTIVE DRIVER STATE URL SWARM DOCKER ERRORS
To create one, we run the `docker-machine create` command, passing the string 3. Create a machine.
`virtualbox` to the `--driver` flag. The final argument we pass is the name of
the machine - in this case, we will name our machine "default".
This command will download a lightweight Linux distribution Run the `docker-machine create` command, passing the string `virtualbox` to the `--driver` flag. The final argument is the name of the machine. If this is your first machine, name it `default`. If you already have a "default" machine, choose another name for this new machine.
([boot2docker](https://github.com/boot2docker/boot2docker)) with the Docker
daemon installed, and will create and start a VirtualBox VM with Docker
running.
$ docker-machine create --driver virtualbox default $ docker-machine create --driver virtualbox default
Running pre-create checks... Running pre-create checks...
Creating machine... Creating machine...
(default) Creating VirtualBox VM... (staging) Copying /Users/ripley/.docker/machine/cache/boot2docker.iso to /Users/ripley/.docker/machine/machines/default/boot2docker.iso...
(default) Creating SSH key... (staging) Creating VirtualBox VM...
(default) Starting VM... (staging) Creating SSH key...
(staging) Starting the VM...
(staging) Waiting for an IP...
Waiting for machine to be running, this may take a few minutes... Waiting for machine to be running, this may take a few minutes...
Machine is running, waiting for SSH to be available... Machine is running, waiting for SSH to be available...
Detecting operating system of created instance... Detecting operating system of created instance...
@ -51,30 +71,18 @@ running.
Docker is up and running! Docker is up and running!
To see how to connect Docker to this machine, run: docker-machine env default To see how to connect Docker to this machine, run: docker-machine env default
You can see the machine you have created by running the `docker-machine ls` This command downloads a lightweight Linux distribution
command again: ()<a href="https://github.com/boot2docker/boot2docker" target="_blank">boot2docker</a>) with the Docker daemon installed, and creates and starts a VirtualBox VM with Docker running.
4. List available machines again to see your newly minted machine.
$ docker-machine ls $ docker-machine ls
NAME ACTIVE DRIVER STATE URL SWARM DOCKER ERRORS NAME ACTIVE DRIVER STATE URL SWARM DOCKER ERRORS
default * virtualbox Running tcp://192.168.99.187:2376 v1.9.1 default * virtualbox Running tcp://192.168.99.187:2376 v1.9.1
Next, as noted in the output of the `docker-machine create` command, we have to 5. Get the environment commands for your new VM.
tell Docker to talk to that machine. You can do this with the `docker-machine
env` command. For example,
$ eval "$(docker-machine env default)" As noted in the output of the `docker-machine create` command, you need to tell Docker to talk to the new machine. You can do this with the `docker-machine env` command.
$ docker ps
> **Note**: If you are using `fish`, or a Windows shell such as
> Powershell/`cmd.exe` the above method will not work as described. Instead,
> see [the `env` command's documentation](reference/env.md)
> to learn how to set the environment variables for your shell.
This will set environment variables that the Docker client will read which
specify the TLS settings. Note that you will need to do that every time you
open a new tab or restart your machine.
To see what will be set, we can run `docker-machine env default`.
$ docker-machine env default $ docker-machine env default
export DOCKER_TLS_VERIFY="1" export DOCKER_TLS_VERIFY="1"
@ -84,7 +92,24 @@ To see what will be set, we can run `docker-machine env default`.
# Run this command to configure your shell: # Run this command to configure your shell:
# eval "$(docker-machine env default)" # eval "$(docker-machine env default)"
You can now run Docker commands on this host: 6. Connect your shell to the new machine.
$ eval "$(docker-machine env default)"
**Note**: If you are using `fish`, or a Windows shell such as
Powershell/`cmd.exe` the above method will not work as described.
Instead, see <a href="https://docs.docker.com/machine/reference/env/" target="_blank">the `env` command's documentation</a>
to learn how to set the environment variables for your shell.
This sets environment variables for the current shell that the Docker client will read which specify the TLS settings. You need to do this each time you open a new shell or restart your machine.
You can now run Docker commands on this host.
## Run containers and experiment with Machine commands
Run a container with `docker run` to verify your set up.
1. Use `docker run` to download and run `busybox` with a simple 'echo' command.
$ docker run busybox echo hello world $ docker run busybox echo hello world
Unable to find image 'busybox' locally Unable to find image 'busybox' locally
@ -95,19 +120,18 @@ You can now run Docker commands on this host:
e433a6c5b276: Download complete e433a6c5b276: Download complete
hello world hello world
Any exposed ports are available on the Docker host’s IP address, which you can 2. Get the host IP address.
get using the `docker-machine ip` command:
Any exposed ports are available on the Docker host’s IP address, which you can get using the `docker-machine ip` command:
$ docker-machine ip default $ docker-machine ip default
192.168.99.100 192.168.99.100
For instance, you can try running a webserver ([nginx](https://www.nginx.com/) 3. Run a webserver (<a href="https://www.nginx.com/" target="_blank">nginx</a>) in a container with the following command:
in a container with the following command:
$ docker run -d -p 8000:80 nginx $ docker run -d -p 8000:80 nginx
When the image is finished pulling, you can hit the server at port 8000 on the When the image is finished pulling, you can hit the server at port 8000 on the IP address given to you by `docker-machine ip`. For instance:
IP address given to you by `docker-machine ip`. For instance:
$ curl $(docker-machine ip default):8000 $ curl $(docker-machine ip default):8000
<!DOCTYPE html> <!DOCTYPE html>
@ -136,25 +160,20 @@ IP address given to you by `docker-machine ip`. For instance:
</body> </body>
</html> </html>
You can create and manage as many local VMs running Docker as you please- just You can create and manage as many local VMs running Docker as you please; just run `docker-machine create` again. All created machines will appear in the output of `docker-machine ls`.
run `docker-machine create` again. All created machines will appear in the
output of `docker-machine ls`.
If you are finished using a host for the time being, you can stop it with ## Start and stop machines
`docker-machine stop` and later start it again with `docker-machine start`.
If you are finished using a host for the time being, you can stop it with `docker-machine stop` and later start it again with `docker-machine start`.
$ docker-machine stop default $ docker-machine stop default
$ docker-machine start default $ docker-machine start default
## Operating on machines without specifying the name ## Operate on machines without specifying the name
Some commands will assume that the specified operation should be run on a Some `docker-machine` commands will assume that the given operation should be run on a machine named `default` (if it exists) if no machine name is specified. Because using a local VM named `default` is such a common pattern, this allows you to save some typing on the most frequently used Machine commands.
machine named `default` (if it exists) if no machine name is passed to them as
an argument. Because using a local VM named `default` is such a common pattern,
this allows you to save some typing on Machine commands that may be frequently
invoked.
For instance: For example:
$ docker-machine stop $ docker-machine stop
Stopping "default".... Stopping "default"....
@ -171,7 +190,7 @@ For instance:
$ docker-machine ip $ docker-machine ip
192.168.99.100 192.168.99.100
Commands that will follow this style are: Commands that follow this style are:
- `docker-machine config` - `docker-machine config`
- `docker-machine env` - `docker-machine env`
@ -188,5 +207,11 @@ Commands that will follow this style are:
- `docker-machine upgrade` - `docker-machine upgrade`
- `docker-machine url` - `docker-machine url`
For machines other than `default`, and commands other than those listed above, For machines other than `default`, and commands other than those listed above, you must always specify the name explicitly as an argument.
you must always specify the name explicitly as an argument.
## Where to go next
- Provision multiple Docker hosts [on your cloud provider](get-started-cloud.md)
- [Understand Machine concepts](concepts.md)
- <a href="https://docs.docker.com/machine/drivers/" target="_blank">Docker Machine driver reference</a>
- <a href="https://docs.docker.com/machine/reference/" target="_blank">Docker Machine subcommand reference</a>

BIN
docs/img/docker-engine.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 18 KiB

BIN
docs/img/engine.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 18 KiB

BIN
docs/img/machine-mac-win.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 14 KiB

BIN
docs/img/machine.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 55 KiB

BIN
docs/img/nginx-webserver.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 81 KiB

BIN
docs/img/ocean_click_api.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 36 KiB

BIN
docs/img/ocean_droplet.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 26 KiB

BIN
docs/img/ocean_gen_token.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 42 KiB

BIN
docs/img/ocean_save_token.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 50 KiB

BIN
docs/img/ocean_token_create.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 56 KiB

BIN
docs/img/provision-use-case.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 24 KiB

9
docs/index.md
View File

@ -8,9 +8,14 @@ identifier="workw_machine"
+++ +++
<![end-metadata]--> <![end-metadata]-->
# Docker Machine # Docker Machine
- Install a machine on your [local system using VirtualBox](get-started.md). - [Docker Machine overview](overview.md)
- Install multiple machines [on your cloud provider](get-started-cloud.md). - [Install Docker Machine](install-machine.md)
- Install a machine on your [local system using VirtualBox](get-started.md)
- Install multiple machines [on your cloud provider](get-started-cloud.md)
- [Machine concepts and help](concepts.md)
- [Migrate from Boot2Docker to Docker Machine](migrate-to-machine.md)
- [Docker Machine driver reference](drivers/index.md) - [Docker Machine driver reference](drivers/index.md)
- [Docker Machine subcommand reference](reference/index.md) - [Docker Machine subcommand reference](reference/index.md)

18
docs/install-machine.md
View File

@ -18,10 +18,7 @@ installation</a> instructions or <a
href="https://docs.docker.com/installation/windows" target="_blank">Windows href="https://docs.docker.com/installation/windows" target="_blank">Windows
installation</a> instructions. installation</a> instructions.
If you only want Docker Machine, you can install the Machine binaries (the If you want only Docker Machine, you can install the Machine binaries directly by following the instructions in the next section. You can find the latest versions of the binaries are on the <a href="https://github.com/docker/machine/releases/" target="_blank"> docker/machine release page</a> on GitHub.
latest versions of which are located at
<https://github.com/docker/machine/releases/> ) directly by following the
instructions in the next section.
## Installing Machine Directly ## Installing Machine Directly
@ -41,7 +38,7 @@ instructions in the next section.
curl -L https://github.com/docker/machine/releases/download/v0.6.0/docker-machine-Windows-x86_64.exe > "$HOME/bin/docker-machine.exe" && \ curl -L https://github.com/docker/machine/releases/download/v0.6.0/docker-machine-Windows-x86_64.exe > "$HOME/bin/docker-machine.exe" && \
chmod +x "$HOME/bin/docker-machine.exe" chmod +x "$HOME/bin/docker-machine.exe"
Otherwise, download one of the releases from the [release page](https://github.com/docker/machine/releases/) directly. Otherwise, download one of the releases from the <a href="https://github.com/docker/machine/releases/" target="_blank"> docker/machine release page</a> directly.
3. Check the installation by displaying the Machine version: 3. Check the installation by displaying the Machine version:
@ -64,11 +61,12 @@ prompt, add `$(__docker_machine_ps1)` to your `PS1` setting in `~/.bashrc`.
PS1='[\u@\h \W$(__docker_machine_ps1)]\$ ' PS1='[\u@\h \W$(__docker_machine_ps1)]\$ '
You can find additional documentation in the comments at the You can find additional documentation in the comments at the <a href="https://github.com/docker/machine/tree/master/contrib/completion/bash" target="_blank">top of each script</a>.
[top of each script](https://github.com/docker/machine/tree/master/contrib/completion/bash).
## Where to go next ## Where to go next
- [Docker Machine overview](index.md) - [Docker Machine overview](overview.md)
- [Docker Machine driver reference](drivers/index.md) - Create and run a Docker host on your [local system using VirtualBox](get-started.md)
- [Docker Machine subcommand reference](reference/index.md) - Provision multiple Docker hosts [on your cloud provider](get-started-cloud.md)
- <a href="https://docs.docker.com/machine/drivers/" target="_blank">Docker Machine driver reference</a>
- <a href="https://docs.docker.com/machine/reference/" target="_blank">Docker Machine subcommand reference</a>

112
docs/overview.md
View File

@ -1,6 +1,6 @@
<!--[metadata]> <!--[metadata]>
+++ +++
title = "Overview of Machine" title = "Machine Overview"
description = "Introduction and Overview of Machine" description = "Introduction and Overview of Machine"
keywords = ["docker, machine, amazonec2, azure, digitalocean, google, openstack, rackspace, softlayer, virtualbox, vmwarefusion, vmwarevcloudair, vmwarevsphere, exoscale"] keywords = ["docker, machine, amazonec2, azure, digitalocean, google, openstack, rackspace, softlayer, virtualbox, vmwarefusion, vmwarevcloudair, vmwarevsphere, exoscale"]
[menu.main] [menu.main]
@ -9,105 +9,59 @@ weight=-90
+++ +++
<![end-metadata]--> <![end-metadata]-->
# Overview of Docker Machine
Machine lets you create Docker hosts on your computer, on cloud providers, and # Docker Machine Overview
inside your own data center. It automatically creates hosts, installs Docker on
them, then configures the `docker` client to talk to them. A "machine" is the
combination of a Docker host and a configured client.
Once you create one or more Docker hosts, Docker Machine supplies a number of You can use Docker Machine to:
commands for managing them. Using these commands you can
- start, inspect, stop, and restart a host * Install and run Docker on Mac or Windows
- upgrade the Docker client and daemon * Provision and manage multiple remote Docker hosts
- configure a Docker client to talk to your host * Provision Swarm clusters
### Looking for the installation docs? ## What is Docker Machine?
Docker Machine is a tool that lets you install Docker Engine on virtual hosts, and manage the hosts with `docker-machine` commands. You can use Machine to create Docker hosts on your local Mac or Windows box, on your company network, in your data center, or on cloud providers like AWS or Digital Ocean.
For Windows or Mac, you can obtain Docker Machine by installing the [Docker Using `docker-machine` commands, you can start, inspect, stop, and restart a managed host, upgrade the Docker client and daemon, and configure a Docker client to talk to your host.
Toolbox](https://www.docker.com/toolbox). To read instructions for installing
Machine on Linux or for installing Machine alone without Docker Toolbox, see the
[Machine installation instructions](install-machine.md).
## Understand Docker Machine basic concepts Point the Machine CLI at a running, managed host, and you can run `docker` commands directly on that host. For example, run `docker-machine env default` to point to a host called `default`, follow on-screen instructions to complete `env` setup, and run `docker ps`, `docker run hello-world`, and so forth.
Docker Machine allows you to provision Docker on virtual machines that reside ## Why should I use it?
either on your local system or on a cloud provider. Docker Machine creates a
host on a VM and you use the Docker Engine client as needed to build images and
create containers on the host.
To create a virtual machine, you supply Docker Machine with the name of the Machine is currently the only way to run Docker on Mac or Windows, and the best way to provision multiple remote Docker hosts on various flavors of Linux.
driver you want use. The driver represents the virtual environment. For example,
on a local Linux, Mac, or Windows system the driver is typically Oracle
VirtualBox. For cloud providers, Docker Machine supports drivers such as AWS,
Microsoft Azure, Digital Ocean and many more. The Docker Machine reference
includes a complete [list of the supported drivers](drivers/index.md).
Since Docker runs on Linux, each VM that Docker Machine provisions relies on a Docker Machine has these two broad use cases.
base operating system. For convenience, there are default base operating
systems. For the Oracle Virtual Box driver, this base operating system is the
`boot2docker.iso`. For drivers used to connect to cloud providers, the base
operating system is Ubuntu 15.10. You can change this default when you create a
machine. The Docker Machine reference includes a complete [list of the supported
operating systems](drivers/os-base.md).
For each machine you create, the Docker host address is the IP address of the * **I want to run Docker on Mac or Windows**
Linux VM. This address is assigned by the `docker-machine create` subcommand.
You use the `docker-machine ls` command to list the machines you have created.
The `docker-machine ip <machine-name>` command returns a specific host's IP
address.
Before you can run a `docker` command on a machine, you configure your ![Docker Machine on Mac and Windows](img/machine-mac-win.png)
command-line to point to that machine. The `docker-machine env <machine-name>`
subcommand outputs the configuration command you should use. When you run a
container on the Docker host, the container's ports map to ports on the VM.
For a complete list of the `docker-machine` subcommands, see the [Docker Machine If you work primarily on a Mac or Windows laptop or desktop, you need Docker Machine in order to "run Docker" (that is, Docker Engine) locally. Installing Docker Machine on a Mac or Windows box provisions a local virtual machine with Docker Engine, gives you the ability to connect it, and run `docker` commands.
subcommand reference](reference/index.md).
## Crash Reporting * **I want to provision Docker hosts on remote systems**
Provisioning a host is a complex matter that can fail for a lot of reasons. ![Docker Machine for provisioning multiple systems](img/provision-use-case.png)
Your workstation may have a wide variety of shell, network configuration, VPN,
proxy or firewall issues. There are also reasons from the other end of the
chain: your cloud provider or the network in between.
To help `docker-machine` be as stable as possible, we added a monitoring of Docker Engine runs natively on Linux systems. If you have a Linux box as your primary system, and want to run `docker` commands, all you need to do is download and install Docker Engine. However, if you want an efficient way to provision multiple Docker hosts on a network, in the cloud or even locally, you need Docker Machine.
crashes whenever you try to `create` or `upgrade` a host. This will send, over
HTTPS, to Bugsnag some information about your `docker-machine` version, build,
OS, ARCH, the path to your current shell and, the history of the last command as
you could see it with a `--debug` option. This data is sent to help us pinpoint
recurring issues with `docker-machine` and will only be transmitted in the case
of a crash of `docker-machine`.
If you wish to opt out of error reporting, you can create a `no-error-report` Whether your primary system is Mac, Windows, or Linux, you can install Docker Machine on it and use `docker-machine` commands to provision and manage large numbers of Docker hosts. It automatically creates hosts, installs Docker Engine on them, then configures the `docker` clients. Each managed host ("**_machine_**") is the combination of a Docker host and a configured client.
file in your `$HOME/.docker/machine` directory, and Docker Machine will disable
this behavior. e.g.:
$ mkdir -p ~/.docker/machine && touch ~/.docker/machine/no-error-report ## What's the difference between Docker Engine and Docker Machine?
Leaving the file empty is fine -- Docker Machine just checks for its presence. When people say "Docker" they typically mean **Docker Engine**, the client-server application made up of the Docker daemon, a REST API that specifies interfaces for interacting with the daemon, and a command line interface (CLI) client that talks to the daemon (through the REST API wrapper). Docker Engine accepts `docker` commands from the CLI, such as `docker run <image>`, `docker ps` to list running containers, `docker images` to list images, and so on.
## Getting help ![Docker Engine](img/engine.png)
Docker Machine is still in its infancy and under active development. If you need **Docker Machine** is a tool for provisioning and managing your Dockerized hosts (hosts with Docker Engine on them). Typically, you install Docker Machine on your local system. Docker Machine has its own command line client `docker-machine` and the Docker Engine client, `docker`. You can use Machine to install Docker Engine on one or more virtual systems. These virtual systems can be local (as when you use Machine to install and run Docker Engine in VirtualBox on Mac or Windows) or remote (as when you use Machine to provision Dockerized hosts on cloud providers). The Dockerized hosts themselves can be thought of, and are sometimes referred to as, managed "**_machines_**".
help, would like to contribute, or simply want to talk about the project with
like-minded individuals, we have a number of open channels for communication.
- To report bugs or file feature requests: please use the [issue tracker on ![Docker Machine](img/machine.png)
Github](https://github.com/docker/machine/issues).
- To talk about the project with people in real time: please join the
`#docker-machine` channel on IRC.
- To contribute code or documentation changes: please [submit a pull request on
Github](https://github.com/docker/machine/pulls).
For more information and resources, please visit
[our help page](https://docs.docker.com/project/get-help/).
## Where to go next ## Where to go next
- Install a machine on your [local system using VirtualBox](get-started.md). - [Install Docker Machine](install-machine.md)
- Install multiple machines [on your cloud provider](get-started-cloud.md). - Create and run a Docker host on your [local system using VirtualBox](get-started.md)
- [Docker Machine driver reference](drivers/index.md) - Provision multiple Docker hosts [on your cloud provider](get-started-cloud.md)
- [Docker Machine subcommand reference](reference/index.md) - [Provision a Docker Swarm cluster with Docker Machine](https://docs.docker.com/swarm/machine-provisioning/provision-w-machine/)
- [Understand Machine concepts](concepts.md)
- <a href="https://docs.docker.com/machine/drivers/" target="_blank">Docker Machine driver reference</a>
- <a href="https://docs.docker.com/machine/reference/" target="_blank">Docker Machine subcommand reference</a>
- [Migrate from Boot2Docker to Docker Machine](migrate-to-machine.md)