Ubuntu Linux 17.04 (64-bit)

Let’s take a look at the steps required to install Docker.

This first command will ensure that you aren’t running older versions of Docker. The package has been renamed a few times, so you’ll need to specify several possibilities here:

$ sudo apt-get remove docker docker-engine docker.io

Next you will need to add the required software dependencies and apt respository for Docker Community Edition. This lets us fetch and install packages for Docker and validate that they are signed.

$ sudo apt-get update
$ sudo apt-get install \
    apt-transport-https \
    ca-certificates \
    curl \
    software-properties-common
$ curl -fsSL https://download.docker.com/linux/ubuntu/gpg |\
    sudo apt-key add -
$ sudo add-apt-repository \
    "deb [arch=amd64] https://download.docker.com/linux/ubuntu \
    $(lsb_release -cs) \
    stable"

Now that you have the repository set up, run the following commands to install Docker:

$ sudo apt-get update
$ sudo apt-get install docker-ce

Assuming you don’t get any error messages, you now have Docker installed!

Fedora Linux 26 (64-bit)

Let’s take a look at the steps needed in order to install the correct Docker packages on your system.

This first command will ensure that you aren’t running older versions of Docker. As on Ubuntu systems, the package has been renamed a few times, so you’ll need to specify several possibilities here:

$ sudo dnf remove docker \
    docker-common \
    docker-selinux \
    docker-engine-selinux \
    docker-engine

Next you will need to add the required software dependencies and dnf respository for Docker Community Edition.

$ sudo dnf -y install dnf-plugins-core
$ sudo dnf config-manager \
    --add-repo \
    https://download.docker.com/linux/fedora/docker-ce.repo

Now you can install the current version of Docker Community Edition.

$ sudo dnf install docker-ce

GUI installer

Download the latest Docker Community Edition for Mac installer and then double-click on the downloaded program icon. Follow all of the installer prompts until the installation is finished.

Docker Community Edition for Mac relies on the xhyve project to provide a native lightweight virtualization layer for the Linux server component, which macOS requires to launch Linux virtual machines that can build Docker images and run containers.

Homebrew installation

You can also install the Docker CLI tools using the popular Homebrew package management system for macOS. If you take this approach, you should consider installing Docker Machine for creating and managing your Linux VM. We’ll discuss that shortly in “Non-Linux VM-Based Server”.

Chocolatey installation

You can also install the Docker CLI tools using the popular Chocolatey package management system for Windows. If you take this approach, you should consider installing Docker Machine for creating and managing your Linux VM. We’ll discuss that shortly in “Non-Linux VM-Based Server”.

Docker Machine

In early 2015, Docker announced the beta release of Docker Machine, a tool that makes it much easier to set up Docker hosts on bare-metal, cloud, and virtual machine platforms.

The easiest way to install Docker Machine is to visit the GitHub releases page and download the correct binary for your operating system and architecture. Currently, there are variants for 64-bit versions of Linux, Windows, and macOS, among a few other options.

For these demonstrations, you will need to have a recent release of a hypervisor, like VirtualBox, installed on your system. VirtualBox is freely downloadable and easily installed on most systems, so for this section, the examples will all use a Unix-based system with VirtualBox. The following example shows how to do the install on macOS.

First, you need to download and install the docker-machine executable. This example downloads v0.13.0, but you can determine the current release on GitHub.

$ mkdir ~/bin
$ curl -L https://github.com/docker/machine/releases/\
download/v0.13.0/docker-machine-`uname -s`-`uname -m` \
  > ~/bin/docker-machine
$ export PATH=${PATH}:~/bin
$ chmod u+rx ~/bin/docker-machine

Once you have the docker-machine executable in your path, you can start to use it to set up Docker hosts. Here we’ve just put it temporarily into your path. If you want to keep running it in the future, add it to your .profile or .bash_profile file. Now that you can run the tool, the next thing that you need to do is create a virtual machine to host your Docker server.

You can do this using the docker-machine create command:

$ docker-machine create --driver virtualbox local

Creating CA: /home/skane/.docker/machine/certs/ca.pem
Creating client certificate: /home/skane/.docker/machine/certs/cert.pem
Running pre-create checks...
(local) Image cache directory does not exist, creating it at ...
(local) No default Boot2Docker ISO found locally, downloading the latest...
(local) Latest release for github.com/boot2docker/boot2docker is v17.09.1-ce
(local) Downloading /home/skane/.docker/machine/cache/boot2docker.iso from ...
(local) 0%..10%..20%..30%..40%..50%..60%..70%..80%..90%..100%
Creating machine...
(local) Copying /home/me/.docker/machine/cache/boot2docker.iso to ...
(local) Creating VirtualBox VM...
(local) Creating SSH key...
(local) Starting the VM...
(local) Check network to re-create if needed...
(local) Found a new host-only adapter: "vboxnet0"
(local) Waiting for an IP...
Waiting for machine to be running, this may take a few minutes...
Detecting operating system of created instance...
Waiting for SSH to be available...
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 your Docker Client to the Docker Engine running on this
  virtual machine, run: docker-machine env local

This downloads a virtual machine image and then creates a VirtualBox VM that you can use as a Docker host. If you look at the output from the create command, you will see that it instructs you to run docker-machine env local.

This command will produce output that includes all of the environment variables that you must set in your shell to configure the Docker client to use your docker-machine virtual machine.

$ docker-machine env local
export DOCKER_TLS_VERIFY="1"
export DOCKER_HOST="tcp://172.17.42.10:2376"
export DOCKER_CERT_PATH="/Users/me/.docker/machine/machines/local"
export DOCKER_MACHINE_NAME="local"
# Run this command to configure your shell:
# eval $(docker-machine env local)

The last line in the preceding output includes a command that will automatically set up those environment variables in your current shell. This command is different across platforms, but on Unix-based systems it will look like this:

$ eval $(docker-machine env local)

Because we’re evaluating the output of the command with eval, this command produces no output. If you’re curious, feel free to run the part of the command in parentheses to see what is being evaluated. Generally speaking, you will want to also put this whole eval block in your .profile or .bash_profile file as well, since it makes working with your Docker VM much easier going forward.

Now that you have that all set up, you can use the following command to confirm what machines you have running:

$ docker-machine ls
NAME  ACTIVE DRIVER     STATE   URL                       SWARM DOCKER      ...
local -      virtualbox Running tcp://172.17.42.10:2376         v17.09.1-ce ...

This tells you that you have one machine, named local, that is active and running.

Now you can pass commands to the new Docker machine by leveraging the regular docker command, since you have set the proper environment variables.

If you did not want to set the Docker environment variables from docker-machine env local for some reason, you could also use the docker and docker-machine commands in conjunction with one another to configure the docker CLI at runtime, like so: docker $(docker-machine config local) ps.

This command embeds the output from docker-machine into the middle of the docker command. If you run the docker-machine config command on its own, you can see what it is adding to the docker command:

$ docker-machine config local
--tlsverify
--tlscacert="/home/skane/.docker/machine/machines/local/ca.pem"
--tlscert="/home/skane/.docker/machine/machines/local/cert.pem"
--tlskey="/home/skane/.docker/machine/machines/local/key.pem"
-H=tcp://172.17.42.10:2376

Although you can see the Docker host’s IP address in the output, you can ask for it explicitly with the following command:

$ docker-machine ip local
172.17.42.10

If you want to log in to the system, you can easily do this by running:

$ docker-machine ssh local
                        ##         .
                  ## ## ##        ==
               ## ## ## ## ##    ===
           /"""""""""""""""""\___/ ===
      ~~~ {~~ ~~~~ ~~~ ~~~~ ~~~ ~ /  ===- ~~~
           \______ o           __/
             \    \         __/
              \____\_______/
 _                 _   ____     _            _
| |__   ___   ___ | |_|___ \ __| | ___   ___| | _____ _ __
| '_ \ / _ \ / _ \| __| __) / _` |/ _ \ / __| |/ / _ \ '__|
| |_) | (_) | (_) | |_ / __/ (_| | (_) | (__|   <  __/ |
|_.__/ \___/ \___/ \__|_____\__,_|\___/ \___|_|\_\___|_|
Boot2Docker version 17.09.1-ce, build HEAD : e7de9ae - Fri Dec  8 19:41:36 ...
Docker version 17.09.1-ce, build 19e2cf6
docker@local:~$ exit

To stop your Docker machine, you can run:

$ docker-machine stop local
Stopping "local"...
Machine "local" was stopped.

And then you can run this to restart it (you need it to be running):

$ docker-machine start local

Once a machine is down, you can also remove it to clean up after yourself entirely:

$ docker-machine rm local

If you want to explore the other options that docker-machine provides, you can simply run docker-machine without any other options to see the command help.

Vagrant

If you need more flexibility with the way your Docker development environment is set up, you might want to consider using Vagrant instead of docker-machine. Like Docker Machine, Vagrant provides support for multiple hypervisors, but it is much more extensible, and can often be leveraged to mimic even the most complex environments.

A common use case for leveraging Vagrant during Docker development is to support testing on images that match your production environment. Vagrant supports everything from broad distributions like CentOS 7 and Ubuntu 16.04 to finely focused atomic host distributions like CoreOS and Project Atomic.

You can easily install Vagrant on most platforms by downloading a self-contained package from vagrantup.com. You will also need to have a hypervisor, like VirtualBox, installed on your system.

In the following example, you will create a CoreOS-based Docker host running the Docker daemon on the unencrypted port 2375. You could use your favorite distribution here instead, but CoreOS ships with working Docker out of the box and the image is quite small.

After Vagrant is installed, create a host directory with a name similar to docker-host and then move into that directory:

$ mkdir docker-host
$ cd docker-host

To install the coreos-vagrant files, you need the version control tool named Git. If you don’t already have Git, you can install it via your package manager of choice, or download and install it from git-scm.com. When Git is installed, you can grab the coreos-vagrant files and then change into the new directory with the following commands:

$ git clone https://github.com/coreos/coreos-vagrant.git
$ cd coreos-vagrant

Inside the coreos-vagrant directory, you’ll need to leverage the built-in ignition tool or the built-in cloud-init tool to add a systemd unit file that will enable the Docker daemon on TCP port 2375. The Vagrantfile will determine whether to use ignition or cloud-init based on your hypervisor, so it is easiest to simply set them both up.

For ignition, create a file called config.ign that contains all of the following:

{
  "ignition": {
    "version": "2.0.0",
    "config": {}
  },
  "storage": {},
  "systemd": {
    "units": [
      {
        "name": "docker-tcp.socket",
        "enable": true,
        "contents": "[Unit]\nDescription=Docker Socket for the API\n..."
      }
    ]
  },
  "networkd": {},
  "passwd": {}
}

git clone https://github.com/bluewhalebook/\
docker-up-and-running-2nd-edition.git

For cloud-init, create a file called user-data that contains all of the following, including the very first line:

#cloud-config

coreos:
  units:
    - name: docker-tcp.socket
      command: start
      enable: true
      content: |
        [Unit]
        Description=Docker Socket for the API

        [Socket]
        ListenStream=2375
        Service=docker.service
        BindIPv6Only=both

        [Install]
        WantedBy=sockets.target

When you have saved both of these files, you can start up the Vagrant-based virtual machine by running:

$ vagrant up
Bringing machine 'core-01' up with 'vmware_fusion' provider...
==> core-01: Cloning VMware VM: 'coreos-alpha'. This can take some time...
==> core-01: Checking if box 'coreos-alpha' is up to date...
==> core-01: Verifying vmnet devices are healthy...
==> core-01: Preparing network adapters...
==> core-01: Fixed port collision for 22 => 2222. Now on port 2202.
==> core-01: Starting the VMware VM...
==> core-01: Waiting for machine to boot. This may take a few minutes...
    core-01: SSH address: 172.17.42.10:22
    core-01: SSH username: core
    core-01: SSH auth method: private key
==> core-01: Machine booted and ready!
==> core-01: Forwarding ports...
    core-01: -- 22 => 2202
    core-01: SSH address: 172.17.42.10:22
    core-01: SSH username: core
    core-01: SSH auth method: private key
==> core-01: Setting hostname...
==> core-01: Configuring network adapters within the VM...
==> core-01: Running provisioner: file...
==> core-01: Running provisioner: shell...
    core-01: Running: inline script
==> core-01: Running provisioner: shell...
    core-01: Running: inline script

To set up your shell environment so that you can easily use your local Docker client to talk to the Docker daemon on your virtual machine, you can set the following variables:

$ unset DOCKER_TLS_VERIFY
$ unset DOCKER_CERT_PATH
$ export DOCKER_HOST=tcp://127.0.0.1:2375

... Fixed port collision for 2375 ... Now on port 2202

export DOCKER_HOST=tcp://127.0.0.1:2202

If everything is running properly, you should now be able to run the following to connect to the Docker daemon:

$ docker info
Containers: 0
 Running: 0
 Paused: 0
 Stopped: 0
Images: 0
Server Version: 17.11.0-ce
Storage Driver: overlay2
 Backing Filesystem: extfs
 Supports d_type: true
 Native Overlay Diff: true
Logging Driver: json-file
Cgroup Driver: cgroupfs
Plugins:
 Volume: local
 Network: bridge host macvlan null overlay
 Log: awslogs fluentd gcplogs gelf journald json-file logentries splunk syslog
Swarm: inactive
Runtimes: runc
Default Runtime: runc
Init Binary: docker-init
containerd version: 992280e8e265f491f7a624ab82f3e238be086e49
runc version: 0351df1c5a66838d0c392b4ac4cf9450de844e2d
init version: v0.13.2 (expected: 949e6facb77383876aeff8a6944dde66b3089574)
Security Options:
 seccomp
  Profile: default
 selinux
Kernel Version: 4.14.4-coreos
Operating System: Container Linux by CoreOS 1618.0.0 (Ladybug)
OSType: linux
Architecture: x86_64
CPUs: 1
Total Memory: 996.3MiB
Name: core-01
ID: MFKI:CLTN:3KDF:JXF4:FV74:GZAM:VJD7:35CW:TS3J:LTYE:QBLW:X26A
Docker Root Dir: /var/lib/docker
Debug Mode (client): false
Debug Mode (server): false
Registry: https://index.docker.io/v1/
Experimental: false
Insecure Registries:
 127.0.0.0/8
Live Restore Enabled: false

To connect to a shell on the Vagrant-based virtual machine, you can run:

$ vagrant ssh
Last login: Sun Dec 17 20:23:34 UTC 2017 from 192.168.180.1 on ssh
Container Linux by CoreOS alpha (1618.0.0)
core@core-01 ~ $ exit

You can stop your Vagrant-based VM by running:

$ vagrant halt
==> core-01: Attempting graceful shutdown of VM...