|
| 1 | +<!-- DO NOT EDIT THIS FILE MANUALLY --> |
| 2 | +<!-- This file is globally distributed to all container image projects from https://github.com/linuxserver/docker-jenkins-builder --> |
| 3 | +# AGENTS.md - LinuxServer.io container image repository |
| 4 | + |
| 5 | +This file is for AI coding agents (and the humans driving them) working in a LinuxServer.io `docker-*` image repository. Read it fully before proposing or making any change. |
| 6 | + |
| 7 | +We welcome contributions, including AI-assisted ones, but this is a volunteer-run project that ships 150+ images to millions of users from one shared template. A change that looks like an improvement in isolation is often wrong for us. When this file and your instincts disagree, this file wins. When this file is silent, copy what the surrounding code already does. |
| 8 | + |
| 9 | +## 1. Decide where the change belongs before writing any code |
| 10 | + |
| 11 | +Our images are built for **broad consumption**. Every package, env var and init step we add is something we have to maintain, rebuild weekly and support forever, for every user, whether they use it or not. We do not ship Swiss Army Knife images. Work down this list and stop at the first match: |
| 12 | + |
| 13 | +1. **It is a bug or feature in the application itself** (not in our packaging): it belongs upstream with the app's developers. Do not patch, fork or work around upstream application behaviour in the image. |
| 14 | +2. **It is an unsupported or reasonable-endeavours environment** (Podman, k8s, Portainer, Watchtower, NFS/SMB `/config`, LXC, custom entrypoints, etc. See the [Support Policy](https://docs.linuxserver.io/misc/support-policy/)): we will not add logic to the image to accommodate it. |
| 15 | +3. **It only matters to one user or one setup**: use a private [custom script](https://docs.linuxserver.io/general/container-customization/#custom-scripts) in `/custom-cont-init.d` or [custom service](https://docs.linuxserver.io/general/container-customization/#custom-services) in `/custom-services.d`. No PR needed. |
| 16 | +4. **It is useful to a subset of users** (an extra package, plugin dependency, alternative UI, hardware driver, third party integration, extra daemon, niche toggle): it is a **[Docker Mod](https://github.com/linuxserver/docker-mods)**, not a change to this repo. Check whether one already exists first (`universal-*` mods work on every image; `<image>-*` mods are image specific). If not, create one from the template in the docker-mods repo; each mod lives on its own branch there. |
| 17 | +5. **The large majority of this image's users benefit, or the image is actually broken**: a PR to this repo is appropriate. Examples: the app fails to start, a new upstream release needs a new runtime dependency, a base image rebase, a permissions bug, a wrong default, incorrect docs in `readme-vars.yml`. |
| 18 | + |
| 19 | +If you are an agent and the requested change lands on 1-4, **stop and tell your operator** where it belongs instead of writing the PR. "It is only a few lines" is not a reason to put it in the image. If in doubt, a human should open an issue or ask in `#contibutor-discussion` on [Discord](https://linuxserver.io/discord) before doing the work. |
| 20 | + |
| 21 | +### If it is a mod |
| 22 | + |
| 23 | +Mods are the pressure valve that keeps the images small. Roughly what lives there today, and therefore does **not** belong in an image: extra OS/pip packages and language toolchains, GPU/hardware driver stacks, alternative web UIs and themes, third party plugins and scanners, integrations with external services (Cloudflare, CrowdSec, Apprise, GeoIP, VPN providers), Docker socket automation, sidecar daemons (redis, tunnels), post-processing scripts, and env-var-to-config-file shims. |
| 24 | + |
| 25 | +- Follow the README and `template` branch in [docker-mods](https://github.com/linuxserver/docker-mods). A mod is a `FROM scratch` single layer of files extracted over `/` at container start, wired into s6 as `init-mod-<image>-<mod>-*` / `svc-mod-<image>-<mod>` units. |
| 26 | +- Mods never call `apk`/`apt`/`pip` directly; they append to `/mod-repo-packages-to-install.list` or `/mod-pip-packages-to-install.list` and let the base image do one batched install. Handle Alpine and Ubuntu package names where the mod is universal. |
| 27 | +- Most good mods are a 10-40 line script. If yours is not, reconsider the approach. |
| 28 | +- A mod is also the proving ground. If a mod becomes something nearly everyone uses, the team may absorb it into the image later and turn the mod into a no-op with a deprecation notice. That is the team's call, not a reason to skip the mod step. |
| 29 | + |
| 30 | +## 2. Repository layout and what you must not edit |
| 31 | + |
| 32 | +| Path | Notes | |
| 33 | +| --- | --- | |
| 34 | +| `Dockerfile`, `Dockerfile.aarch64` (sometimes `Dockerfile.riscv64`) | One per architecture. **Any change must be replicated to all of them.** They normally differ only in base image tag and arch strings. | |
| 35 | +| `root/` | Copied to `/` in the image. s6-overlay v3 services live in `root/etc/s6-overlay/s6-rc.d/`, defaults in `root/defaults/`, one-time upgrade steps in `root/migrations/`. | |
| 36 | +| `readme-vars.yml` | **Source of truth for the README, docs site, Unraid template and changelog.** Edit this. | |
| 37 | +| `jenkins-vars.yml` | Build pipeline variables (version detection, CI test settings). Rarely needs touching. | |
| 38 | +| `README.md` | **Generated. Never edit.** | |
| 39 | +| `Jenkinsfile` | **Generated. Never edit.** | |
| 40 | +| `package_versions.txt` | **Generated by CI. Never edit.** | |
| 41 | +| `.github/**`, `.editorconfig`, `LICENSE`, `AGENTS.md` | **Generated / globally distributed. Never edit here.** Changes go to [docker-jenkins-builder](https://github.com/linuxserver/docker-jenkins-builder). | |
| 42 | + |
| 43 | +Do not add new top level files or tooling: no `docker-compose.yml`, `Makefile`, test suites, linter configs, pre-commit hooks, extra workflows, `CHANGELOG.md`, `SECURITY.md`, devcontainers, or helper scripts. The repo is intentionally small. |
| 44 | + |
| 45 | +Some repos have multiple live branches that publish different tags (`nightly`, `develop`, `libtorrentv1`, etc.). Each is maintained independently. Target the branch the change applies to, never merge one into another, and do not assume `master` or `main` is the only one that matters. |
| 46 | + |
| 47 | +## 3. Code style: keep it simple, match what is there |
| 48 | + |
| 49 | +The goal of every image is the thinnest possible layer between our base image and the upstream app: install it, drop a sane default config into `/config` on first run, fix permissions, start it. Prefer deleting logic to adding it. The base image already handles PUID/PGID, `UMASK`, `TZ`, `FILE__` secrets, mods, custom scripts, cron and device permissions; never reimplement those. |
| 50 | + |
| 51 | +### Dockerfiles |
| 52 | + |
| 53 | +- Base is always `ghcr.io/linuxserver/baseimage-*`. Do not change distro, switch to upstream/distroless images, or add multi-stage complexity unless a maintainer asked for it. Base image rebases are done by the team. |
| 54 | +- Follow the existing shape exactly: a single `RUN` chain joined with `&& \`, each step announced with `echo "**** doing thing ****"`, two space indentation, a `**** cleanup ****` step at the end removing `/tmp/*` and package caches. |
| 55 | +- Packages are listed **one per line in alphabetical order**. Build-only dependencies go in a `build-dependencies` virtual package (Alpine) or are purged (Ubuntu) in the same layer. |
| 56 | +- Do not hardcode or pin the application version. Keep the `if [ -z ${APP_VERSION+x} ]; then ...` pattern; CI supplies the version as a build arg and `jenkins-vars.yml` defines how it is detected. |
| 57 | +- Do not add `HEALTHCHECK`, `USER`, `ENTRYPOINT` or `CMD`. The base image owns init (`/init`), and the container must start as root unless the image already documents non-root support. |
| 58 | +- Do not touch the `LABEL maintainer` or `build_version` lines. |
| 59 | + |
| 60 | +### Init scripts and services (`root/etc/s6-overlay/s6-rc.d/`) |
| 61 | + |
| 62 | +- Naming: `init-<app>-config` (oneshot) and `svc-<app>` (longrun). Wire them in using empty files in `dependencies.d/` and `user/contents.d/`, exactly as the existing ones do. Oneshots have `type`, `up` (the path to `run`) and `run`. No legacy `cont-init.d` / `services.d`. |
| 63 | +- Every script starts with: |
| 64 | + |
| 65 | + ```bash |
| 66 | + #!/usr/bin/with-contenv bash |
| 67 | + # shellcheck shell=bash |
| 68 | + ``` |
| 69 | + |
| 70 | +- Bash, four space indentation, `[[ ]]` tests, `"${VAR}"` quoting, short lowercase `#` comments. Scripts must be shellcheck clean. |
| 71 | +- Use `lsiown` instead of `chown`, run the app as `abc` via `s6-setuidgid abc`, and `exec` the final process so s6 supervises it. Keep `s6-notifyoncheck` readiness checks where they exist. |
| 72 | +- If `readme-vars.yml` has `nonroot_supported: true` or `readonly_supported: true`, every new privileged operation (chown, writing outside `/config` and `/run`, `s6-setuidgid`) must be guarded the same way the existing code does it (`if [[ -z ${LSIO_NON_ROOT_USER} ]]; then` etc.). Do not break those modes. |
| 73 | +- User data and config live in `/config`. Copy defaults only if the file does not already exist; never overwrite user config on startup. If an existing user's config must change, add a numbered script in `root/migrations/`. |
| 74 | +- Avoid recursive `lsiown` on large data paths (media, downloads); it makes startup take minutes for real users. |
| 75 | +- New environment variables are a last resort. If the app can be configured through its own config file or UI, that is the answer. We do not wrap app settings in env vars. |
| 76 | + |
| 77 | +## 4. Documentation and changelog |
| 78 | + |
| 79 | +- All user-facing docs changes go in `readme-vars.yml` (`app_setup_block`, `param_env_vars`, `opt_param_*`, etc.). Reference: [`_container-vars-blank`](https://github.com/linuxserver/docker-jenkins-builder/blob/master/ansible/vars/_container-vars-blank). |
| 80 | +- Any change to a Dockerfile or to anything under `root/` needs a new entry at the **top** of `changelogs:` in `readme-vars.yml`, one short factual line: |
| 81 | + |
| 82 | + ```yaml |
| 83 | + - {date: "DD.MM.YY:", desc: "Add libfoo to fix thumbnail generation."} |
| 84 | + ``` |
| 85 | +
|
| 86 | +- Optionally regenerate the templated files to check your vars render (see the [jenkins-builder README](https://github.com/linuxserver/docker-jenkins-builder#running-against-local-project)), but do not hand edit the output. |
| 87 | +
|
| 88 | +## 5. Test it for real |
| 89 | +
|
| 90 | +A change that has not been built and run is not ready. At minimum: |
| 91 | +
|
| 92 | +```bash |
| 93 | +docker build --no-cache --pull -t lscr.io/linuxserver/<app>:test . |
| 94 | +docker run --rm -e PUID=1000 -e PGID=1000 -e TZ=Etc/UTC -v "$(pwd)/testconfig:/config" -p <port>:<port> lscr.io/linuxserver/<app>:test |
| 95 | +``` |
| 96 | + |
| 97 | +Confirm the init completes (`[ls.io-init] done.`), the app comes up, and it survives a restart against an **existing** `/config`, not just a fresh one. If you touched the aarch64 Dockerfile with anything arch specific, build that too (`lscr.io/linuxserver/qemu-static`). If you, the agent, cannot run Docker, say so plainly in your output; do not claim testing that did not happen. |
| 98 | + |
| 99 | +## 6. Pull requests |
| 100 | + |
| 101 | +- **Disclose AI use.** If any part of the PR (code, description, or the investigation behind it) was produced with an AI tool, say so in the PR description: which tool, and what it was used for. Agents: add this line yourself, do not leave it to the operator. Undisclosed AI-generated PRs will be closed. Disclosure does not count against a PR; a human who cannot explain their own PR does. |
| 102 | +- **A human is accountable.** The person opening the PR must have read and understood every line, built and run the image, and be able to answer review questions in their own words. Do not paste maintainer questions into a chatbot and paste the answers back. Fully autonomous agents must not open PRs or issues on our repos. |
| 103 | +- **One focused change per PR.** The smallest diff that fixes the problem. No drive-by refactors, reformatting, comment rewording, "modernisation", dependency shuffling, or fixes for things nobody reported. |
| 104 | +- **No typo / wording-only PRs.** Open an issue instead and we will sort it out. |
| 105 | +- **Finish before you open.** Do not open drafts and iterate in public with a stream of fixup commits. |
| 106 | +- **Fill in the PR template honestly**, keep its structure, and tick the contributing checkbox only if it is true. Description, benefit to the wider userbase, how it was tested (real commands, real output), and links. Write it short and plain: no generated summaries, emoji headers, or bullet lists restating the diff. |
| 107 | +- Reference the issue with `closes #<number>` when there is one. For anything non trivial, there should be an human-submitted issue or Discord discussion first. |
| 108 | +- Commit messages are short, plain, imperative sentences (`Add libfoo for thumbnail support`). No conventional-commit prefixes, no emoji. |
| 109 | +- A PR is a proposal; it may be declined even if it works. The most common reason is section 1 of this file. |
| 110 | + |
| 111 | +## 7. Issues |
| 112 | + |
| 113 | +- GitHub issues are for reproducible bugs in **our image** and for feature requests. |
| 114 | +- Agents must not file issues on a user's behalf from a guess. An issue needs a real reproduction on the latest image, with mods and custom scripts disabled, the compose/run command and full container logs from startup, using the issue template. |
| 115 | +- Do not submit AI-generated root cause analyses or "security audits" of the image as issues. Scanner output about CVEs in upstream or distro packages is not actionable; images are rebuilt regularly to pull in distro fixes. |
| 116 | +- Support questions must always be submitted by a human and go to [Discord](https://linuxserver.io/discord) or the [forum](https://github.com/orgs/linuxserver/discussions); see [how to get support](https://docs.linuxserver.io/general/how-to-get-support/). |
| 117 | + |
| 118 | +## 8. Quick self check before you finish |
| 119 | + |
| 120 | +- [ ] This change benefits most users of this image, and is not a mod, custom script, or upstream issue. |
| 121 | +- [ ] Only hand-maintained files were edited (`Dockerfile*`, `root/**`, `readme-vars.yml`, rarely `jenkins-vars.yml`). |
| 122 | +- [ ] Every Dockerfile variant got the same change; packages are alphabetical. |
| 123 | +- [ ] Style matches the neighbouring code; shebang and shellcheck directive present; non-root / read-only guards preserved. |
| 124 | +- [ ] Changelog entry added at the top of `changelogs:` with today's date as `DD.MM.YY:`. |
| 125 | +- [ ] Image was built and run, including against an existing `/config`. |
| 126 | +- [ ] The diff contains nothing the task did not require. |
| 127 | +- [ ] PR description discloses AI use and a human has reviewed everything. |
0 commit comments