Running GUI Apps with X11 in Containers

1. 1

   Install Xorg and start it at boot

   X11 needs a functional Xorg server. Install it:

   bash · install Xorg

   sudo apt install x11-xserver-utils

   Verify the installation:

   bash · check version

   Xorg -version

   To start Xorg at boot, create a systemd service file:

   bash · create service file

   sudo nano /etc/systemd/system/xorg.service

   config · /etc/systemd/system/xorg.service

   [Unit]
   Description=Xorg Display Server
   After=network.target
   
   [Service]
   ExecStart=/usr/bin/Xorg :0
   Restart=always
   User=root
   Environment=DISPLAY=:0
   
   [Install]
   WantedBy=multi-user.target

   Enable, start, and check the service:

   bash · enable & start

   sudo systemctl enable xorg.service
   sudo systemctl start xorg.service
   sudo systemctl status xorg.service

   A black screen after starting the Xorg service is expected.

2. 2

   Share the X11 socket with containers

   Option 1 — scoped xhost access (temporary)

   If the container runs as root, grant only the local root identity access for the current X session:

   bash · scoped xhost access

   DISPLAY=:0 XAUTHORITY=/root/.Xauthority xhost +SI:localuser:root
   
   # Revoke after stopping the container
   DISPLAY=:0 XAUTHORITY=/root/.Xauthority xhost -SI:localuser:root

   Do not use xhost +

   xhost + disables X11 access control for every client. Use the scoped identity rule above and revoke it when the container stops.

   Option 2 — scoped systemd service

   For a dedicated display deployment, persist the same scoped identity rule and revoke it when the service stops:

   bash · create service file

   sudo nano /etc/systemd/system/xhost.service

   config · /etc/systemd/system/xhost.service

   [Unit]
   Description=Allow local container root to access X11
   After=xorg.service
   Requires=xorg.service
   
   [Service]
   Type=oneshot
   Environment=DISPLAY=:0
   Environment=XAUTHORITY=/root/.Xauthority
   ExecStart=/usr/bin/xhost +SI:localuser:root
   ExecStop=-/usr/bin/xhost -SI:localuser:root
   RemainAfterExit=true
   
   [Install]
   WantedBy=multi-user.target

   Enable and start it:

   bash · enable & start

   sudo systemctl enable xhost.service
   sudo systemctl start xhost.service

3. 3

   Configure the deployment for X11 access

   In ALPON Cloud, open the Applications tab of your asset and start a new deployment. Configure it as follows:

   

   Container name & image — choose a name, then select the image and tag holding your X11 application (from the Sixfab Container Registry or a custom path).

   Environment — set DISPLAY so output appears on the host's screen. Confirm the value on the device with echo $DISPLAY (typically :0).

   DISPLAY :0

   Volumes — mount the X11 socket and the .Xauthority file so the container can reach the graphical environment:

   X11 socket (read-only) /tmp/.X11-unix → /tmp/.X11-unix

   Authorization file (read-only) /root/.Xauthority → /root/.Xauthority

   Privileges — leave Privileged disabled unless the application requires separate hardware access that cannot be expressed with a targeted device or bind mount. Deploy, verify the GUI, and revoke temporary xhost access when finished.

Troubleshooting

Make sure a display is physically connected. Without one, xhost + fails to open the display:

xhost: unable to open display ""

If a display is connected, export the variable and retry:

export DISPLAY=:0

The xhost.service may also fail when no display is available:

× xhost.service - Allow X11 access to containers
     Loaded: loaded (/etc/systemd/system/xhost.service; enabled; preset: enabled)
     Active: failed (Result: exit-code)
    Process: 52110 ExecStart=/usr/bin/xhost + (code=exited, status=1/FAILURE)

xhost[52110]: /usr/bin/xhost:  unable to open display ""
systemd[1]: xhost.service: Failed with result 'exit-code'.
systemd[1]: Failed to start xhost.service - Allow X11 access to containers.

These errors mean the X11 display is unavailable — usually because no physical display is connected or the setup is misconfigured.

Deployment settings in ALPON Cloud for an X11-enabled container.