diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..0c5845d --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,102 @@ +# 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](https://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): +```bash +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: +```bash +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: +```bash +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): +```yaml +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: +```yaml +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: + ```bash + 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:** + ```bash + 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. diff --git a/Dockerfile b/Dockerfile index 85dfa45..75a3bdf 100644 --- a/Dockerfile +++ b/Dockerfile @@ -9,7 +9,8 @@ LABEL build_version="Linuxserver.io version:- ${VERSION} Build-date:- ${BUILD_DA LABEL maintainer="thelamer" # title -ENV TITLE=Chromium +ENV TITLE=QMX-Fusion +ENV CHROME_CLI="--kiosk http://localhost" RUN \ echo "**** add icon ****" && \ @@ -20,7 +21,13 @@ RUN \ apt-get update && \ apt-get install -y --no-install-recommends \ chromium \ - chromium-l10n && \ + chromium-l10n \ + git \ + nginx && \ + echo "**** clone web content ****" && \ + git clone https://github.com/Sparks72/QMX-Fusion-v1 /var/www/fusion-v1 && \ + chown -R abc:abc /var/www/fusion-v1 && \ + rm -f /etc/nginx/sites-enabled/default && \ echo "**** cleanup ****" && \ apt-get autoclean && \ rm -rf \ diff --git a/Dockerfile.aarch64 b/Dockerfile.aarch64 index fbe8cb9..dc04d9c 100644 --- a/Dockerfile.aarch64 +++ b/Dockerfile.aarch64 @@ -9,7 +9,8 @@ LABEL build_version="Linuxserver.io version:- ${VERSION} Build-date:- ${BUILD_DA LABEL maintainer="thelamer" # title -ENV TITLE=Chromium +ENV TITLE=QMX-Fusion +ENV CHROME_CLI="--kiosk http://localhost" RUN \ echo "**** add icon ****" && \ @@ -20,7 +21,13 @@ RUN \ apt-get update && \ apt-get install -y --no-install-recommends \ chromium \ - chromium-l10n && \ + chromium-l10n \ + git \ + nginx && \ + echo "**** clone web content ****" && \ + git clone https://github.com/Sparks72/QMX-Fusion-v1 /var/www/fusion-v1 && \ + chown -R abc:abc /var/www/fusion-v1 && \ + rm -f /etc/nginx/sites-enabled/default && \ echo "**** cleanup ****" && \ apt-get autoclean && \ rm -rf \ diff --git a/jenkins-vars.yml b/jenkins-vars.yml index f100265..45b21db 100644 --- a/jenkins-vars.yml +++ b/jenkins-vars.yml @@ -1,7 +1,7 @@ --- # jenkins variables -project_name: docker-chromium +project_name: docker-qmx-fusion external_type: os release_type: stable release_tag: latest @@ -9,12 +9,12 @@ ls_branch: master build_armhf: false repo_vars: - BUILD_VERSION_ARG = 'CHROMIUM_VERSION' - - LS_USER = 'linuxserver' - - LS_REPO = 'docker-chromium' - - CONTAINER_NAME = 'chromium' - - DOCKERHUB_IMAGE = 'linuxserver/chromium' - - DEV_DOCKERHUB_IMAGE = 'lsiodev/chromium' - - PR_DOCKERHUB_IMAGE = 'lspipepr/chromium' + - LS_USER = 'sa6anw' + - LS_REPO = 'docker-qmx-fusion' + - CONTAINER_NAME = 'qmx-fusion' + - DOCKERHUB_IMAGE = 'sa6anw/qmx-fusion' + - DEV_DOCKERHUB_IMAGE = 'sa6anw/qmx-fusion-dev' + - PR_DOCKERHUB_IMAGE = 'sa6anw/qmx-fusion-pr' - DIST_IMAGE = 'ubuntu' - MULTIARCH = 'true' - CI = 'true' diff --git a/readme-vars.yml b/readme-vars.yml index 405a8de..21d40a4 100644 --- a/readme-vars.yml +++ b/readme-vars.yml @@ -1,12 +1,12 @@ --- # project information -project_name: chromium -project_url: "https://www.chromium.org/chromium-projects/" +project_name: qmx-fusion +project_url: "https://github.com/Sparks72/QMX-Fusion-v1" project_logo: "https://raw.githubusercontent.com/linuxserver/docker-templates/master/linuxserver.io/img/chromium-logo.png" -project_blurb: "[Chromium]({{ project_url }}) is an open-source browser project that aims to build a safer, faster, and more stable way for all users to experience the web." -project_lsio_github_repo_url: "https://github.com/linuxserver/docker-{{ project_name }}" -project_categories: "Web Browser" +project_blurb: "Docker image for [QMX-Fusion]({{ project_url }}), an application for radio enthusiasts." +project_lsio_github_repo_url: "https://git.sa6anw.se/sa6anw/docker-{{ project_name }}" +project_categories: "Radio" project_blurb_optional_extras_enabled: false # supported architectures available_architectures: @@ -32,7 +32,7 @@ custom_params: # optional variables opt_param_usage_include_env: true opt_param_env_vars: - - {env_var: "CHROME_CLI", env_value: "https://www.linuxserver.io/", desc: "Specify one or multiple Chromium CLI flags, this string will be passed to the application in full."} + - {env_var: "CHROME_CLI", env_value: "--kiosk http://localhost", desc: "Specify one or multiple Chromium CLI flags, this string will be passed to the application in full."} # Selkies blurb settings selkies_blurb: true show_nvidia: true @@ -114,6 +114,7 @@ init_diagram: | "chromium:latest" <- Base Images # changelog changelogs: + - {date: "06.01.26:", desc: "Add nginx to serve QMX-Fusion-v1 and start chromium in kiosk mode."} - {date: "20.12.25:", desc: "Add Wayland init logic."} - {date: "22.09.25:", desc: "Rebase to Debian Trixie."} - {date: "01.07.25:", desc: "Add Kasm branch."} diff --git a/root/defaults/menu.xml b/root/defaults/menu.xml index e259a62..5dbe72c 100644 --- a/root/defaults/menu.xml +++ b/root/defaults/menu.xml @@ -2,6 +2,6 @@ /usr/bin/xterm -/usr/bin/wrapped-chromium +/usr/bin/wrapped-chromium diff --git a/root/defaults/menu_wayland.xml b/root/defaults/menu_wayland.xml index 96888f8..bbf0dbc 100644 --- a/root/defaults/menu_wayland.xml +++ b/root/defaults/menu_wayland.xml @@ -2,6 +2,6 @@ /usr/bin/foot -/usr/bin/wrapped-chromium --enable-features=UseOzonePlatform --ozone-platform=wayland +/usr/bin/wrapped-chromium --enable-features=UseOzonePlatform --ozone-platform=wayland diff --git a/root/etc/nginx/conf.d/default.conf b/root/etc/nginx/conf.d/default.conf new file mode 100644 index 0000000..0cff0a8 --- /dev/null +++ b/root/etc/nginx/conf.d/default.conf @@ -0,0 +1,8 @@ +server { + listen 80 default_server; + root /var/www/fusion-v1; + index index.html; + location / { + try_files $uri $uri/ =404; + } +} diff --git a/root/etc/services.d/nginx/run b/root/etc/services.d/nginx/run new file mode 100755 index 0000000..7351fd0 --- /dev/null +++ b/root/etc/services.d/nginx/run @@ -0,0 +1,2 @@ +#!/usr/bin/with-contenv bash +exec nginx -g "daemon off;"