From 6d310686d9daf3351343ebb2263e6da0cb2c6092 Mon Sep 17 00:00:00 2001
From: Edwin <18327273+thinkbig1979@users.noreply.github.com>
Date: Fri, 31 Jul 2026 21:01:21 +0200
Subject: [PATCH] docs(dr): make the runbook's rclone step work as written
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Step 2 of the disaster-recovery runbook failed for anyone following it
verbatim. The capstan-tools alias mounts rclone.conf at the appuser path, but
--entrypoint sh skips the entrypoint that drops privileges, so the throwaway
container runs as root with HOME=/root and rclone never opened the file:

    NOTICE: Config file "/root/.config/rclone/rclone.conf" not found - using defaults
    CRITICAL: Failed to create file system for "offsite:/offsite/capstan-repo":
              didn't find section in config file ("offsite")

The message points at the remote, not at the config, so it sends you
debugging the wrong thing during an outage — and step 2 is the one that
retrieves the only copy of the repository that survived losing the volume.

Setting RCLONE_CONFIG explicitly fixes it regardless of which user runs, and
the reason is documented next to it so nobody "tidies" the variable away.
Also notes that a local-filesystem remote needs its own bind mount, since the
path is resolved inside the container.

Observed while re-running the destroy-and-recover drill for agent-os-36o.

agent-os-36o
---
 README.md | 16 ++++++++++++++++
 1 file changed, 16 insertions(+)

diff --git a/README.md b/README.md
index 439d605..28f9faa 100644
--- a/README.md
+++ b/README.md
@@ -232,9 +232,22 @@ Define this once, adjusting the paths to your deployment:
 alias capstan-tools='docker run --rm \
   -v ./data:/app/data \
   -v ~/.config/rclone/rclone.conf:/home/appuser/.config/rclone/rclone.conf:ro \
+  -e RCLONE_CONFIG=/home/appuser/.config/rclone/rclone.conf \
   --entrypoint sh ghcr.io/thinkbig1979/capstan:latest -c'
 ```
 
+`RCLONE_CONFIG` is not optional. `--entrypoint sh` skips the entrypoint that
+would drop to `appuser`, so these commands run as **root** with `HOME=/root`,
+and rclone looks for its config under `$HOME`. Without the variable it never
+reads the file you just mounted and step 2 fails with:
+
+```
+NOTICE: Config file "/root/.config/rclone/rclone.conf" not found - using defaults
+CRITICAL: Failed to create file system for "<remote>:<path>": didn't find section in config file
+```
+
+which reads like a broken remote rather than a config it never opened.
+
 #### 2. Get the repository back from the remote
 
 ```bash
@@ -245,6 +258,9 @@ capstan-tools 'rclone sync <remote>:<path> /app/data/restic-repo --stats-one-lin
 what the UI's DR Restore does; doing it by hand keeps step 1's "container
 stopped" rule intact.
 
+If the remote is a local-filesystem one, add its bind mount to the alias too —
+the path is resolved inside the container.
+
 #### 3. Find the database snapshot
 
 ```bash