Skip to content

All services: standardize the service READMEs - #363

Merged
crypt0rr merged 4 commits into
mainfrom
t3code/standardize-service-readmes
Oct 8, 2026
Merged

crypt0rr merged 4 commits into
mainfrom
t3code/standardize-service-readmes

Conversation

@jackspiering

@jackspiering jackspiering commented Oct 7, 2026 •

Copy link
Copy Markdown
Collaborator

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:

Section Content
Introduction What the service does, in one or two sentences, with a link to upstream
At a glance Tailnet address, service port, image, and data paths
Before you start Only what the Quick Start does not cover
Deviations from the standard setup Every difference from the template, with the reason
First run What the user does after the first start
Configuration, Troubleshooting, Upgrading Optional, only when the service needs them
Links Upstream documentation and source code

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 root README.md links to it after the Quick Start.
  • documentation/free-up-port-53.md (new): the DNSStubListener guide, 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 of CONTRIBUTING.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

  • None.

Verification

  • Deviations. Each compose.yaml was compared with the template, so every "Deviations" section lists actual differences.
  • First run. 116 stacks were started locally with a stand-in for the Tailscale container, to see what the application does at its first start: the port it listens on, redirects to a setup page, generated passwords in the log, and the owner of created folders. Where that was not enough, the upstream documentation was used.
  • Tailscale Serve. Radarr, Pi-hole, Copyparty, and Node-RED were also tested through Tailscale Serve on the Tailnet. For the other stacks, the "Service port" is the port that the application was seen to listen on.
  • rumdl check --config .markdownlint.yml on all 127 changed Markdown files: passed.
  • git diff --check: passed.
  • All external links in the changed files were requested. All resolve, except three that block automated requests (docs.paperless-ngx.com, plex.tv/claim, and the pre-existing stargazers badge link in the root README.md).
  • docker compose config --quiet: this pull request changes no Compose file.

Not verified:

  • Immich, Sure, and Traefik were not started. Their READMEs are the existing text in the new structure.
  • The exit node, subnet router, and app connector READMEs follow their Compose files and the Tailscale documentation.
  • Hytale and Minecraft started, but no game client connected.
  • The default logins of ClipCascade and Speedtest Tracker come from the upstream documentation.

Checklist

  • I have performed a self-review of my code and followed the templates structure.
  • I have added verification that the stack works as expected.
  • I have updated necessary documentation (e.g. frontpage README.md ).
  • I have selected the correct label(s) for this PR.

Additional Context

  • Pi-hole, Copyparty, Node-RED: fix web interface access through Tailscale Serve #362 is merged. The READMEs of Pi-hole, Copyparty, and Node-RED describe the behaviour after that fix.
  • Kaneo. main gained 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 merges main, and the Kaneo README is rewritten for the new stack and checked against a running copy: Kaneo does not start with the sample KANEO_CLIENT_URL, listens on port 5173, and has registration enabled.
  • Overlap with Add service contract enforcement workflow #330. That draft also changes templates/service-template/README.md and CONTRIBUTING.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.
  • Good places to start the review: documentation/standard-setup.md, the template README, step 6 of CONTRIBUTING.md, and then Immich, Sure, Pocket ID, FreshRSS, Mailpit, Traefik, and Seafile, where existing notes were sorted into the new sections.
  • Problems that the checks found. The READMEs describe the current behaviour and warn where data is at risk. None of these is changed here:
    • Technitium and FossFLOW store their data in a path that the stack does not mount, so the data is lost when the container is recreated. Technitium: store settings and zones on the host #364 and FossFLOW: store diagrams on the host #365 fix this and are stacked on this pull request.
    • Nessus has no volumes, and Tenable does not support storage volumes for its image. The README says so.
    • Ollama: OLLAMA_API_KEY does not restrict access. The API answered without a key while the variable was set. The README no longer claims it.
    • Stirling-PDF: DOCKER_ENABLE_SECURITY=false no longer disables the login. The image creates admin / stirling.
    • Arcane, ConvertX, Formbricks, Hemmelig, and Karakeep ship public sample secrets that the user must replace.
    • In Coder, Docmost, Kaneo, Miniflux, and Tandoor the database shares the network of the Tailscale container, so it listens on the Tailscale IP address of the device.
    • AFFiNE, Immich, Kaneo, Karakeep, KitchenOwl, LubeLogger, NetBox, Pocket ID, and Tandoor load the whole .env through env_file, which includes TS_AUTHKEY.
    • Pingvin Share and Hemmelig are archived upstream, and the original FossFLOW repository is gone.
    • ArtistTrackarr sets PGI where it means PGID, and LubeLogger has a build: . line without a Dockerfile.

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.
@crypt0rr
crypt0rr merged commit de1e9f8 into main Oct 8, 2026
1 check passed
@crypt0rr
crypt0rr deleted the t3code/standardize-service-readmes branch October 8, 2026 15:23
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants