How to Install Docker on FreeBSD via Linux Compatibility

Docker has become an essential tool for software development and deployment, but it’s not natively available for FreeBSD. However, thanks to FreeBSD’s Linux compatibility layer, it’s possible to run Docker containers on FreeBSD systems. This guide provides a detailed, step-by-step approach to installing and configuring Docker on FreeBSD using the Linux compatibility features.

Table of Contents

1. Introduction
2. Prerequisites
3. Setting Up Linux Compatibility Layer
4. Installing Docker
5. Configuring Docker
6. Testing Your Docker Installation
7. Troubleshooting Common Issues
8. Performance Considerations
9. Limitations
10. Conclusion

Introduction

FreeBSD is known for its stability, performance, and advanced features like the ZFS filesystem. While Docker was developed primarily for Linux, FreeBSD’s Linux compatibility layer (linuxulator) allows you to run many Linux applications, including Docker. This approach enables FreeBSD users to leverage the vast ecosystem of Docker containers while continuing to enjoy FreeBSD’s benefits.

It’s important to note that running Docker through the Linux compatibility layer has some performance overhead and limitations compared to running Docker natively on Linux. However, for many use cases, the performance is more than adequate, and the convenience of using Docker containers on FreeBSD outweighs these limitations.

Prerequisites

Before starting the installation process, ensure your system meets the following requirements:

• FreeBSD 13.0 or newer (earlier versions may work but aren’t officially supported for this guide)
• Root or sudo access to your FreeBSD system
• At least 2GB of RAM (4GB or more recommended for running multiple containers)
• At least 20GB of free disk space
• A stable internet connection for downloading packages
• Basic familiarity with FreeBSD system administration and the command line

Setting Up Linux Compatibility Layer

FreeBSD’s Linux compatibility layer allows Linux binaries to run on FreeBSD. We’ll need to configure this layer before installing Docker.

1. Enable Linux Compatibility in the Kernel

First, ensure that the Linux compatibility module is loaded. Add the following line to /etc/rc.conf:

linux_enable="YES"

Load the Linux kernel module immediately without rebooting:

# kldload linux64

Verify that the module is loaded:

# kldstat | grep linux

You should see output indicating that the Linux module is loaded.

2. Install Linux Base

FreeBSD provides Linux base packages that provide core Linux functionality. Let’s install the CentOS 7 base, which works well with Docker:

# pkg install linux_base-c7

3. Configure Linux Filesystems

Docker requires several Linux-specific filesystems. Add the following lines to /etc/fstab:

linprocfs   /compat/linux/proc      linprocfs   rw,late    0   0
linsysfs    /compat/linux/sys       linsysfs    rw,late    0   0
tmpfs       /compat/linux/dev/shm   tmpfs       rw,late,mode=1777    0   0
fdescfs     /dev/fd                 fdescfs     rw,late,linrdlnk     0   0

Mount these filesystems without rebooting:

# mount /compat/linux/proc
# mount /compat/linux/sys
# mount /compat/linux/dev/shm
# mount /dev/fd

4. Set Up Linux System Directories

Create necessary Linux system directories:

# mkdir -p /compat/linux/dev/pts
# mkdir -p /compat/linux/dev/shm
# mkdir -p /compat/linux/proc
# mkdir -p /compat/linux/sys

Installing Docker

Now that the Linux compatibility layer is set up, we can install Docker.

1. Download the Docker Installation Script

We’ll use the official Docker installation script:

# fetch https://get.docker.com -o /tmp/get-docker.sh

2. Make the Script Compatible with FreeBSD

Since we’re running on FreeBSD, we need to modify the environment to make the script think it’s running on Linux:

# cd /tmp
# brandelf -t Linux get-docker.sh
# chmod +x get-docker.sh

3. Install Docker

Now run the Docker installation script within the Linux compatibility environment:

# linux get-docker.sh

This command will download and install Docker and its dependencies. The installation might take a few minutes depending on your internet connection speed.

Configuring Docker

After installation, we need to configure Docker to work properly on FreeBSD.

1. Create Docker Configuration Directory

# mkdir -p /compat/linux/etc/docker

2. Configure Docker Daemon

Create a configuration file for the Docker daemon:

# ee /compat/linux/etc/docker/daemon.json

Add the following configuration:

{
  "data-root": "/var/lib/docker",
  "storage-driver": "overlay2",
  "iptables": false,
  "ip-forward": false,
  "bridge": "none",
  "hosts": ["unix:///var/run/docker.sock"]
}

This configuration:

• Sets the Docker data directory
• Uses the overlay2 storage driver, which works with FreeBSD’s ZFS
• Disables iptables (which doesn’t work on FreeBSD)
• Disables IP forwarding and bridge networking (which require additional configuration on FreeBSD)
• Configures Docker to listen on a Unix socket

3. Set Up Docker to Start on Boot

Add Docker to the startup services by adding this line to /etc/rc.conf:

docker_enable="YES"

4. Create a Service Script for Docker

Create a service script for Docker:

# ee /usr/local/etc/rc.d/docker

Add the following content to the file:

#!/bin/sh
#
# PROVIDE: docker
# REQUIRE: LOGIN linux
# KEYWORD: shutdown
#
# Add the following lines to /etc/rc.conf.local or /etc/rc.conf
# to enable this service:
#
# docker_enable (bool):   Set to NO by default.
#                         Set it to YES to enable docker.

. /etc/rc.subr

name="docker"
rcvar=docker_enable

load_rc_config $name

: ${docker_enable:="NO"}

start_cmd="${name}_start"
stop_cmd="${name}_stop"
status_cmd="${name}_status"

docker_start()
{
    echo "Starting Docker daemon"
    /usr/bin/linux /usr/bin/dockerd > /var/log/docker.log 2>&1 &
    echo $! > /var/run/docker.pid
}

docker_stop()
{
    if [ -f /var/run/docker.pid ]; then
        echo "Stopping Docker daemon"
        kill `cat /var/run/docker.pid`
        rm /var/run/docker.pid
    else
        echo "Docker is not running"
    fi
}

docker_status()
{
    if [ -f /var/run/docker.pid ]; then
        echo "Docker is running as pid `cat /var/run/docker.pid`"
    else
        echo "Docker is not running"
    fi
}

run_rc_command "$1"

Make the script executable:

# chmod +x /usr/local/etc/rc.d/docker

5. Start Docker

Start the Docker service:

# service docker start

Testing Your Docker Installation

Let’s verify that Docker is working correctly.

1. Check Docker Version

# linux docker --version

You should see output similar to: Docker version 24.0.6, build ed223bc

2. Run a Test Container

Try running the “hello-world” container to verify Docker is functioning correctly:

# linux docker run hello-world

If Docker is working properly, you’ll see a message confirming that your installation is working correctly.

3. Try a More Complex Container

Let’s test a more complex container, such as NGINX:

# linux docker run -d -p 8080:80 --name test-nginx nginx

This command runs an NGINX container in the background and maps port 8080 on your FreeBSD host to port 80 in the container.

Access the NGINX welcome page by opening a web browser and navigating to http://localhost:8080 or using curl:

# curl http://localhost:8080

You should see the NGINX welcome page HTML.

Troubleshooting Common Issues

Docker Daemon Fails to Start

If the Docker daemon fails to start, check the Docker logs:

# cat /var/log/docker.log

Common issues include:

• Missing Linux compatibility filesystems (check that all required filesystems are mounted)
• Permission problems (ensure proper permissions on /var/run/docker.sock)
• Conflicts with existing FreeBSD network configuration

Container Networking Issues

If containers can’t connect to the internet or each other:

1. Check if the Docker bridge network is created:

# linux docker network ls

2. Verify that FreeBSD’s firewall allows traffic from Docker containers:

# pfctl -s rules  # For PF firewall
# ipfw list       # For IPFW firewall

You may need to add rules to allow traffic from Docker’s network ranges.

Storage Driver Problems

If you encounter storage driver errors:

1. Try changing the storage driver in /compat/linux/etc/docker/daemon.json to “vfs”, which is slower but more compatible:

{
  "storage-driver": "vfs"
}

2. Restart Docker after making changes:

# service docker restart

Performance Considerations

Running Docker through FreeBSD’s Linux compatibility layer introduces some overhead compared to running Docker natively on Linux. Here are some tips to optimize performance:

1. Use ZFS for Docker’s storage: ZFS offers excellent performance and features like compression and snapshots.

2. Allocate sufficient memory: Docker consumes additional memory when running through the Linux compatibility layer. Ensure your system has at least 4GB of RAM for optimal performance.

3. Consider CPU limitations: The Linux compatibility layer adds CPU overhead. Plan for this when determining how many containers you can run efficiently.

4. Monitor resource usage: Use tools like top, htop, or zfs list to monitor system resources and adjust your container deployment accordingly.

Limitations

When running Docker on FreeBSD via Linux compatibility, be aware of these limitations:

1. No native FreeBSD containers: You can only run Linux containers, not FreeBSD containers.

2. Networking limitations: Some advanced Docker networking features may not work as expected.

3. Performance overhead: There’s always some performance penalty compared to running Docker natively on Linux.

4. Limited hardware access: Direct hardware access from containers may be restricted or unavailable.

5. Compatibility issues: Not all Docker features are guaranteed to work, especially newer or more experimental ones.

Conclusion

While Docker doesn’t natively support FreeBSD, the Linux compatibility layer provides a viable workaround for running Docker containers on FreeBSD systems. This approach allows FreeBSD users to leverage the vast ecosystem of Docker containers while continuing to enjoy FreeBSD’s robust features, security, and stability.

For production environments with critical Docker workloads, you might want to consider using dedicated Linux hosts or virtual machines for Docker. However, for development, testing, and many production scenarios, Docker on FreeBSD via Linux compatibility works remarkably well.

By following this guide, you’ve successfully set up Docker on your FreeBSD system and can now explore the world of containerized applications while maintaining your FreeBSD infrastructure.