Setting up docker in QubesOS

I’ve not yet written anything about my experience running QubesOS as my development machine although it really is overdue.

In the meantime I thought I’d get this little tidbit down as there are tons of resources out on the web that are now very out of date and give very complicated and now incorrect solutions.

The following instructions are all for Fedora-33 VMs.

Install docker in your template VM

Just like any other software install, the binaries need to live in your template VM.

Get your chosen template VM started up (in this case Fedora-33) and install both docker and docker-compose as normal.

sudo dnf install docker

sudo dnf install docker-compose

Next, we want to make sure that the images used in app VM A don’t interfere with images used in app VM B, so we need to tell docker where they should live. In this case, I’ve gone with putting them in the user’s home directory.

To configure dockerd in each VM, we can provide a daemon.json in the default location where dockerd is going to find it (create this dir/file if it doesn’t yet exist):

/etc/docker/daemon.json

{
    "data-root": "/home/user/docker",
    "group": "user"
}

NB: The group entry is there to set the owning group of docker’s sock file. Without this, docker running in the VM won’t have rights to access its sock, so won’t be able to communicate with docker’s api.

Start docker when your app VM starts

In your app VM:

Add the following line to your /rw/config/rc.local

#...

dockerd &

#...

This will run dockerd every time your app VM boots.

Clean up

Shutdown both the template VM and your app VM to sync their filesystems, then the next time you start your app VM you’ll have a fully-functioning docker system.

Update February 2024

I’ve just installed QubesOS 4.1 so had to go through all this again. Unfortunately I got a ton of these errors when running docker-compose:

docker-proxy executable not found in $PATH

Worse, if you miss that error the first time around then try to start containers (that expose ports) again it throws a load of Cannot start container: port has already been allocated errors.

It turns out the docker binaries from the default repos are a bit broken - there really was no docker-proxy binary installed (Note: on Fedora 39). So uninstalling docker and re-installing from docker’s own repos, as per their own instructions is enough to get it all working as expected.