Getting Started with Docker

In this tutorial, we'll run matchbox on your Linux machine with Docker to network boot and provision a cluster of QEMU/KVM CoreOS machines locally. You'll be able to create Kubernetes clusters, etcd3 clusters, and test network setups.

Note: To provision physical machines, see network setup and deployment.


Install the package dependencies and start the Docker daemon.

$ # Fedora
$ sudo dnf install docker virt-install virt-manager
$ sudo systemctl start docker

$ # Debian/Ubuntu
$ # check Docker's docs to install Docker 1.8+ on Debian/Ubuntu
$ sudo apt-get install virt-manager virtinst qemu-kvm

Clone the matchbox source which contains the examples and scripts.

$ git clone
$ cd matchbox

Download CoreOS image assets referenced by the etcd-docker example to examples/assets.

$ ./scripts/get-coreos stable 1235.9.0 ./examples/assets

For development convenience, add /etc/hosts entries for nodes so they may be referenced by name as you would in production.

$ # /etc/hosts
$ ...


Run the latest matchbox Docker image from with the etcd-docker example. The container should receive the IP address on the docker0 bridge.

$ sudo docker pull
$ sudo docker run -p 8080:8080 --rm -v $PWD/examples:/var/lib/matchbox:Z -v $PWD/examples/groups/etcd3:/var/lib/matchbox/groups:Z -address= -log-level=debug

Take a look at the etcd3 groups to get an idea of how machines are mapped to Profiles. Explore some endpoints exposed by the service, say for QEMU/KVM node1.


Since the virtual network has no network boot services, use the dnsmasq image to create an iPXE network boot environment which runs DHCP, DNS, and TFTP.

$ sudo docker run --name dnsmasq --cap-add=NET_ADMIN -v $PWD/contrib/dnsmasq/docker0.conf:/etc/dnsmasq.conf:Z -d

In this case, dnsmasq runs a DHCP server allocating IPs to VMs between and, resolves to (the IP where matchbox runs), and points iPXE clients to

Client VMs

Create QEMU/KVM VMs which have known hardware attributes. The nodes will be attached to the docker0 bridge, where Docker's containers run.

$ sudo ./scripts/libvirt create-docker

You can connect to the serial console of any node. If you provisioned nodes with an SSH key, you can SSH after bring-up.

$ sudo virsh console node1

You can also use virt-manager to watch the console.

$ sudo virt-manager

Use the wrapper script to act on all nodes.

$ sudo ./scripts/libvirt [start|reboot|shutdown|poweroff|destroy]


The VMs should network boot and provision themselves into a three node etcd3 cluster, with other nodes behaving as etcd3 gateways.

The example profile added autologin so you can verify that etcd3 works between nodes.

$ systemctl status etcd-member
$ etcdctl set /message hello
$ etcdctl get /message


Clean up the containers and VM machines.

$ sudo docker rm -f dnsmasq
$ sudo ./scripts/libvirt poweroff
$ sudo ./scripts/libvirt destroy

Going Further

Learn more about matchbox or explore the other example clusters. Try the k8s example to produce a TLS-authenticated Kubernetes cluster you can access locally with kubectl.