docker-qmx-fusion/AGENTS.md

Developer Guide for Agentic Coding Agents

This guide provides the necessary context, commands, and conventions for working effectively in the docker-qmx-fusion repository.

1. Project Overview

This repository maintains the Docker image for QMX-Fusion, based on Chromium. It follows the LinuxServer.io standards. It uses the s6-overlay for process management and the selkies base image for GUI-in-browser functionality.

2. Critical Development Rules

• NEVER edit auto-generated files directly:
  • README.md (Edit readme-vars.yml instead)
  • Jenkinsfile (Edit jenkins-vars.yml instead)
  • package_versions.txt (Auto-generated by CI)
• Synchronize Dockerfiles: If you add a package or change logic in Dockerfile, ensure the same changes are applied to Dockerfile.aarch64.
• Package Sorting: Always list packages in apt-get install blocks in alphabetical order.
• Changelog: Every logic or Dockerfile change MUST include an entry in readme-vars.yml under the changelogs section.

3. Build, Lint, and Test Commands

Build

To build the image locally (amd64):

docker build --no-cache --pull -t lscr.io/linuxserver/chromium:latest .

Linting

We use shellcheck for all shell scripts. Run it on any script you modify:

shellcheck root/usr/bin/wrapped-chromium

Testing

Container testing is performed using the LinuxServer.io CI tool. To run tests locally, you need the built image and the CI container:

docker run --rm \
  --shm-size=1gb \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -e IMAGE="lscr.io/linuxserver/chromium" \
  -e TAGS="latest" \
  -t ghcr.io/linuxserver/ci:latest \
  python3 test_build.py

4. Configuration Management (readme-vars.yml)

The readme-vars.yml file is the source of truth for documentation and container parameters.

Adding Environment Variables

Add new variables under opt_param_env_vars (optional) or param_env_vars (required):

opt_param_env_vars:
  - { env_var: "CHROME_CLI", env_value: "https://www.linuxserver.io/", desc: "Specify Chromium CLI flags" }

Updating Changelog

Always add a new entry at the top of the changelogs list:

changelogs:
  - { date: "06.01.26:", desc: "Update logic for X feature." }

5. Code Style Guidelines

Shell Scripts (root/)

• Shebang: Always use #!/bin/bash.
• Indentation: Use 2 spaces for indentation.
• Wrapper Pattern: Follow the pattern in root/usr/bin/wrapped-chromium.
• Cleanup: Scripts should handle cleanup of temporary files (e.g., Chromium Singleton locks).
• Security: Check for privileged mode when necessary:

  if grep -q 'Seccomp:.0' /proc/1/status; then
    # Privileged mode logic
  fi
  

Dockerfiles

• Base Image: Use the specified LinuxServer.io base image (e.g., ghcr.io/linuxserver/baseimage-selkies).
• Layer Optimization: Chain commands with && \ and perform cleanup in the same RUN block to minimize image size.
• Cleanup Commands:

  apt-get autoclean && \
  rm -rf /var/lib/apt/lists/* /var/tmp/* /tmp/*
  

LinuxServer.io Conventions

• PUID/PGID: Support for user mapping is handled by the base image; ensure any new files in root/ are compatible with the abc user.
• S6 Overlay: Use S6 service files for process management if adding new background services. Ensure run scripts are executable (chmod +x). In this project, an nginx service is used to serve local content.

6. Error Handling and Logging

• Redirection: In Shell scripts, redirect stderr to stdout or /dev/null as appropriate: "$@" > /dev/null 2>&1.
• Exit Codes: Use set -e in complex scripts to exit on failure.
• Validation: Validate the existence of binaries or directories before execution.

7. Directory Structure

• /root: Files here are copied directly to the root of the container image.
• /root/defaults: Default configuration files for Openbox and autostart.
• /root/usr/bin: Custom scripts and wrappers.
• /root/etc/services.d: s6-overlay service definitions.
• /.github: CI/CD workflows and issue templates.

8. Multi-Architecture Support

• Always update both Dockerfile (amd64) and Dockerfile.aarch64 (arm64).
• Use lscr.io/linuxserver/qemu-static to build ARM images on x86 hardware.
• Avoid architecture-specific binaries in root/ unless handled by logic in scripts.