103 lines
4.4 KiB
Markdown
103 lines
4.4 KiB
Markdown
# 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.
|