diff --git a/README.md b/README.md index ece09e6e..6d10c7f9 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) @@ -286,6 +287,47 @@ 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/ ~/stacks/ +cd ~/stacks/ +``` + +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//compose.yaml ~/stacks//compose.yaml +diff ScaleTail/services//.env ~/stacks//.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 + +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//ts/state:/var/lib/tailscale + application: + volumes: + - /srv/scaletail//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`.