Repository navigation
All services: standardize the service READMEs - #363
Merged
Merged
Conversation
Give every service README the same headings in the same order: At a glance, Before you start, Deviations from the standard setup, First run, and Links, with Configuration, Troubleshooting, and Upgrading as optional sections. - Describe the shared sidecar setup once in documentation/standard-setup.md, so that a service README only lists what differs. - Move the port 53 guide to documentation/free-up-port-53.md. - Reduce the template README to the headings and placeholders, and move the instructions for contributors to CONTRIBUTING.md. - Rewrite all 122 service READMEs. Remove feature lists and the repeated sidecar explanation, and keep the service-specific notes.
This was referenced Oct 7, 2026
This was referenced Oct 7, 2026
crypt0rr
approved these changes
Oct 8, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
The service READMEs had grown apart. All 122 had a "Configuration Overview" paragraph that repeated the sidecar explanation, 62 had a feature list copied from upstream, and about 40 headings existed in one README only. The notes that matter to a user, such as required secrets or a changed network layout, had no fixed place.
This pull request gives every service README the same headings in the same order:
A section with nothing to report keeps its heading and says "None", so a reader can tell that the service follows the standard setup.
Changes:
documentation/standard-setup.md(new): describes the shared sidecar setup once, so that a service README only lists what differs. The rootREADME.mdlinks to it after the Quick Start.documentation/free-up-port-53.md(new): theDNSStubListenerguide, which Pi-hole and AdGuard Home each carried a copy of.templates/service-template/README.md: only the headings and placeholders. The instructions for contributors moved to step 6 ofCONTRIBUTING.md.services/*/README.md: all 122 rewritten. Feature lists and the repeated sidecar paragraph are gone. Service-specific notes are kept and sorted into the new sections.Related Issues
Verification
compose.yamlwas compared with the template, so every "Deviations" section lists actual differences.rumdl check --config .markdownlint.ymlon all 127 changed Markdown files: passed.git diff --check: passed.docs.paperless-ngx.com,plex.tv/claim, and the pre-existing stargazers badge link in the rootREADME.md).docker compose config --quiet: this pull request changes no Compose file.Not verified:
Checklist
Additional Context
maingained Kaneo - use a single application service instead of two (replicate Kaneo configuration) #343 after this branch started, which turned Kaneo into a single application container. The branch mergesmain, and the Kaneo README is rewritten for the new stack and checked against a running copy: Kaneo does not start with the sampleKANEO_CLIENT_URL, listens on port5173, and has registration enabled.templates/service-template/README.mdandCONTRIBUTING.md, and its validator tests use the old README layout, so the two will conflict. A rule that checks the README headings and their order would fit that validator better than a separate workflow, so this pull request adds no CI check.documentation/standard-setup.md, the template README, step 6 ofCONTRIBUTING.md, and then Immich, Sure, Pocket ID, FreshRSS, Mailpit, Traefik, and Seafile, where existing notes were sorted into the new sections.OLLAMA_API_KEYdoes not restrict access. The API answered without a key while the variable was set. The README no longer claims it.DOCKER_ENABLE_SECURITY=falseno longer disables the login. The image createsadmin/stirling..envthroughenv_file, which includesTS_AUTHKEY.PGIwhere it meansPGID, and LubeLogger has abuild: .line without a Dockerfile.