DOCSEARCHbyAlgolia
Submit Docs

jlesage/docker-baseimage-gui

repository·master·Indexed 23 days ago

https://github.com/jlesage/docker-baseimage-gui

A minimal Docker baseimage for running X graphical applications on headless servers, accessible via web browser (port 5800) or VNC (port 5900). It supports Alpine, Debian, and Ubuntu distributions and includes helpers for package management (add-pkg, del-pkg), environment variable configuration (set-cont-env), and a process supervisor for managing background services.

Tokens
14.4K
Snippets
17
Records
65
Agent score
78%

What's inside jlesage-docker-baseimage-gui

  1. Understand Docker image tag versioning

    master

    Docker image tags follow semantic versioning (MAJOR.MINOR.PATCH) and allow you to pin to specific versions or use floating tags for updates:

    • distro-vX.Y.Z: An exact version of the image.
    • distro-vX.Y: The latest version of a specific minor version.
    • distro-vX: The latest version of a specific major version.

  2. Core components of the baseimage

    master

    The baseimage provides a pre-configured environment for running X applications, including:

    • Initialization system: Handles container startup.
    • Process supervisor: Provides proper PID 1 functionality (e.g., process reaping).
    • TigerVNC: An X server with an integrated VNC server.
    • Openbox: A lightweight window manager.
    • noVNC: An HTML5 VNC client for web access.
    • NGINX: A high-performance HTTP server for the web interface.
    • Optimized environment: Tools and settings specifically for Dockerized GUI applications.

  3. Configure application data directories in /config

    master

    All persistent application data (configs, logs, state) should be stored in the /config directory, which is intended to be mapped to a host volume.

    The baseimage automatically configures XDG Base Directory Specification variables to point under /config/:

    • XDG_DATA_HOME=/config/xdg/data
    • XDG_CONFIG_HOME=/config/xdg/config
    • XDG_CACHE_HOME=/config/xdg/cache
    • XDG_STATE_HOME=/config/xdg/state

  4. Use initialization and finalization scripts

    master

    The baseimage provides hooks for running scripts at specific stages of the container lifecycle:

    Initialization Scripts

    Located in /etc/cont-init.d/. They run in alphabetical order before services start.

    • Naming Convention: Use XX-name.sh (e.g., 10-setup.sh) to ensure predictable order.
    • Recommended Range: Use 50-59 for custom application logic to avoid conflicts with baseimage ranges (10-29 and 70-89).

    Finalization Scripts

    Located in /etc/cont-finish.d/. They run in alphabetical order after all services have stopped during container shutdown.

  5. Choose between Alpine or Debian/Ubuntu baseimages

    master

    When selecting a baseimage for your GUI application, consider the following trade-offs:

    • Alpine Linux (Recommended): Offers a compact size and is designed for security, simplicity, and resource efficiency. It uses musl and BusyBox. Note that because it uses musl instead of glibc, some applications might face compatibility issues if they are not built for Alpine.
    • Debian/Ubuntu: Provides excellent compatibility with existing applications that expect glibc, making it easier to integrate software that isn't available in Alpine's repositories or lacks source code for Alpine.

  6. Add internal environment variables via files

    master

    You can define internal environment variables by creating files in /etc/cont-env.d/ inside the container.

    • The filename is the variable name.
    • The file content is the variable value.
    • If the file is executable, the variable's value is taken from the file's standard output.

    Important Notes:

    • If the execution returns code 100, the variable is not set.
    • stderr output from the executable is redirected to the container logs.
    • Use the set-cont-env helper in your Dockerfile to set these variables.

  7. Enable Automatic Clipboard Sync

    master

    Allows seamless copy-paste between the host and the container via a web browser.

    Requirements:

    • Must use a Chromium-based browser (e.g., Chrome, Edge).
    • Must use HTTPS (SECURE_CONNECTION=1).
    • Does not work with VNC clients.

    If automatic sync is unavailable, use the side panel clipboard for manual transfer.

  8. Understand the Container Startup and Shutdown sequences

    master

    The baseimage follows a specific lifecycle for managing services and initialization.

    Startup Sequence

    1. The init process (/init) is invoked.
    2. Internal environment variables are loaded from /etc/cont-env.d.
    3. Initialization scripts in /etc/cont-init.d are executed (alphabetical order).
    4. Control is passed to the process supervisor.
    5. The service group /etc/services.d/default and its dependencies are loaded.
    6. Services are started in order.

    Shutdown Sequence

    Triggered by application termination or a docker stop command:

    1. All services are terminated in reverse order.
    2. SIGTERM is sent to running processes.
    3. After 5 seconds, remaining processes are killed via SIGKILL.
    4. The process supervisor executes the exit script (/etc/services.d/exit).
    5. Finalization scripts in /etc/cont-finish.d/ are executed (alphabetical order).

  9. Configure the container using Public Environment Variables

    master

    You can customize the container and application behavior using Public Environment Variables. These can be set during container creation using the -e "<VAR>=<VALUE>" argument of the docker run command.

    Note: If a variable is defined as both internal and public, the public value takes precedence.

  10. Use Docker Secrets as environment variables

    master

    The baseimage automatically exports Docker secrets as environment variables if they follow the naming convention CONT_ENV_<environment variable name>.

    For example, a secret named CONT_ENV_MY_PASSWORD will be available as the environment variable MY_PASSWORD inside the container.

  12. Get started with the baseimage

    master

    To create a Docker container for a graphical application, you need three components in your Dockerfile:

    1. Instructions to install the application and its dependencies.
    2. A script to start the application, stored at /startapp.sh in the container.
    3. The name of the application set via the APP_NAME environment variable.

    Follow these steps to build and run an example container (e.g., xterm):

    1. Create a startapp.sh script with exec <path_to_binary>.
    2. Make the script executable: chmod +x startapp.sh.
    3. Create a Dockerfile using the baseimage, installing dependencies, copying the script, and setting APP_NAME.
    4. Build the image: docker build -t <tag> ..
    5. Run the container, mapping ports 5800 (Web GUI) and 5900 (VNC).
    ### Dockerfile
```dockerfile
# Pull the baseimage.
FROM jlesage/baseimage-gui:alpine-3.19-v4

# Install xterm.
RUN add-pkg xterm

# Copy the start script.
COPY startapp.sh /startapp.sh

# Set the application name.
RUN set-cont-env APP_NAME "Xterm"

    startapp.sh

    #!/
exec /usr/bin/xterm

    Build and Run

    chmod +x startapp.sh
docker build -t docker-xterm .
docker run --rm -p 5800:5800 -p 5900:5900 docker-xterm