Repository files navigation

Machine lets you create Docker hosts on your computer, on cloud providers, andinside your own data center. It creates servers, installs Docker on them, thenconfigures the Docker client to talk to them.

It works a bit like this:

$docker-machine create -d virtualbox defaultRunning pre-create checks...Creating machine...(default) Creating VirtualBox VM...(default) Creating SSH key...(default) Starting VM...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 with boot2docker...Copying certs to the local machine directory...Copying certs to the remote machine...Setting Docker configuration on the remote daemon...Checking connection to Docker...Docker is up and running!To see how to connect Docker to this machine, run: docker-machine env default$docker-machine lsNAME      ACTIVE   DRIVER       STATE     URL                         SWARM   DOCKER   ERRORSdefault   -        virtualbox   Running   tcp://192.168.99.188:2376           v1.9.1$eval"$(docker-machine env default)"$docker run busyboxecho hello worldUnable to find image 'busybox:latest' locally511136ea3c5a: Pull completedf7546f9f060: Pull completeea13149945cb: Pull complete4986bf8c1536: Pull completehello world

In addition to local VMs, you can create and manage cloud servers:

$docker-machine create -d digitalocean --digitalocean-access-token=secret stagingCreating SSH key...Creating Digital Ocean droplet...To see how to connect Docker to this machine, run: docker-machine env staging$docker-machine lsNAME      ACTIVE   DRIVER         STATE     URL                         SWARM   DOCKER   ERRORSdefault   -        virtualbox     Running   tcp://192.168.99.188:2376           v1.9.1staging   -        digitalocean   Running   tcp://203.0.113.81:2376             v1.9.1

Full documentationis available here.

Want to hack on Machine? Please start with theContributing Guide.

In addition to the core driver plugins bundled alongside Docker Machine, userscan make and distribute their own plugin for any virtualization technology orcloud provider. To browse the list of known Docker Machine plugins, pleaseseethis document in ourdocs repo.

Docker Machine tries to do the right thing in a variety of scenarios butsometimes things do not go according to plan. Here is a quick troubleshootingguide which may help you to resolve of the issues you may be seeing.

Note that some of the suggested solutions are only available on the DockerMachine master branch. If you need them, consider compiling Docker Machine fromsource.

A common issue with Docker Machine is that it will hang when attempting to startup the virtual machine. Since starting the machine is part of thecreateprocess,create is often where these types of errors show up.

A hang could be due to a variety of factors, but the most common suspect isnetworking. Consider the following:

• Are you using a VPN? If so, try disconnecting and see if creation willsucceed without the VPN. Some VPN software aggressively controls routes andyou may need tomanually add the route.
• Are you connected to a proxy server, corporate or otherwise? If so, take alook at the--no-proxy flag forenv and atsetting environment variablesfor the created Docker Engine.
• Are there a lot of host-only interfaces listed by the commandVBoxManage list hostonlyifs? If so, this has sometimes been known to cause bugs. Considerremoving the ones you are not using (VBoxManage hostonlyif remove name) andtrying machine creation again.

We are keenly aware of this as an issue and working towards a set of solutionswhich is robust for all users, so please give us feedback and/or report issues,workarounds, and desired workflows as you discover them.

If you see messages such as "exit status 1" creating machines with VirtualBox,this frequently indicates that there is an issue with VirtualBox itself. Pleasefile an issue and include a linkto aGithub Gist with the output of the VirtualBoxlog (usually located at$HOME/.docker/machine/machines/machinename/machinename/Logs/VBox.log), as wellas the output of running the Docker Machine command which is failing with theglobal--debug flag enabled. This will help us to track down which versionsof VirtualBox are failing where, and under which conditions.

If you see messages such as "exit status 255", this frequently indicates therehas been an issue with SSH. Please investigate your SSH configuration if youhave one, and/orfile an issue.

In order tocreate orupgrade virtual machines running Docker, DockerMachine will check the Github API for the latest release of theboot2dockeroperating system. The Github APIallows for a small number of unauthenticated requests from a given client, butif you share an IP address with many other users (e.g. in an office), you mayget rate limited by their API, and Docker Machine will error out with messagesindicating this.

In order to work around this issue, you cangenerate atokenand pass it to Docker Machine using the global--github-api-token flag likeso:

$docker-machine --github-api-token=token create -d virtualbox newbox

This should eliminate any issues you've been experiencing with rate limiting.