How to run Docker on FreeBSD 12

How to get Docker running on FreeBSD 12

Jails vs Docker

Over the last couple of months I came across multiple questions on how to run Docker on FreeBSD. Usually the discussion ends up
in advocating Jails as the native FreeBSD solution (which it is). But often then not outside requirements dictate the use of the Docker container solution.

Not to repeat the discussion, and there are plenty of already, but if you are looking for segregation of a set of processes
with containers and you don’t rely on any hubs to do so, Jails most likely will fit the bill.

But this post is about the cases you can not or want to. The idea outlined here is not new and reflects
the setup on FreeNAS and in a wider sense how it is done on Windows and OSX.


To give you an idea what we are going to do:

  1. Setup FreeBSD with Bhyve (which means you need a machine capable todo so. Check the FreeBSD manual )
  2. Install Debian 9 onto a newly created VM.
  3. Install Docker there.
  4. Open up Docker remote API.
  5. Install Portainer to manage containers from the outside (web).

Key thing to highlight is that there is no docker command available on FreeBSD. So running CLI commands
will need you to login into the Debian VM or use the web interface.

The FreeBSD pkg repo has a package called Docker and Docker-compose which work great with the docker daemon running in the VM.
Set the DOCKER_HOST env to the ipaddress and port eg This gives a native interface with docker from FreeBSD.

Setup Bhyve

I assume you have FreeBSD running on your machine with Bhyve enabled and ready to go.
Personally I use the FreeBSD package vm-bhyve to run VMs on Bhyve. Install it via the pkg command. You know the drill.
Please follow the setup guide on Github.
Make sure to setup the virtual switch.

Create a new VM with the Debian template:

$ sudo vm create -t debian -s 20G debian

Edit the generated debian.conf file in the directory (eg /zrt/vm/debian) holding the VM files and add more memory and cpu
to fit your needs.

Download the Debian iso:

$sudo vm iso

Install the Debian VM:

sudo vm install debian debian-9.6.0-amd64-netinst.iso

Check that the tap0 interface opened by Bhyve is connected to the Bhyve bridge.

vm-public: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> metric 0 mtu 1500
ether 12:af:53:76:65:7c
id 00:00:00:00:00:00 priority 32768 hellotime 2 fwddelay 15
maxage 20 holdcnt 6 proto rstp maxaddr 2000 timeout 1200
root id 00:00:00:00:00:00 priority 32768 ifcost 0 port 0
ifmaxaddr 0 port 5 priority 128 path cost 2000000
ifmaxaddr 0 port 1 priority 128 path cost 20000
groups: bridge vm-switch viid-4c918@
nd6 options=1<PERFORMNUD>

Complete the Debian install:

Console into the VM and complete the typical Debian installation. If the installer is unable to
obtain an IP address then check the network settings (bridge and vm-bhyve switch)

$ sudo vm console debian

After completing the installation you should have a minimum Debian installation.

Add additional packages to make life easier:
$ apt-get install vim net-tools
Coming from BSD the lack of ifconfig or netstat is quite painful.

Install Docker

Please follow the Docker installation guide
After that follow this to open the API for remote access.

Docker is now fully configure and the hello-world should work:

$ docker run hello-world

Docker Management with Portainer

I assume you want to use a web frontend but you can as easily run Docker commands from within the VM.
Login via ssh or via vm console debian

Portainer is a web interface for Docker with a nice dashboard and logging capabilities.
Installation if pretty straight forward:

Run these commands from inside the VM:

$ docker volume create portainer_data
$ docker run -d -p 9000:9000 -v /var/run/docker.sock:/var/run/docker.sock -v portainer_data:/data portainer/portainer

Get the VM’s IP address:

$ ip address

And navigate to port 9000 to finish the install of Portainer. You could use a local socket connection but then every link in Portainer is
mapped to where when you would choose the external environment and use the IP address these mappings would work like you would expect.

These settings can be changed at Endpoints.


This is the rough outline of how to get Docker running on FreeBSD.

Is it wise to open the API?

Well you should secure that port with firewall rules
in a production setting.


  • Added info about the docker pkg.