Waterfox in a docker image

This post is about a learning exercise, specifically learning to make a docker image which interacts with the GUI in the host system. It is a continuation of a previous post “Learning to use docker”.
It may be that some users may find the end product useful. Running Waterfox in a docker container enables it to be used reliably in any Linux distro, and even across different architectures.
It is not that a Waterfox install is all that difficult… you just download a tar file and unpack it and make a link. The only thing putting Waterfox in a docker container adds is a guarenteed run environment.

The issue of making a docker image which interacts with X11 in the host is quite simple. One just has to provide a means for programs running inside the container to access certain X11 files in the host system.

The big issue in doing this with Waterfox turned out to be tracing all the dependencies of Waterfox so that I could construct in the image environment all the things needed to make Waterfox startup and run. Waterfox is a huge program ( as large as Firefox). I had to work out a systematic method of finding all the dependencies. I think I have achieved that.

Another issue , is to construct a Dockerfile so that it is self sufficient… so that if someone else wants to build and run the Waterfox docker image, all I have to pass over to them is the Dockerfile… it will download everything else it needs.

So here is the Dockerfile which I think achieves all that

FROM debian:stable-20220801-slim
#set working dir inside container
RUN cd /etc/apt && \
# apt debian setup
  cp sources.list sources.list.orig && \
  sed 's/main/main contrib non-free/' sources.list.orig >sources.list && \
  cd /wfox && \
  apt-get update && \
  apt-get upgrade -y && \
  apt-get install -y apt-utils && \
# apt install packages for waterfox
  apt-get install -y  dconf-gsettings-backend gvfs gvfs-libs libc6 \
   libcom-err2 libdbus-1-3 libelogind0 libexpat1 libgcc-s1 \
   libgdk-pixbuf-2.0-0 libgl1-mesa-dri libgpg-error0 libkeyutils1 \
   liblzma5 libnss-mdns libpcre3 libpulse0 libselinux1 libtirpc3 \
   python3-minimal zlib1g && \
# apt install packages for waterfox libraries
  apt-get install -y libatk1.0-0 libatk-bridge2.0-0 libatspi2.0-0 libblkid1 libbrotli1 libbsd0 libc6 libcairo2 libcairo-gobject2 libdatrie1 libdbus-1-3 libdbus-glib-1-2 libepoxy0 libexpat1 libffi7 libfontconfig1 libfreetype6 libfribidi0 libgcc-s1 libgcrypt20 libgdk-pixbuf-2.0-0 libglib2.0-0 libglib2.0-dev libgpg-error0 libgraphite2-3 libgtk-3-0 libharfbuzz0b libice6 liblz4-1 liblzma5 libmd0 libmount1 libnspr4 libnss3 libpango-1.0-0 libpangocairo-1.0-0 libpangoft2-1.0-0 libpcre2-8-0 libpcre3 libpixman-1-0 libpng16-16 libselinux1 libsm6 libstdc++6 libsystemd0 libthai0 libuuid1 libwayland-client0 libwayland-cursor0 libwayland-egl1 libx11-6 libx11-xcb1 libxau6 libxcb1 libxcb-render0 libxcb-shm0 libxcomposite1 libxcursor1 libxdamage1 libxdmcp6 libxext6 libxext6-dbg libxfixes3 libxi6 libxinerama1 libxkbcommon0 libxrandr2 libxrender1 libxt6 libzstd1 zlib1g && \
# needed to unpack waterfox tarfile
 apt-get install -y bzip2 && \
# Mystery dependencies
  apt-get install -y libpci3 libpciaccess0 && \
  apt-get install -y libegl1 libegl-dev  && \
# apt-get install -y libgl1 libglfw3  && \
# Javascript packages
  apt-get install -y nodejs npm  && \
  apt-get install -y  gir1.2-javascriptcoregtk-4.0 javascriptcoregtk-4.0\
   javascript-common libnode72 && \
# firefox
# apt-get install -y firefox-esr && \
# locale
  apt-get install -y locales locales-all && \
#  get waterfox distro tarfile and unpack
  apt-get install -y wget && \
  cd /wfox 
RUN wget https://github.com/WaterfoxCo/Waterfox/releases/download/\
G4.1.5/waterfox-G4.1.5.en-US.linux-x86_64.tar.bz2 && \
  bzip2 -dc waterfox-G4.1.5.en-US.linux-x86_64.tar.bz2 | tar xvf - && \
  rm waterfox-G4.1.5.en-US.linux-x86_64.tar.bz2
# setup environment
RUN groupadd -g 1000 wfox
RUN useradd -d /home/wfox -s /bin/bash -m wfox -u 1000 -g 1000
RUN rm -fr /tmp/* /var/tmp/* /var/cache/*/*
USER wfox
ENV HOME /home/wfox
ENV TZ=Australia/Sydney
# exec waterfox
CMD /wfox/waterfox/waterfox

All you have to do if you want to try my waterfox docker image is copy and paste the above into a file called Dockerfile.
Then assuming you have docker installed, you do (caution this will lead to about 1.4Gb of downloads)

docker build -t wfoximage.v1 .

wfoximage.v1 is the name you give to the image. It can be anything. The dot ‘.’ is important
You will see lots of stuff scrolling, mostly downloads.
Then when it stops , if there are no errors, you should have an image. You can check with

docker images

It should be listed
Then to run the image you do (no downloads here, it just runs)

xhost +
docker run -v /tmp/.X11-unix:/tmp/.X11-unix -e DISPLAY=$DISPLAY -h $HOSTNAME -v $HOME/.Xauthority:/home/nevj/.Xauthority wfoximage.v1

Thats all. A Waterfox window should open. You will see a blank Welcome screen… all my Waterfox installs do that, but otherwise it all works, and looks just like Firefox.

Now that is all a bit brief , and does not tell the full story.
I have a pdf document which you may download if interested from here

You should click on the file wfoxdocker.pdf . It will most likely display, or if you want to download it , click the download button. Github sometimes refuses to display large pdf files, so if that happens, just download it.
On that same Github page are all the files referred to in the pdf document. The series of 7 Dockerfile attempts are in the dockerfiles subdirectory. The one Dockerfile.debv7 is the final version as listed above.

I would love to hear from anyone who tries it and finds issues. Lots of messages will scroll across the controlling window… that is apparently normal… Waterfox is under development.

I would like to acknowledge debugging assistance from @Akito and @kovacslt and help from @Rosika in the previous post.


I forgot to say what to do if you do not have docker installed.
In Debian it is

apt-get install docker.io

It is confusing. There is also a deb package called docker, but that is something else

1 Like

Hi Neville, :wave:


That´s quite an achievement. I really admire your stamina. :heart:

Unfortunately my download data allowance is limited to a certain extent, as you know.
Would´ve loved to try it out.

But I downloaded your pdf and am looking forward to reading it.

Thanks for mentioning me as well in your acknowledgements despite my very limited and humble input. I`m feeling honoured indeed… :heart:

Many greetings from Rosika :slightly_smiling_face:

1 Like

Thanks @Rosika ,
I wanted to warn you about the 1.4Gb download it generates, but you beat me to it.
If you wanted to try a docker example with a gui app, try the little xcalc example in the pdf document.

It turned out to be a much more difficult job than I envisaged.


1 Like

Thanks, Neville.

Yes, I noticed the 1.4 GB data when I read your post and I thought to myself: wow, that´s quite a project indeed.

Thanks for the hint. :+1:


Funny thing: I have xcalc available on my host (Lubuntu) but never used it so far. :blush:.

I think it´s part of a greater package x11-apps. However I use the command
firejail oclock -transparent (also from this package) every day. :wink:.

There´s so much more to the x11-apps package. I´m sure you know that, Neville.
But for anyone else interested here are the contents:

env LANG=en_US.UTF-8 apt-cache show x11-apps
Package: x11-apps

 This package provides a miscellaneous assortment of X applications
 that ship with the X Window System, including:
  - atobm, bitmap, and bmtoa, tools for manipulating bitmap images;
  - ico, a demo program animating polyhedrons;
  - oclock and xclock, graphical clocks;
  - rendercheck, a program to test render extension implementations;
  - transset, a tool to set opacity property on a window;
  - xbiff, a tool which tells you when you have new email;
  - xcalc, a scientific calculator desktop accessory;
  - xclipboard, a tool to manage cut-and-pasted text selections;
  - xconsole, which monitors system console messages;
  - xcursorgen, a tool for creating X cursor files from PNGs;
  - xditview, a viewer for ditroff output;
  - xedit, a simple text editor for X;
  - xeyes, a demo program in which a pair of eyes track the pointer;
  - xgc, a graphics demo;
  - xload, a monitor for the system load average;
  - xlogo, a demo program that displays the X logo;
  - xmag, which magnifies parts of the X screen;
  - xman, a manual page browser;
  - xmore, a text pager;
  - xwd, a utility for taking window dumps ("screenshots") of the X session;
  - xwud, a viewer for window dumps created by xwd;
  - Xmark, x11perf, and x11perfcomp, tools for benchmarking graphical
    operations under the X Window System;

Many greetings from Rosika :slightly_smiling_face:


… without any doubt. You´re really great, Neville. :+1:

Yes it is worth showing people that. I had to look it up myself. Years ago in BSD that used to be about all the gui apps you got in the standard system, so they came preinstalled along with X11 and the primitive twm window manager… Things have changed. Today you have to install them.
I had no idea what the package name was. Did a lot of searching, then I found apt-file. It works like a dream.


1 Like

Didn´t know that. Sounds great. :+1:

Well, things change all over the place. The important thing however is the apps can be (manually) installed.

Thanks for mentioning apt-file. If I remember correctly I heard of that command some while ago. I´ll look into it, as it seems interesting.

Many greetings.
Rosika :slightly_smiling_face:

1 Like