Docker on FreeBSD


by ross at 23:40:26 on July 26, 2017

There are two approaches to running Docker on FreeBSD. Fisrt one was created back in 2015 and it was a native port of Docker engine to FreeBSD. It was an ambitious project but nobody stepped forward to continuously port the never-ending flow of upstream code to FreeBSD. So the port still exists (sysutils/docker-freebsd) but it wasn't updated since 2015 and it is Docker v1 (it is v17 as of 2017).

The other approach is to use official way of running Docker on platforms other than Linux. Well, somewhat official as Docker still does not support FreeBSD as a host officially. This is docker-machine tool which in turn will use VirtualBox to run a virtual machine with Linux and Docker engine. docker utility on the host will communicate with the engine inside VB where all the work will be done. This article describes what needs to be done to start using it.


Before we begin you need VirtualBox installed. Do not skip adding /boot/loader.conf and /etc/rc.conf lines mentioned on that page.

You won't need user inteface or anything, docker-machine will do all the work, just make sure VirtualBox is present and ready to be used.


# pkg install docker docker-machine docker-compose

That is all for root. Docker will be used by a regular user so run the following commands as this user.

Docker will store its stuff in ~/.docker. You might not want the virtual machine image files to live in your home, in this case just create a symlink:

> mkdir ~/.docker
> ln -s /storage/docker ~/.docker/machine

With the command above all the files will go to /storage/docker (give your user write permissions).

Create the machine

> docker-machine create --driver virtualbox \
    --virtualbox-memory 2048 \
    --virtualbox-cpu-count 2 \
    --virtualbox-disk-size 102400 \
    --virtualbox-hostonly-cidr "" \

Here's the example. We are creating machine named docker1. It is using VirtualBox driver, the vm has 2G of memory, 2 cores and 100G of disk space. docker-machine setups VirtualBox to use host-only network adapter (it will create vboxnet0 interface on the host automatically) and we are instructing it to use as the address of this adapter — change it to what suits your needs or omit this flag (default is

And basically that is all. Check if it is running:

> docker-machine ls
NAME      ACTIVE   DRIVER       STATE     URL                     SWARM   DOCKER        ERRORS
docker1   -        virtualbox   Running   tcp://           v17.06.0-ce

If you do open VirtualBox interface you will find a virtual machine named docker1 running. You can start/stop/whatever your machine using docker-machine utility.

Connect to the machine

docker utility by default tries to talk to Docker engine running on the same host. However with specific environment variables you can instruct it to talk to other host. docker-machine can export these variables for you.

> eval `docker-machine env docker1`

This will import into your current shell session variables needed for docker utility to talk to the machine docker1. From now on you just run docker command as usual:

> docker run hello-world
Unable to find image 'hello-world:latest' locally
latest: Pulling from library/hello-world
b04784fba78d: Pull complete 
Digest: sha256:f3b3b28a45160805bb16542c9531888519430e9e6d6ffc09d72261b0d26ff74f
Status: Downloaded newer image for hello-world:latest

Hello from Docker!
This message shows that your installation appears to be working correctly.

To generate this message, Docker took the following steps:
 1. The Docker client contacted the Docker daemon.
 2. The Docker daemon pulled the "hello-world" image from the Docker Hub.
 3. The Docker daemon created a new container from that image which runs the
    executable that produces the output you are currently reading.
 4. The Docker daemon streamed that output to the Docker client, which sent it
    to your terminal.

To try something more ambitious, you can run an Ubuntu container with:
 $ docker run -it ubuntu bash

Share images, automate workflows, and more with a free Docker ID:

For more examples and ideas, visit:

Everything docker-related should work now. But it is a new port so there might be bugs, for one I wasn't able to ping anything but 172.17.x.x from a running Docker container, although TCP does work (apt-get in Debian containers worked out of the box).