From 8f3c003b491b864e3cb38f1e8e2c528449782b84 Mon Sep 17 00:00:00 2001
From: Jack Spiering <46534141+jackspiering@users.noreply.github.com>
Date: Tue, 13 Oct 2026 23:27:05 +0200
Subject: [PATCH 1/2] Docs: explain how to keep changes out of the clone

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.
---
 README.md | 39 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 39 insertions(+)

diff --git a/README.md b/README.md
index c648808d..f6b5c79f 100644
--- a/README.md
+++ b/README.md
@@ -22,6 +22,7 @@ ScaleTail is a collection of ready-to-run [Docker Compose](https://docs.docker.c
   - [Utilities](#utilities)
   - [Food and wellness](#food-and-wellness)
 - [Update a stack](#update-a-stack)
+- [Keep your changes out of the clone](#keep-your-changes-out-of-the-clone)
 - [Remove a stack](#remove-a-stack)
 - [Get help](#get-help)
 - [Tailscale Serve and Funnel](#tailscale-serve-and-funnel)
@@ -276,6 +277,44 @@ If `git stash pop` reports a conflict in `.env`, open the file, keep your values
 
 Before you restart the stack, read the "Upgrading" section of the service README, if it has one.
 
+## Keep your changes out of the clone
+
+This section is optional. The steps in [Quick Start](#quick-start) work as they are. Use one of these options when you run several stacks, or when `git pull` or switching branches runs into your `.env` or into data that the containers wrote as root.
+
+### Run the stack from a copy
+
+Copy the service directory out of the clone, before the first start, and run the stack from the copy:
+
+```sh
+cp -R ScaleTail/services/<service> ~/stacks/<service>
+cd ~/stacks/<service>
+```
+
+Your `.env`, the Tailscale state, and the application data now live outside the clone, so `git pull` in the clone never conflicts with them. A copy no longer follows the repository, so to pick up changes, update the clone and compare the files:
+
+```sh
+git -C ScaleTail pull
+diff ScaleTail/services/<service>/compose.yaml ~/stacks/<service>/compose.yaml
+```
+
+Read the "Upgrading" section of the service README before you apply a change.
+
+### Keep your changes in an override file
+
+To stay in the clone, put your changes to `compose.yaml` in a file named `compose.override.yaml` (singular) next to it. Compose reads both files without extra options, and `git pull` never touches an untracked file. Entries in `volumes` and `environment` replace the entry with the same container path or variable name, so an override can also move data out of the clone:
+
+```yaml
+services:
+  tailscale:
+    volumes:
+      - /srv/scaletail/<service>/ts/state:/var/lib/tailscale
+  application:
+    volumes:
+      - /srv/scaletail/<service>/data:/config
+```
+
+Use the container path from the `volumes` of the application in `compose.yaml`. Check the result with `docker compose config`. The override file does not cover `.env`, which is tracked, so keep using `git stash` for it, or run the stack from a copy.
+
 ## Remove a stack
 
 From the service directory, run `docker compose down --volumes`. To remove the stack completely, also remove the device on the [Machines](https://console.tailscale.com/admin/machines) page and delete the service directory. It contains the Tailscale state in `./ts/state` and the application data. The containers create some of these folders as root, so deleting them may need `sudo`.

From 415003d829b78ddac8fca90f17290ac2f19a0c90 Mon Sep 17 00:00:00 2001
From: Jack Spiering <46534141+jackspiering@users.noreply.github.com>
Date: Thu, 15 Oct 2026 14:48:28 +0200
Subject: [PATCH 2/2] Docs: compare .env too when running a stack from a copy

---
 README.md | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/README.md b/README.md
index f6b5c79f..c55a5b6c 100644
--- a/README.md
+++ b/README.md
@@ -295,8 +295,11 @@ Your `.env`, the Tailscale state, and the application data now live outside the
 ```sh
 git -C ScaleTail pull
 diff ScaleTail/services/<service>/compose.yaml ~/stacks/<service>/compose.yaml
+diff ScaleTail/services/<service>/.env ~/stacks/<service>/.env
 ```
 
+The `.env` comparison also lists the values you set yourself. Look for variables that are new upstream, such as a new required secret, and add them to your copy.
+
 Read the "Upgrading" section of the service README before you apply a change.
 
 ### Keep your changes in an override file