Docker Machine is a tool that lets you install Docker software on virtual machines or remote cloud platforms easily. If you installed Docker on your local host you understood how to obtain package via package manager and manage Docker engine.

I recommend using Docker Machine to install and manage Docker engine on remote machines or cloud platforms to avoid tedious works such as spinning up an instance and configure firewalls, then login the instance via ssh to install Docker engine. The tool can intervene to do such works between us and the cloud environments.

Another use case of Docker Machine is to provision multiple hosts for container orchestration or simply when a mass preparation is needed for Docker engine. The tool gives you the same syntax to multiply Docker hosts so that you can just repeat the same for different environments (i.e. hybrid cloud, on-prem and cloud, etc).

In this tutorial, I will cover 1) create AWS EC2 based Docker host 2) Run a simple application 3) Clean up Docker host. It’s quite straightforward if you use other cloud vendors.

Create a machine

Docker machine – Install machine

First you need to install Docker Machine itself by following the above link. In my environment docker-machine version 0.16.2 is set up. You also need AWS credential to run commands for AWS. Here’s the previous guide “How do AWS CLI credential and IAM role for EC2 work?” to set up your credential.

$ docker-machine --version
docker-machine version 0.16.2, build bd45ab13

To invoke AWS API to turn up an EC2 instance, docker-machine create –driver amazonec2 will be needed. I pass some other flags for opening 8000 port on the host, the region and instance type for t2.micro.

With this command below, one EC2 instance “aws-sandbox” will be up and running with Docker engine installed in first place. The flags all vary depending on what environment and driver you run a command against. Azure driver has completely different flags.

Docker machine – Amazon Web Services EC2 example

$ docker-machine create --driver amazonec2 --amazonec2-open-port 8000 --amazonec2-region ap-northeast-1 --amazonec2-instance-type "t2.micro" aws-sandbox

docker-machine ls returns managed machines under the tool. In this case aws-sandbox is returned with the status, URL and Docker engine version information. docker-machine ip command returns the host’s IP address.

$ docker-machine ls
NAME          ACTIVE   DRIVER      STATE     URL                        SWARM   DOCKER      ERRORS
aws-sandbox   -        amazonec2   Running   tcp://3.112.224.179:2376           v19.03.13

$ docker-machine ip aws-sandbox
3.112.224.179

Next let’s change the local environment and local Docker client connect Docker daemon on the created host in AWS. docker-machine env aws-sandbox displays the configuration command “eval $(docker-machine env aws-sandbox)” if you’re using bash or zsh.

$ docker-machine env aws-sandbox
export DOCKER_TLS_VERIFY="1"
export DOCKER_HOST="tcp://3.112.224.179:2376"
export DOCKER_CERT_PATH="/home/ether/.docker/machine/machines/aws-sandbox"
export DOCKER_MACHINE_NAME="aws-sandbox"
# Run this command to configure your shell:
# eval $(docker-machine env aws-sandbox)

$ eval $(docker-machine env aws-sandbox)

Now it’s done and you Docker client should be able to talk to AWS Docker engine with the configured environment. Here’s the result of docker info from local machine for the remote AWS Docker host. The server version is 19.03.13 in this example and there are no containers as of now.

We’re ready for using Docker, so move to the next section how to set a container and run an application on the host.

Run a simple application

Now you’re able to invoke a test web image on the remote EC2 instance and confirm web access on the port 8000. This external port 8000 is exposed on the docker host when we launched the Docker host with docker-machine command. The port 80 is listened on the nginx container inside and 8000 is open on the host machine respectively.

This command is run on the remote instance to pull web server image and run a container. Once it’s up, you can access the host IP address with the port 8000 on your browser.

$ docker run -d -p 8000:80 --name webserver kitematic/hello-world-nginx

Clearn up Docker host

Here’s the step how to unset the environmental variables against the remote host and delete the created Docker host in AWS.

After you unset the environmental variables, you’ll be back to the local Docker engine to call API to manage local containers.

# unset the environmental variables
$ eval $(docker-machine env -u)

# delete the EC2 instance of Docker engine
$ docker-machine rm aws-sadbox

$ docker-machine ls
NAME   ACTIVE   DRIVER   STATE   URL   SWARM   DOCKER   ERRORS

Next I collected some frequent use commands from the command reference.

Command reference

docker-machine status, To check machine status.

$ docker-machine status <your machine>
Running

docker-machine create, is to create a docker machine. Here’s a place you have to start creating your docker machine. –driver flag is necessary. If you want to know plugin specific flags you can use –help in text.

$ docker-machine create

docker-machine env is to set environment variables to dictate that docker should run a command against a particular machine. You can specify shell with –shell flag.

$ docker-machine env <your machine> # bash or zsh is expected

# For PowerShell or cmd.exe
$ docker-machine env --shell PowerShell <your machine>
$ docker-machine env --shell cmd <your machine>

To inspect further details about the machine. You can use docker-machine inspect with –format option to extract required information for use.

$ docker-machine inspect <your machine>

docker-machine ssh is to perform commands on your machine via SSH. If you run just docker-machine ssh <your machine>, you’ll be able to login into the Docker host remotely.

$ docker-machine ssh aws-sandbox free
              total     used     free   shared  buff/cache   available
Mem:        1014540   142488   170552     4328      701500      670756
Swap:             0           0           0

$ docker-machine ssh aws-sandbox df -h
Filesystem      Size  Used Avail Use% Mounted on
udev            488M     0  488M   0% /dev
tmpfs           100M  4.3M   95M   5% /run
/dev/xvda1       16G  3.5G   13G  23% /
tmpfs           496M     0  496M   0% /dev/shm
tmpfs           5.0M     0  5.0M   0% /run/lock
tmpfs           496M     0  496M   0% /sys/fs/cgroup
tmpfs           100M     0  100M   0% /run/user/1000

docker-machine scp is to copy your file from local to the remote Docker host efficiently. There are 2 options -r for copying files recursively and -d for rsync for the command.

$ touch testfile
$ docker-machine scp ./testfile aws-sandbox:/home/docker/

At last docker-machine rm is to remove the local reference and deletes it on the cloud provider or virtualization management platform.

$ docker-machine rm aws-sandbox
$ docker-machine rm <your machine>