How to run docker on Qubes-OS

Docker-on-qubes.md

Docker on Qubes

Since this page is apparently the top result on google, Heres a link to how to do it.

https://martingladdish.co.uk/technology/setting-up-docker-under-qubesos/

That page has more detail, but here are the instructions in case its down.

1. Install docker engine, following the instruction on https://www.docker.com. NOT DESKTOP as that wont work in Qubes (unless you enable nested virtualization)
2. Make the below /etc/docker/daemon.json
3. Add "dockerd &" to your appvms (NOT TEMPLATE) /rw/config/rc.local

/etc/docker/daemon.json

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

Tried this with the debian-11 template on August 23, 2023. Martin did this with fedora-33 in 2021.

If you have trouble, you can ask for help at https://forum.qubes-os.org/

To do this in Qubes-OS 3.x, look at the history of this page.

NOTE: For anyone looking for an alternative method which works-as-intended, see also gist:Install Docker on Qubes OS 4.2. The following are the condensed steps required, without the verbose explanations accompanying each step.

Since there is not a documented reliability concern for "bind-dirs" facility, mainly just a matter of "that's a whole lotta words, too bad I'm not readin' 'em" when it comes to documentation, immediately followed by struggles to understand why things are not working; here we provide "the Qubes way" of solving for both that does not leave "bind-dirs" in a broken state.

Configure TemplateVM

sudo apt install -y docker.io
sudo systemctl disable containerd
sudo systemctl disable docker
[[ $(getent group docker) == '' ]] && sudo groupadd docker;
sudo usermod -aG docker user;
[ ! -d /etc/docker ] && sudo mkdir -p /etc/docker && sudo chmod 755 /etc/docker;
[ ! -d /var/lib/docker ] && sudo mkdir -p /var/lib/docker && sudo chmod 710 /var/lib/docker;
sudo mkdir -p /etc/qubes-bind-dirs.d
sudo touch /etc/qubes-bind-dirs.d/30_docker.conf
sudo chmod 644 /etc/qubes-bind-dirs.d/30_docker.conf
echo "binds+=( '/var/lib/docker' )" | sudo tee --append /etc/qubes-bind-dirs.d/30_docker.conf
echo "binds+=( '/etc/docker' )" | sudo tee --append /etc/qubes-bind-dirs.d/30_docker.conf

Enable docker service for AppVM(s)

Remember to change $QUBENAME to be the name of your target AppVM/Qube:

qvm-service --enable $QUBENAME docker

Verification inside AppVM

Exit the dom0 shell.
Shutdown your TemplateVM, saving all changes.
Launch a terminal in your AppVM to perform verifications:

systemctl status containerd
systemctl status docker
docker run --rm -it busybox

After exiting busybox, you can verify "bind-dirs" is working as intended by restarting the AppVM (sudo reboot), then launching a new AppVM terminal verify the busybox image persisted between restarts (optionally removing the image):

docker images
docker rmi busybox

Why would I do it this way?

1. It preserves the privilege model and run time environment intended by docker devs and/or package authors.
2. It leverages package-supplied units for service start-up and configuration, which may change over time.
3. It is DispVM friendly.

Generally, this eliminates any configuration steps from being "inside the AppVM", any time we have to modify /rw/ directly from "inside" an AppVM we're taking an "advanced approach" to administration of our Qubes meant for solving problems that can't be solved by any regular means. To illustrate: Why bootstrap docker from the TemplateVM? Why not bootstrap everything from rc.local? Because it is inconvenient, and not necessary, unless you are trying to keep everything outside of the TemplateVM and only need docker in a single AppVM.

These means and reasons apply to more than just docker.

EDIT: removed unnecessary packages from apt install command and corrected incorrect package name, added commands to disable containerd and docker daemons in the TempalteVM, removed qvm-service --enable call for containerd as suggested by @runephilosof-abtion

I agree with @sw4k. A few corrections though.

For debian, the docker package from https://docs.docker.com/engine/install/debian/#install-using-the-repository is called docker-ce.
They recommend installing these sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
In Debian the services are enabled by default when you install them (in Fedora they are disabled), so you will have to disable them in the template after install, if you want it only enabled through qvm-service.
You don't need to enable containerd, since the docker service depends on it.

Thanks for this snippet. Not sure how accurate this is but in case you have issues with performing the post installation steps, try performing them in the Template VM vs the App VM