Titan with Docker¶
Titan for docker is designed to run on any system that supports docker, but there are some dependencies that limit the set of supported operation systems, especially on Linux.
To help understand why this is necessary, it helps to understand a bit about the
architecture of Titan. To make titan possible, there is a container
titan-<context>-server) running in the background that provides data
versioning capabilities on top of ZFS. This requires
that ZFS be installed on the host operating system, but because of how
out-of-tree kernel modules work, this needs to be done by the titan software (a
titan-<context>-launch in particular). Titan attempts to
provide pre-built versions for common OSes, as well as a means to build them
on the fly for new versions, but there are limits to this system. If you are
not on a supported operating system, you may find
titan install taking a
long time to build binaries, or failing outright.
If we do not have a pre-built version of the ZFS binaries, we will attempt to build them on the fly. For Linux, we are still limited to the set of supported distributions, but we can build for slightly different variations or versions if needed. If you are running a Linux system other than a supported distribution, you can also compile and install ZFS yourself, provided it’s version 0.8.1, 0.8.2, or 2.0.*, and Titan will use that instead of trying to install its own.
If the installation is taking a while, and you see a
docker ps output, then it’s off building a custom version
of ZFS. If you are running a supported operating system, then reach out to the
community to see if new pre-built binaries need to be created.
MacOS and Windows¶
MacOS and Windows operate in a similar fashion, with an embedded
HyperKit VM running Linux behind the
scenes. This VM runs LinuxKit.
Titan supports Docker Desktop releases after Docker Community Edition 17.12.0-ce
for both Mac and
This version, released on 2018-01-09, is the first one completely built with the LinuxKit VM.
If you are running a very old distribution (for example, using the old
framework on Windows), you mileage may vary. You should update to the latest version of
Docker Desktop prior to using Titan.
If a brand new Docker Desktop release comes out that ships with a new
LinuxKit kernel, it may take some time for the community to update the
pre-built packages for the newest versions. If you encounter titan
trying to build packages for a new ZFS kernel, head over to the
and open an issue (or PR) with the new version and
uname -a output.
Titan does not work with the new Docker for WSL due to limitations in Docker that prevent local volumes from working properly.
System Specific Setup¶
On Windows, disable “Use the WSL2 Based Engine” in your Docker settings on Windows. We currently do not support Docker running via WSL2. You can always change this setting back later.
On Mac, disable “Use gRPC FUSE for file sharing”.
The situation with Linux is quite different. With Linux, there’s no standard Docker VM being provided by Docker Desktop. Instead, we’re running on whatever host VM you have. Because each distribution requires distro-specific mechanisms to download and install the right kernel files required to build ZFS, we have a much more limited support matrix. In addition, distros will often build specialized versions for different clouds (e.g. AWS, Azure, GCP), requiring specific builds for each of them. You’re much more likely to encounter an unsupported platform when running Titan on Linux, but the community tries to provide pre-built binaries for:
Ubuntu Bionic (18.04) and later
CentOS 7 and later
LinuxKit as used by Docker Desktop
If you are running one of these flavors and not finding pre-built binaries available, it’s likely just a matter of updating the zfs-releases repository with the latest build information. If you are trying to use a different distribution all together, or are trying a new major version for the first time in the community, you may need to update the zfs-builder repository such that it knows how to build the new variant.
If you are using an unsupported Linux version, you can always install ZFS yourself. Titan will use any installed ZFS, version 0.8.1 or later, and won’t attempt to install its own modules.