How to Run GUI-Based Applications Inside Docker?

Table of Contents#

1. Underlying Concepts: X11 and Wayland
2. Prerequisites
3. Method 1: Sharing the Host’s X11 Socket (Linux Only)
4. Method 2: Using a VNC Server Inside the Container (Cross-Platform)
5. Method 3: Docker Desktop’s Built-In X11 Support (Windows/macOS)
6. Advanced: Wayland for Modern GUI Apps
7. Common Practices & Best Practices
8. Troubleshooting Guide
9. Conclusion
10. References

1. Underlying Concepts: X11 and Wayland#

Before diving into methods, it’s critical to understand the display servers that power GUI apps on Linux (and by extension, Docker):

X11 (X Window System)#

The traditional display server for Linux. X11 handles rendering GUI windows, input from mice/keyboards, and communication between apps and the host display. It uses a Unix socket (/tmp/.X11-unix/X0) and DISPLAY environment variable to route GUI output to the host.

Wayland#

A modern replacement for X11 designed for security and performance. Wayland uses a simpler architecture and direct rendering, making it ideal for modern GTK4/Qt6 apps. It uses a socket at /run/user/<UID>/wayland-0 and the WAYLAND_DISPLAY variable.

2. Prerequisites#

• Linux: Docker installed, X11/Wayland display server running (preinstalled on most distros like Ubuntu, Fedora).
• Windows/macOS: Docker Desktop installed (with WSL2 backend for Windows).
• Optional: VNC viewer (e.g., RealVNC, TigerVNC) for cross-platform VNC-based methods.

3. Method 1: Sharing the Host’s X11 Socket (Linux Only)#

This method directly routes the container’s GUI output to the host’s X11 server. It’s fast and simple but limited to Linux hosts.

Step-by-Step Guide#

1. Ensure X11 Socket Access: The host’s X11 socket is located at /tmp/.X11-unix. We need to mount this into the container and set the DISPLAY variable.
2. Handle Permissions: The X11 server restricts access by default. Use one of two approaches:
   • Option 1 (Secure): Mount your ~/.Xauthority file (contains X11 access credentials) into the container.
   • Option 2 (Convenient): Allow local Docker containers to access the X11 server with xhost +local:docker.

Example: Running Firefox#

Dockerfile (Non-Root User for Security)#

FROM ubuntu:22.04
 
# Install dependencies and Firefox
RUN apt-get update && apt-get install -y --no-install-recommends \
    firefox-esr \
    && rm -rf /var/lib/apt/lists/*
 
# Create non-root user (matches host UID to avoid permission issues)
ARG USER_UID=1000
ARG USER_GID=1000
RUN groupadd -g $USER_GID dockeruser && \
    useradd -m -u $USER_UID -g $USER_GID dockeruser
 
# Switch to non-root user
USER dockeruser
 
# Set working directory
WORKDIR /home/dockeruser
 
# Run Firefox
CMD ["firefox-esr"]

Build and Run the Container#

# Option 1: Use Xauthority (secure)
docker build --build-arg USER_UID=$(id -u) --build-arg USER_GID=$(id -g) -t firefox-docker .
docker run -it --rm \
    -e DISPLAY=$DISPLAY \
    -e XAUTHORITY=/home/dockeruser/.Xauthority \
    -v $HOME/.Xauthority:/home/dockeruser/.Xauthority \
    -v /tmp/.X11-unix:/tmp/.X11-unix \
    -v $HOME/Downloads:/home/dockeruser/Downloads \
    firefox-docker
 
# Option 2: Use xhost (convenient)
xhost +local:docker
docker run -it --rm \
    -e DISPLAY=$DISPLAY \
    -v /tmp/.X11-unix:/tmp/.X11-unix \
    -v $HOME/Downloads:/home/dockeruser/Downloads \
    firefox-docker

Common Issues & Fixes#

• Permission Denied: Ensure the container user’s UID matches your host UID, or run xhost +local:docker.
• No Display Found: Verify the DISPLAY variable is set correctly (usually :0).

4. Method 2: Using a VNC Server Inside the Container (Cross-Platform)#

This method runs a VNC server inside the container, allowing you to connect via a VNC viewer from any OS (Linux, Windows, macOS). It’s ideal for cross-platform use cases.

Step-by-Step Guide#

1. Install a VNC Server: Use TigerVNC or TightVNC in your Docker image.
2. Expose VNC Port: VNC uses port 5901 (for display :1).
3. Set VNC Password: Secure access with a password.
4. Start the App: Launch the VNC server and the GUI app.

Example: Running GIMP with VNC#

Dockerfile#

FROM debian:bookworm
 
# Install GIMP and TigerVNC
RUN apt-get update && apt-get install -y --no-install-recommends \
    gimp \
    tigervnc-standalone-server \
    tigervnc-common \
    && rm -rf /var/lib/apt/lists/*
 
# Set up VNC password (replace 'your-secure-password' with your own)
RUN mkdir -p /root/.vnc && \
    echo 'your-secure-password' | vncpasswd -f > /root/.vnc/passwd && \
    chmod 600 /root/.vnc/passwd
 
# Configure VNC server
RUN echo "geometry=1920x1080" >> /root/.vnc/config && \
    echo "depth=24" >> /root/.vnc/config
 
# Start VNC and GIMP
CMD ["sh", "-c", "vncserver :1 && DISPLAY=:1 gimp && vncserver -kill :1"]

Build and Run#

docker build -t gimp-vnc .
docker run -it --rm -p 5901:5901 gimp-vnc

Connect to localhost:5901 using your VNC viewer and enter the password your-secure-password.

Best Practices for VNC#

• Use TLS Encryption: Add -x509 to the VNC server command to encrypt traffic.
• Web-Based Access: Install novnc in the container to access the GUI via a browser (expose port 6080).
• Minimize Resolution: Lower the VNC resolution if you experience lag on slow networks.

5. Method 3: Docker Desktop’s Built-In X11 Support (Windows/macOS)#

Docker Desktop for Windows and macOS provides built-in tools to route GUI output to the host.

Docker Desktop for macOS#

1. Install XQuartz: This is a macOS-compatible X11 server.

   brew install --cask xquartz

2. Enable Network Access: Open XQuartz → Preferences → Security → Check "Allow connections from network clients". Restart XQuartz.
3. Run the Container:

   docker run -it --rm \
       -e DISPLAY=host.docker.internal:0 \
       -v /tmp/.X11-unix:/tmp/.X11-unix \
       ubuntu:22.04 \
       sh -c "apt-get update && apt-get install -y x11-apps && xeyes"

   The xeyes app should appear on your macOS desktop.

Docker Desktop for Windows (WSL2 Backend)#

1. Install VcXsrv: A Windows X11 server (download from SourceForge).
2. Configure VcXsrv: Run VcXsrv with "Multiple windows", display number 0, and check "Disable access control".
3. Get WSL2 IP:

   $ip = Get-NetAdapter -Name "vEthernet (WSL)" | Get-NetIPAddress -AddressFamily IPv4 | Select-Object -ExpandProperty IPAddress

4. Run the Container:

   docker run -it --rm \
       -e DISPLAY=$ip:0 \
       ubuntu:22.04 \
       sh -c "apt-get update && apt-get install -y x11-apps && xeyes"

6. Advanced: Wayland for Modern GUI Apps#

Wayland is a modern display server that offers better security and performance than X11. It’s supported by most recent Linux distros (e.g., Fedora 38+, Ubuntu 22.04+).

Example: Running a GTK4 App with Wayland#

Dockerfile#

FROM fedora:39
 
# Install GTK4 dependencies
RUN dnf install -y --nogpgcheck \
    gtk4-devel \
    gcc \
    && dnf clean all
 
# Simple GTK4 app source
COPY hello-wayland.c /app/hello-wayland.c
WORKDIR /app
 
# Compile the app
RUN gcc hello-wayland.c -o hello-wayland `pkg-config --cflags --libs gtk4`
 
# Run the app
CMD ["./hello-wayland"]

hello-wayland.c Source Code#

#include <gtk/gtk.h>
 
static void activate(GtkApplication* app, gpointer user_data) {
  GtkWidget *window = gtk_application_window_new(app);
  gtk_window_set_title(GTK_WINDOW(window), "Hello Wayland!");
  gtk_window_set_default_size(GTK_WINDOW(window), 400, 300);
  gtk_widget_show(window);
}
 
int main(int argc, char **argv) {
  GtkApplication *app = gtk_application_new("org.example.HelloWayland", G_APPLICATION_DEFAULT_FLAGS);
  g_signal_connect(app, "activate", G_CALLBACK(activate), NULL);
  int status = g_application_run(G_APPLICATION(app), argc, argv);
  g_object_unref(app);
  return status;
}

Build and Run#

docker build -t hello-wayland .
docker run -it --rm \
    -e WAYLAND_DISPLAY=$WAYLAND_DISPLAY \
    -v /run/user/$(id -u)/wayland-0:/run/user/$(id -u)/wayland-0 \
    hello-wayland

7. Common Practices & Best Practices#

Security Considerations#

• Avoid xhost +: This allows untrusted apps to access your display server. Use xhost +local:docker instead.
• Non-Root Users: Always run containers as non-root users to limit damage if the container is compromised.
• VNC Passwords: Use strong passwords and TLS encryption for VNC connections.

Performance Optimization#

• Share IPC Namespace: Add --ipc=host to the docker run command to enable faster shared memory communication between the container and host.
• Use Lightweight Base Images: Alpine or Debian Slim instead of Ubuntu to reduce image size and improve startup times.
• GPU Acceleration: For graphics-heavy apps (e.g., video editors), use --gpus all to pass the host’s GPU to the container (requires NVIDIA Docker runtime or AMD ROCm).

Image Size Reduction#

• Multi-Stage Builds: Compile apps in a build image, then copy only the binary to a minimal runtime image.
• Clean Up Package Caches: Add rm -rf /var/lib/apt/lists/* or dnf clean all after installing dependencies.
• Use --no-install-recommends: Avoid installing unnecessary dependencies.

8. Troubleshooting Guide#

9. Conclusion#

Running GUI apps inside Docker is not only possible but also practical for many use cases. Whether you prefer the speed of X11 sharing (Linux), cross-platform VNC access, or modern Wayland support, there’s a method to fit your needs. By following best practices for security and performance, you can enjoy the isolation benefits of Docker while using your favorite GUI tools.

10. References#

• Docker Official Documentation
• X11 Protocol Specification
• Wayland Project
• TigerVNC Documentation
• XQuartz for macOS
• VcXsrv for Windows