UPDATE February 2018
Docker unikernel runner was a nice experiment, but I am no longer developing or maintaining this code. This repository is now archived, feel free to fork it.
This is an experimental unikernel runner for running Mirage OS unikernels in Docker containers. Currently the following Mirage OS targets are supported:
unix: UNIX userspace using the
ukvm: Mirage OS/Solo5 using ukvm as the hypervisor.
kvm(experimental): Mirage OS/Solo5 using software emulation (
qemu) or QEMU/KVM (
kvm) as the hypervisor.
Quick start with a Mirage application
You will need
docker (obviously) and
make to drive the top-level build
process. The build itself is all run in containers so there are no other host
- Clone this repository, run
make. This will build the
docker-mirage.shsomewhere in your $PATH.
- In the directory containing your built Mirage application, run
docker-mirage.sh build HYPERVISOR -t my-unikernel, where HYPERVISOR is one of the supported targets (see note).
- Run the unikernel with
docker-mirage.sh run --rm -ti my-unikernel.
Note: If you're using Docker for Mac or Docker for Windows, then you will
only be able to run images built for the
qemu HYPERVISOR locally.
This section covers more about how runner works, including how to manually
build your own unikernel images without the
docker-mirage wrapper script.
To build the runner and all example containers, run:
Makefiles under the
tests/ directory for an example of how to
manually build unikernel images.
Running the example containers
make run-tests to run all tests available on your host. The Mirage/Solo5
tests require KVM and access to
Two containers which build Mirage OS samples from the
repository are included,
Each is run as a normal Docker container, however you must pass
to the container and run with the
CAP_NET_ADMIN capability. For example:
docker run -ti --rm \ --device=/dev/net/tun:/dev/net/tun \ --cap-add=NET_ADMIN mir-stackv4
CAP_NET_ADMIN and access to
/dev/net/tun are required for runner to be able
to wire L2 network connectivity from Docker to the unikernel. Runner will drop
all capabilities with the exception of
CAP_NET_BIND_SERVICE before launching
To run the
mir-stackv4 sample using
ukvm as a hypervisor:
docker run -ti --rm \ --device=/dev/kvm:/dev/kvm \ --device=/dev/net/tun:/dev/net/tun \ --cap-add=NET_ADMIN mir-stackv4-ukvm
In addition to the requirements for the
unix target, access to
- (#1) Network delays due to random MAC address use. Workaround is:
sysctl -w net.ipv4.conf.docker0.arp_accept=1.
kvmsupport is experimental, currently uses Debian to build the containers due to unknown issues with the Alpine toolchain.