From 2839feef9e33baba668b1d327263e8a7673005db Mon Sep 17 00:00:00 2001
From: Rob Wiederstein <khuon68@gmail.com>
Date: Mon, 9 Mar 2026 11:42:09 -0400
Subject: [PATCH] Document deployment problems and fix volume mounts

---
 README.md          | 30 ++++++++++++++++++++++++++++++
 docker-compose.yml |  5 ++---
 2 files changed, 32 insertions(+), 3 deletions(-)

diff --git a/README.md b/README.md
index 28006e2..e131cb1 100644
--- a/README.md
+++ b/README.md
@@ -33,6 +33,36 @@ and saved as `data-raw/addresses/owners_moved.gpkg`. This file is the stable geo
 source. Account numbers follow the property, so only ownership attributes need
 refreshing weekly.
 
+## Deployment problems and solutions
+
+**1. Workflow YAML syntax error**
+The SSH heredoc (`<< 'EOF'`) inside a YAML `run:` block conflicted with YAML parsing — red triangle in Gitea, no logs.
+→ Replaced with a quoted multiline SSH string.
+
+**2. Runner not picking up jobs**
+The workflow used `container: debian:bookworm-slim` just to get SSH, forcing the runner to pull a Docker image on every run.
+→ Removed the container block, reverted to `runs-on: ubuntu-latest` using the cached runner image.
+
+**3. Runner was repo-scoped, not user-scoped**
+The act_runner was registered specifically for another repo. stAndrews showed zero runners and jobs stayed queued forever.
+→ Re-registered the runner at the user level via Gitea User Settings → Actions → Runners.
+
+**4. Two runner instances competing**
+A manual `pkill` + manual restart created a second runner process alongside the systemd service, both sharing the same UUID.
+→ Killed the duplicate, leaving only the systemd-managed instance.
+
+**5. Gateway Caddyfile `import` silently failing**
+The `import /data/projects/r/*/Caddyfile.snippet` directive was never evaluated — the gateway container only mounts the Caddyfile itself, not the project directories.
+→ Added the stAndrews route directly to the gateway Caddyfile.
+
+**6. renv activating inside the container**
+The volume mount `.:/srv/shiny-server` put `.Rprofile` into the container, triggering renv to try installing its own library and conflicting with packages already installed in the image.
+→ Switched to selective mounts (`./data` and `./www` only). App code is baked into the image; only runtime data is volume-mounted.
+
+**7. `owners.rds` deleted from disk**
+`git rm --cached data/owners.rds` removed it from git tracking but also wiped the file from the filesystem.
+→ Ran `update_owners.R` inside the rstudio container to rebuild it from the SCPA source.
+
 ## Note: building footprints not used
 
 Sarasota County publishes a building footprint GIS layer that could derive accurate
diff --git a/docker-compose.yml b/docker-compose.yml
index de89d15..3b3e471 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -8,9 +8,8 @@ services:
     environment:
       - SHINY_LOG_STDERR=1
     volumes:
-      - .:/srv/shiny-server
-      # Prevents local renv library from shadowing the container's library
-      - /srv/shiny-server/renv/library
+      - ./data:/srv/shiny-server/data
+      - ./www:/srv/shiny-server/www
     healthcheck:
       test: ["CMD", "curl", "-f", "http://localhost:3838/"]
       interval: 1m