diff --git a/docs/completion.md b/docs/completion.md index 0bcc1d397d..f7674e3d7a 100644 --- a/docs/completion.md +++ b/docs/completion.md @@ -57,7 +57,8 @@ Then reload your shell exec $SHELL -l --> - + diff --git a/docs/concepts.md b/docs/concepts.md new file mode 100644 index 0000000000..d80d6945ba --- /dev/null +++ b/docs/concepts.md @@ -0,0 +1,88 @@ + + + +# 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 boot2docker. 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 ` 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 ` +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) +- Docker Machine driver reference +- Docker Machine subcommand reference diff --git a/docs/get-started-cloud.md b/docs/get-started-cloud.md index 306029698b..494affe47c 100644 --- a/docs/get-started-cloud.md +++ b/docs/get-started-cloud.md @@ -1,7 +1,7 @@ -## 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 -“drivers” which let you use the same interface to create hosts on many different -cloud or local virtualization platforms. +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. -To provision hosts, you use the -`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. +You'll need to install and run Docker Machine, and create an account with the cloud provider. -Typically, you provide account verification and security credentials for these providers as flags to `docker-machine create`. These flags are unique for each -driver. For instance, to pass a Digital Ocean access token you use the -`--digitalocean-access-token` flag. +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. -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 + +* `` - name of the host you want to create + +See the create command in the Machine command line reference 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 Docker Machine driver reference for details on the drivers, including required flags and configuration options (which vary by provider). ## Digital Ocean example +As an example, let's take a look at how to create a Dockerized Digital Ocean _Droplet_ (cloud server). + +### Step 1. Create a Digital Ocean account and log in + +If you have not done so already, go to Digital Ocean, create an account, and log in. + +### Step 2. Generate a personal access token + To generate your access token: -1. Go to the Digital Ocean administrator console and click on "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. + 1. Go to the Digital Ocean administrator console and click **API** in the header. -Now, run `docker-machine create` with the `digitalocean` driver and pass your key to -the `--digitalocean-access-token` flag. + ![Click API in Digital Ocean console](img/ocean_click_api.png) -Example: + 2. Click **Generate New Token** to get to the token generator. - $ docker-machine create \ - --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 + ![Generate token](img/ocean_gen_token.png) -For convenience, `docker-machine` will use sensible defaults for choosing -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`. + 3. Give the token a clever name (e.g. "machine"), make sure the **Write (Optional)** checkbox is checked, and click **Generate Token**. -When the creation of a host is initiated, a unique SSH key for accessing the -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. + ![Name and generate token](img/ocean_token_create.png) -To prepare the Docker client to send commands to the remote server we have -created, we can use the subshell method again: + 4. Grab (copy to clipboard) the generated big long hex string and store it somewhere safe. - $ 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 -"active" host, indicated by an asterisk (`*`) in that column: + This is the personal access token you'll use in the next step to create your cloud server. + +### 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 + NAME ACTIVE DRIVER STATE URL SWARM + default * virtualbox Running tcp://192.168.99.100:2376 + docker-sandbox - digitalocean Running tcp://45.55.139.48:2376 + + 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 (*). + +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`. + + $ docker-machine env docker-sandbox + export DOCKER_TLS_VERIFY="1" + 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 + 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 ` gets the host IP adddress and `docker-machine inspect ` 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://:8000` to bring up the webserver home page. You got the `` from the output of the `docker-machine ip ` 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 Driver options and operating system defaults and information about the create 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 - dev - virtualbox Running tcp://192.168.99.103:2376 - staging * digitalocean Running tcp://203.0.113.81:2376 + NAME ACTIVE DRIVER STATE URL SWARM + default * virtualbox Running tcp:////xxx.xxx.xx.xxx:xxxx -To remove a host and all of its containers and images, use `docker-machine rm`: +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. - $ docker-machine rm dev staging - Do you really want to remove "dev"? (y/n): y - Successfully removed dev - Do you really want to remove "staging"? (y/n): y - Successfully removed staging +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-machine ls - NAME ACTIVE DRIVER STATE URL ### 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 Supported Drivers. ### Docker Machine command and driver reference -- `docker-machine` [create](https://docs.docker.com/machine/reference/create/) command -- [Driver options and operating system defaults](https://docs.docker.com/machine/drivers/os-base/) +- `docker-machine` create command +- Driver options and operating system defaults ### 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. - See [Available driver plugins](https://github.com/docker/machine/blob/master/docs/AVAILABLE_DRIVER_PLUGINS.md) in the docker/machine repo on GitHub. + See Available driver plugins in the docker/machine repo on GitHub. ## 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 ls NAME ACTIVE DRIVER STATE URL 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) -clusters. This can be used with any driver and will be secured with TLS. +Docker Machine can also provision Docker Swarm 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. -See the Swarm docs for details. +* To get started with Swarm, see Get and run the Swarm software. -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 Provision a Swarm cluster with Docker Machine. - $ docker-machine create -d virtualbox local +## Where to go next -Load the Machine configuration into your shell: - - $ eval "$(docker-machine env local)" - -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:// \ - swarm-master - -Replace `` 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:// \ - 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 +- [Understand Machine concepts](concepts.md) +- Docker Machine driver reference +- Docker Machine subcommand reference +- Provision a Docker Swarm cluster with Docker Machine diff --git a/docs/get-started.md b/docs/get-started.md index b09c26269f..7e3867e378 100644 --- a/docs/get-started.md +++ b/docs/get-started.md @@ -1,6 +1,6 @@ + # Docker Machine -- Install a machine on your [local system using VirtualBox](get-started.md). -- Install multiple machines [on your cloud provider](get-started-cloud.md). +- [Docker Machine overview](overview.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 subcommand reference](reference/index.md) diff --git a/docs/install-machine.md b/docs/install-machine.md index 1cc08e5b8d..00fdd64a72 100644 --- a/docs/install-machine.md +++ b/docs/install-machine.md @@ -18,10 +18,7 @@ installation instructions or Windows installation instructions. -If you only want Docker Machine, you can install the Machine binaries (the -latest versions of which are located at - ) directly by following the -instructions in the next section. +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 docker/machine release page on GitHub. ## 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" && \ 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 docker/machine release page directly. 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)]\$ ' -You can find additional documentation in the comments at the -[top of each script](https://github.com/docker/machine/tree/master/contrib/completion/bash). +You can find additional documentation in the comments at the top of each script. ## Where to go next -- [Docker Machine overview](index.md) -- [Docker Machine driver reference](drivers/index.md) -- [Docker Machine subcommand reference](reference/index.md) +- [Docker Machine overview](overview.md) +- 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) +- Docker Machine driver reference +- Docker Machine subcommand reference diff --git a/docs/overview.md b/docs/overview.md index c71a34d413..11943a499d 100644 --- a/docs/overview.md +++ b/docs/overview.md @@ -1,6 +1,6 @@ -# Overview of Docker Machine -Machine lets you create Docker hosts on your computer, on cloud providers, and -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. +# Docker Machine Overview -Once you create one or more Docker hosts, Docker Machine supplies a number of -commands for managing them. Using these commands you can +You can use Docker Machine to: -- start, inspect, stop, and restart a host -- upgrade the Docker client and daemon -- configure a Docker client to talk to your host +* Install and run Docker on Mac or Windows +* Provision and manage multiple remote Docker hosts +* 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 -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). +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. -## 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 -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. +## Why should I use it? -To create a virtual machine, you supply Docker Machine with the name of the -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). +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. -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 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). +Docker Machine has these two broad use cases. -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 ` command returns a specific host's IP -address. +* **I want to run Docker on Mac or Windows** -Before you can run a `docker` command on a machine, you configure your -command-line to point to that machine. The `docker-machine env ` -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. + ![Docker Machine on Mac and Windows](img/machine-mac-win.png) -For a complete list of the `docker-machine` subcommands, see the [Docker Machine -subcommand reference](reference/index.md). + 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. -## 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. -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. + ![Docker Machine for provisioning multiple systems](img/provision-use-case.png) -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`. + 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. -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.: + 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. - $ 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 `, `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 -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. +**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_**". -- 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/). +![Docker Machine](img/machine.png) ## Where to go next -- Install a machine on your [local system using VirtualBox](get-started.md). -- Install multiple machines [on your cloud provider](get-started-cloud.md). -- [Docker Machine driver reference](drivers/index.md) -- [Docker Machine subcommand reference](reference/index.md) +- [Install Docker Machine](install-machine.md) +- 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) +- [Provision a Docker Swarm cluster with Docker Machine](https://docs.docker.com/swarm/machine-provisioning/provision-w-machine/) +- [Understand Machine concepts](concepts.md) +- Docker Machine driver reference +- Docker Machine subcommand reference +- [Migrate from Boot2Docker to Docker Machine](migrate-to-machine.md)