If you have ever wanted to deploy and configure a Docker host with a single command from your own terminal you have come to the right place. Docker Machine enables you to provision and manage Docker systems in the cloud from your computer. Using the Docker Machine tools installed locally you can deploy a new cloud server through the UpCloud API in seconds without ever opening a web browser. This guide shows what you need to get started on Ubuntu Linux but Docker Machine is also available on a number of other operating systems including macOS and Windows.

Contents

Enable API permissions

Before you begin, deploying a new server with the Docker Machine onto your UpCloud account requires you to enable the API permissions, these can be found in your user account details at the UpCloud Control Panel.

The first step is to create a new subaccount for just the Docker Machine to API communication. This can be done in the My Account menu under User Accounts tab. We strongly recommend limiting the connections to specific addresses or address ranges for security reasons. You can find out more about the UpCloud accounts and permissions at an article about Group Accounts and Subaccount Management.

Note that you should restrict the API subaccount from your other UpCloud services. Take care handling the credentials if you are programming automation against the UpCloud API.

Quick start for testing

If you wish to quickly test provisioning cloud servers with the Docker Machine and do not mind missing the remote Docker commands, you can download and add the required binaries to your PATH without installing the Docker environment.

Download the Docker Machine binary.

curl -L https://github.com/docker/machine/releases/download/v0.9.0/docker-machine-`uname -s`-`uname -m` -o ~/docker-machine

The crucial part in allowing the Docker Machine to communicate with a cloud provider API comes in a form of the Machine drivers. The Docker Machine driver for this was written and published by a fellow UpCloud user torras on GitHub. It utilises the Go SDK for UpCloud developed by another dedicated user Jalle19 on GitHub.

Download the UpCloud driver.

curl -LO https://github.com/torras/docker-machine-driver-upcloud/releases/download/0/docker-machine-driver-upcloud

Make the two binary files executable with the next command.

chmod +x ~/docker-machine ~/docker-machine-driver-upcloud

Then copy the binaries to an appropriate directory that is included in your PATH.

sudo cp ~/docker-machine* /usr/local/bin/

That is all you need to be able to run docker-machine commands using the UpCloud driver to deploy, manage and delete servers straight from your own command line. Jump forward to the instructions on how to provision a docker host using the Docker Machine.

Setting up Docker Machine environment

To get the most out of what Docker Machine has to offer, you might want to set up a proper environment to enable all features and easy updates. This includes installing the Docker Engine, the Docker Machine, a Go programming environment, as well as a few pre-requisites to these packages.

Installing pre-requisites

Start by making sure you have the following tools installed and ready. Applications like curl, gcc, and git may be included in your distribution, simply verify that they can be found as these will be needed later on.

sudo apt-get install curl gcc git

You will also need to have the next two packages to securely download the Docker Engine. Depending on your system these might already be installed.

sudo apt-get install apt-transport-https ca-certificates

Once you have the pre-requisites installed, continue below with the next step.

Installing Docker Engine

To install Docker with the following instructions, you will need a 64-bit version of Ubuntu 14.04 or newer. For other operating systems and Linux distributions, you can find installing instructions at Docker documentation. Docker Engine itself will not be used locally in this guide but the command line tool is required to run Docker queries on the remote servers. Download and add the Docker project repository key.

curl -fsSL https://yum.dockerproject.org/gpg | sudo apt-key add -

You can verify that the key is valid with the following command.

apt-key fingerprint 58118E89F3A912897C070ADBF76221572C52609D

After successfully executing the above command, you should see a printout as below.

pub     4096R/2C52609D 2015-07-14
        Key fingerprint = 5811 8E89 F3A9 1289 7C07 0ADB F762 2157 2C52 609D
uid                    Docker Release Tool (releasedocker) <[email protected]>

You can then add the Docker repository to your sources list and update.

sudo add-apt-repository "deb https://apt.dockerproject.org/repo/ ubuntu-$(lsb_release -cs) main"
sudo apt-get update

Lastly, install the latest version of Docker with the following command.

sudo apt-get install docker-engine

Once installed, Docker is ready to run. Usually, you might wish to add your username to the docker users group to avoid having to use sudo on every docker run command, but with Docker Machine the commands are run remotely and this is not necessary.

Installing Docker Machine

Next, download the Docker Machine binary and copy it to an appropriate directory in your PATH environmental variable.

curl -L https://github.com/docker/machine/releases/download/v0.9.0/docker-machine-`uname -s`-`uname -m` -o ~/docker-machine

Make sure the program is executable.

chmod +x ~/docker-machine

Then copy it to the /usr/local/bin/ directory.

sudo cp ~/docker-machine /usr/local/bin/

The docker-machine command line tool lets you deploy, manage and delete Docker servers both locally and remotely. Next, continue below with installing the Go programming language packages to download and compile the Docker Machine driver for UpCloud.

Installing Go

Go is an open source programming language that was used to write the Docker Machine driver for UpCloud. Download the appropriate Go package for your system from their download page, or use the 1.7.5 version download command below.

curl -O https://storage.googleapis.com/golang/go1.7.5.linux-amd64.tar.gz

Extract the tar file to the /usr/local directory.

sudo tar -C /usr/local -xzf go1.7.5.linux-amd64.tar.gz

Create a new directory to hold any Go code downloads for example at your home directory.

mkdir ~/go

Then include the downloads folder you just created along with the Go binary directory in your PATH environmental variable.

export GOPATH=$HOME/go
export PATH=$PATH:/usr/local/go/bin

Also, add the same two lines to the end of your profile configuration to avoid having to reset the paths again manually.

nano $HOME/.profile

Go should now be available and configured. Test the install by checking the version number.

go version

You should see an output as shown below.

go version go1.7.5 linux/amd64

The version number should match the package name you downloaded, 1.7.5 for 64-bit Linux in this case as above. With Go packages installed, you are ready to download and compile the Docker Machine driver for UpCloud.

Installing Docker Machine UpCloud driver

The Machine drivers are an important part in how the Docker Machine functions with a cloud provider API. The Docker Machine driver for this was written and published by a fellow UpCloud user torras on GitHub. It utilises the Go SDK for UpCloud developed by another dedicated user Jalle19 on GitHub.

Download the driver using the Go command below.

go get -u github.com/torras/docker-machine-driver-upcloud

Set the driver with executable permissions.

chmod +x  ~/go/bin/docker-machine-driver-upcloud

Then copy it to the same directory as the Docker Machine binary.

sudo cp ~/go/bin/docker-machine-driver-upcloud /usr/local/bin/

That is it, you should now be able to run docker-machine commands using the UpCloud driver to deploy, manage and delete servers straight from your own command line. Continue with the instructions underneath on how to deploy a Docker host using Docker Machine.

Provisioning Docker host

Check that Docker Machine responds to commands and can find the required driver using the command below. This prints the usage options for deploying a new server, including the UpCloud specific parameters with their default values.

docker-machine create --driver upcloud

To actually deploy a server, you will need to choose a few parameters such as the plan, zone, and template with which the server will be created. The following UpCloud specific options can be used to customise the server.

docker-machine create
--driver upcloud
--upcloud-user "username"
--upcloud-passwd "password"
--upcloud-plan "1xCPU-1GB" / "2xCPU-2GB" / "4xCPU-4GB" / "6xCPU-8GB"
--upcloud-zone "uk-lon1" / "de-fra1" / "us-chi1" / "fi-hel1"
--upcloud-template "01000000-0000-4000-8000-000030030200" (Ubuntu Server 16.04)
--upcloud-ssh-user "root"
--upcloud-use-private-network-only
--upcloud-userdata "path/to/cloud-init"
<server_name>

The template option takes an UpCloud storage disk UUID as a parameter. Debian based systems work well together with Docker Machine commands but you can also use other distributions or even create your own template. You can find a list of the public templates at the UpCloud Control Panel under the Disks menu, the following public templates are tested and recommended.

Debian GNU/Linux 7.8 (Wheezy)
01000000-0000-4000-8000-000020020100

Debian GNU/Linux 8.5 (Jessie)
01000000-0000-4000-8000-000020030100

Ubuntu Server 14.04 LTS (Trusty Tahr)
01000000-0000-4000-8000-000030040200

Ubuntu Server 16.04 LTS (Xenial Xerus)
01000000-0000-4000-8000-000030060200

Test your Docker Machine setup by creating a new host using the command below. Replace the <username> and <password> with your API subaccount details to authenticate to the API and enter a hostname by replacing the <server_name>.

docker-machine create --driver upcloud --upcloud-user "<username>" --upcloud-passwd "<password>" --upcloud-plan "1xCPU-1GB" --upcloud-zone "uk-lon1" --upcloud-template "01000000-0000-4000-8000-000030060200" <server_name>

The deployment will only take a moment and when the server is running a Docker Engine will be installed. In case something goes wrong while provisioning, you can restart the process with the following command. This might be necessary if the system image you used to deploy the Docker Machine does not include all the tools Docker expected.

docker-machine provision <server_name>

Once the server is up and running, you can see it on a list of provisioned Docker hosts with the next command.

docker-machine ls
NAME    ACTIVE  DRIVER   STATE    URL                      SWARM  DOCKER  ERRORS
docker  -       upcloud  Running  tcp://83.136.249.21:2376        v1.13.0

Also as usual when your cloud Docker host is being deployed, you will receive an email about the server creation to your UpCloud account with the root password if you wish to log in manually using SSH to check on the server.

Deploying containers to Docker hosts remotely

After the newly provisioned host replies that it is ready, you can employ the docker run command to deploy containers, granted that you installed the Docker binaries. First, check the server environment with the following command. Replace the <server_name> with yours.

docker-machine env <server_name>

Then change focus to the new machine with the command shown in the environment output like the example below.

eval $(docker-machine env <server_name>)

Any Docker commands will now be executed on the focused server instead of running them locally. Deploy a simple container to test the setup with the command below.

docker run hello-world

You should see the latest container image getting downloaded and ran ending with a hello message from Docker confirming that the installation is working correctly.

If you wish to verify that the container was indeed executed on the remote host you can use the Docker Machine to open an SSH connection to the server using a command like below.

docker-machine ssh <server_name>

Once connected, check the containers deployed to the server using the docker ps command with the --all parameter to show exited containers as well.

docker ps --all
CONTAINER ID IMAGE       COMMAND  CREATED        STATUS              PORTS NAMES
c8aa3c18b365 hello-world "/hello" 39 seconds ago Exited (0) 37 seconds ago laughing_newton

When you are finished checking out the server, close the SSH connection and return to your local terminal.

exit

Congratulations, you now have a fully featured Docker Machine command centre at your disposal. You can continue working with the host you deployed or simply delete it if you no longer have a need for the server.

docker-machine rm <server_name>

Summary

Deploying Docker ready cloud servers does not get much easier than with Docker Machine. The simplicity and ease of use will help you save time and money whether you wish to quickly test a container you are developing or build an on-demand scalable cluster. Using Docker Machine also allows you to create and manage Docker Swarm clusters of which you can find out more at the Docker documentation.