Skip to content

Docs: keep changes out of the clone - #389

Draft
jackspiering wants to merge 2 commits into
mainfrom
docs/keep-changes-out-of-clone
Draft

jackspiering wants to merge 2 commits into
mainfrom
docs/keep-changes-out-of-clone

Conversation

@jackspiering

@jackspiering jackspiering commented Oct 13, 2026 •

Copy link
Copy Markdown
Collaborator

Description

Adds an optional README section, "Keep your changes out of the clone", placed after "Update a stack". It describes two ways to stop local changes from colliding with git pull:

  • Run the stack from a copy of its service directory, so .env, the Tailscale state, and the application data live outside the clone. It also says how to compare the copy's compose.yaml and .env with upstream after a git pull, so that new variables are not missed.
  • Put changes in compose.override.yaml (singular, the name Compose loads automatically). Entries in volumes replace the entry with the same container path, so an override can also move data out of the clone. It does not cover .env.

The Quick Start is unchanged, and no compose.yaml or default data path changes. This is a reduced version of the proposal in #317, which also asks to move every default data path outside the repository. I left that out because it would need an "Upgrading" section for every stack.

Draft, to discuss the scope before review.

Related Issues

Verification

  • docker compose config --quiet from each changed service directory: not applicable, no service changed
  • The stack started, Tailscale is healthy, and the service is reachable through the Tailnet: not applicable, documentation only
  • The main function of the service works, and its data survives a restart: not applicable, documentation only
  • rumdl check --config .markdownlint.yml . on the whole repository (0.2.78, the version CI pins), and git diff --check origin/main
  • The override behaviour: in a copy of the template with a compose.override.yaml that mounts other host paths on /config and /var/lib/tailscale, docker compose config (Compose v5.6.0) showed the new bind sources and no old mount on those paths.

Impact on existing users

  • None.

Checklist

  • I have performed a self-review of my code and followed the templates structure.
  • I did not commit a working auth key, password, token, or other credential.
  • The service README uses the headings of the template, in the same order, and is up to date. Not applicable.
  • This PR does not change the list of services.

Additional Context

Open question for the maintainers: whether this belongs in the README at all, or only in documentation/standard-setup.md, given that it adds a second workflow next to the Quick Start.

Add an optional README section for running a stack from a copy of its service directory, or from a compose.override.yaml, so git pull no longer collides with local changes. Refs #317.
@jackspiering jackspiering added the documentation Improvements or additions to documentation label Oct 13, 2026
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.

1 participant