Skip to main content

Getting up and running with Docker on FreeBSD.

title: Docker on FreeBSD
author: ross
date: July 26, 2017
notoc: false

## Installation

There are two approaches to running Docker on FreeBSD. First 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

### VirtualBox

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

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

### Installation

$ 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   0

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).

[1]: #