This guide is designed to help users of the ALPON X4 micro-edge computer run graphical applications within containers using the X11 display protocol. By utilizing X11, graphical user interfaces (GUIs) can be rendered on a display connected to the ALPON X4 while keeping the application containerized. Containerization ensures that applications are isolated and portable, while X11 enables seamless interaction with graphical interfaces.

The process outlined in this document includes setting up the X11 display server on the ALPON X4, configuring it to work with containers, and deploying applications that require a graphical interface. It is essential that a display is physically connected to the ALPON X4 for this setup to function correctly. Without a connected display, commands such as xhost + or related system services may fail, resulting in errors like the inability to open the display or service failures.

By following the steps in this guide, users can:

• Enable X11 on the ALPON X4 to manage graphical applications within containers.
• Configure permissions to allow containers to access the X11 server.
• Deploy and run containerized graphical applications efficiently.

This guide assumes basic familiarity with Linux commands and the Sixfab Connect platform. It is structured to provide clear, step-by-step instructions to ensure successful implementation, even for users new to X11 or containerization.

Install Xorg

To use X11, the ALPON X4 must have a functional Xorg server and display manager installed.

Install the Xorg server, which is responsible for managing graphical displays:

sudo apt install x11-xserver-utils

Verify Xorg Installation

After installation, verify that Xorg is installed correctly by checking its version:

Xorg -version

Starting Xorg at System Boot

3.1 Create a Service File
To enable Xorg to start at boot, create a systemd service file:

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

3.2 Edit the Service File
Add the following content to the file:

[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

3.3 Enable the Service
Enable the service to start automatically at boot:

sudo systemctl enable xorg.service

3.4 Start and Test the Service
Manually start the service and check its status to ensure it's working:

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

Share X11 Socket with the Container

To allow a container to access the X11 display, you'll need to share the X11 socket from your ALPON X4 with the container.

Option 1 — Set X11 Permissions (Temporary solution)

Grant access to the X11 display for containers:

xhost +

This command temporarily allows connections from local containers to the X11 display.

❗️

Security Warning

The xhost + command temporarily disables access control for the X11 server, allowing any user or application to connect. This poses a significant security risk and should only be used for testing or in trusted environments. Avoid using it in production systems.

Option 2 — Set permissions with systemd (Permanent solution)

Grant access to the X11 display for containers with systemd service.

1. Create the Systemd Service File

To create a new service file, run the following command:

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

2. Edit the Service File

Add the following content to the service file. This service will run the xhost + command when the system starts.

[Unit]
Description=Allow X11 access to containers
After=graphical.target

[Service]
Type=oneshot
ExecStart=/usr/bin/xhost +
RemainAfterExit=true

[Install]
WantedBy=multi-user.target

3. Enable and Start the Service

To enable and start the service, use the following commands:

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

Configuring App Deployment for X11 Access

To run graphical applications inside containers on your ALPON X4, you need to configure the deployment settings in Sixfab Connect. This process ensures that the container can interact with the X11 server on the host machine, allowing graphical user interfaces (GUIs) to be displayed properly. Follow the steps below to deploy your X11-enabled application:

1. Access the Applications Tab

Log in to your Sixfab Connect platform and navigate to the Applications tab of your asset.

2. Configure Deployment Settings

In the deployment configuration screen, fill in the following details:

Container Name

Choose a name for your container.

Image & Tag

• Select the Docker image that contains your X11 application.
• You can either use a pre-built image from the Sixfab registry or specify the path to a custom image.
• Set the appropriate tag for the image to ensure the correct version of the application is deployed.

Environments

Configure the environment variables to ensure your container can interact with the X11 server on the device:

• DISPLAY: Set this to the host's display environment variable, typically :0, so that the graphical output will appear on the host's screen.

  Key	Value
  DISPLAY	:0

  To confirm the display value, you can run the following command on the device:
  
  

  Shell

  echo $DISPLAY
  

Volumes

The container needs access to the X11 socket and the .Xauthority file to interact with the graphical environment.

Configure the following volumes:

• Mount X11 Socket
  Mount the X11 socket from the host system to the container:

  Local Path	Target Path
  /tmp/.X11-unix	/tmp/.X11-unix

  
  

• Mount .Xauthority File
  The .Xauthority file stores authentication data for the X11 server. Mount this file to ensure proper access:

  Local Path	Target Path
  /root/.Xauthority	/root/.Xauthority

Privileged Mode

To allow the container full access to the X11 server, enable the "Privileged" option.

Deploy the Application

Once all settings are configured, click Deploy to start the container with X11 access.

The graphical application inside the container should now be able to render its GUI on the connected display of the ALPON X4.

Troubleshooting

Ensure that a display is physically connected to the ALPON X4. Without a connected display, commands like xhost + may result in errors such as:

If your display is connected, run the following command:

export DISPLAY=:0

Additionally, the xhost.service may fail with the following logs:

These errors indicate that the X11 display is unavailable due to the absence of a physical display or misconfiguration.

📘

Note

A black screen after starting Xorg service is to be expected.

Following the steps outlined in this guide, you can successfully run graphical applications within containers using X11 on your host machine. This approach allows you to leverage the benefits of containerization while maintaining the ability to visualize and interact with GUI applications seamlessly. If you encounter any issues, ensure that your environment variables are correctly set and that the necessary permissions are granted for X11 access.