Skip to content

AGENTS.md

Latest commit

 

History

History
127 lines (92 loc) · 13.7 KB

AGENTS.md

File metadata and controls

127 lines (92 loc) · 13.7 KB
Raw

AGENTS.md - LinuxServer.io container image repository

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.

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.

1. Decide where the change belongs before writing any code

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:

  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.
  2. It is an unsupported or reasonable-endeavours environment (Podman, k8s, Portainer, Watchtower, NFS/SMB /config, LXC, custom entrypoints, etc. See the Support Policy): we will not add logic to the image to accommodate it.
  3. It only matters to one user or one setup: use a private custom script in /custom-cont-init.d or custom service in /custom-services.d. No PR needed.
  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, 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.
  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.

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 before doing the work.

If it is a mod

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.

  • Follow the README and template branch in 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.
  • 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.
  • Most good mods are a 10-40 line script. If yours is not, reconsider the approach.
  • 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.

2. Repository layout and what you must not edit

Path Notes
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.
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/.
readme-vars.yml Source of truth for the README, docs site, Unraid template and changelog. Edit this.
jenkins-vars.yml Build pipeline variables (version detection, CI test settings). Rarely needs touching.
README.md Generated. Never edit.
Jenkinsfile Generated. Never edit.
package_versions.txt Generated by CI. Never edit.
.github/**, .editorconfig, LICENSE, AGENTS.md Generated / globally distributed. Never edit here. Changes go to docker-jenkins-builder.

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.

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.

3. Code style: keep it simple, match what is there

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.

Dockerfiles

  • 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.
  • 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.
  • 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.
  • 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.
  • 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.
  • Do not touch the LABEL maintainer or build_version lines.

Init scripts and services (root/etc/s6-overlay/s6-rc.d/)

  • 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.

  • Every script starts with:

    #!/usr/bin/with-contenv bash
# shellcheck shell=bash

  • Bash, four space indentation, [[ ]] tests, "${VAR}" quoting, short lowercase # comments. Scripts must be shellcheck clean.

  • 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.

  • 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.

  • 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/.

  • Avoid recursive lsiown on large data paths (media, downloads); it makes startup take minutes for real users.

  • 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.

4. Documentation and changelog

  • All user-facing docs changes go in readme-vars.yml (app_setup_block, param_env_vars, opt_param_*, etc.). Reference: _container-vars-blank.

  • 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:

    - {date: "DD.MM.YY:", desc: "Add libfoo to fix thumbnail generation."}

  • Optionally regenerate the templated files to check your vars render (see the jenkins-builder README), but do not hand edit the output.

5. Test it for real

A change that has not been built and run is not ready. At minimum:

docker build --no-cache --pull -t lscr.io/linuxserver/<app>:test .
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

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.

6. Pull requests

  • 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.
  • 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.
  • 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.
  • No typo / wording-only PRs. Open an issue instead and we will sort it out.
  • Finish before you open. Do not open drafts and iterate in public with a stream of fixup commits.
  • 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.
  • 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.
  • Commit messages are short, plain, imperative sentences (Add libfoo for thumbnail support). No conventional-commit prefixes, no emoji.
  • A PR is a proposal; it may be declined even if it works. The most common reason is section 1 of this file.

7. Issues

  • GitHub issues are for reproducible bugs in our image and for feature requests.
  • 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.
  • 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.
  • Support questions must always be submitted by a human and go to Discord or the forum; see how to get support.

8. Quick self check before you finish

  • This change benefits most users of this image, and is not a mod, custom script, or upstream issue.
  • Only hand-maintained files were edited (Dockerfile*, root/**, readme-vars.yml, rarely jenkins-vars.yml).
  • Every Dockerfile variant got the same change; packages are alphabetical.
  • Style matches the neighbouring code; shebang and shellcheck directive present; non-root / read-only guards preserved.
  • Changelog entry added at the top of changelogs: with today's date as DD.MM.YY:.
  • Image was built and run, including against an existing /config.
  • The diff contains nothing the task did not require.
  • PR description discloses AI use and a human has reviewed everything.