README.md

@@ -172,7 +172,17 @@ It differs from production deliberately: `DEMO_MODE=true` with no PayPal credent
 
 ### One-time setup on the NAS
 
-Create the directory structure. These paths are deliberately **not** under `/volume1/configs/redefined-designs` — sharing production's Postgres directory would mean QA writing into production's database files.
+**Build the image before creating the stack.** `redefined-designs:qa` exists only on the NAS — it is never pushed to a registry. If the stack is deployed first, Compose finds no local image, falls back to pulling from Docker Hub, and fails with a misleading `pull access denied ... repository does not exist or may require 'docker login'`.
+
+```bash
+cd /volume1/docker/redefined-designs
+sudo docker build --no-cache -t redefined-designs:qa /volume1/docker/redefined-designs
+sudo docker images | grep redefined-designs   # confirm the qa tag is present
+```
+
+For the same reason, leave Portainer's **"Pull latest image"** toggle **off** when deploying or redeploying this stack. The compose file sets `pull_policy: never` so a missing image reports itself as missing rather than as a registry authentication problem.
+
+Next, create the directory structure. These paths are deliberately **not** under `/volume1/configs/redefined-designs` — sharing production's Postgres directory would mean QA writing into production's database files.
 
 ```bash
 sudo mkdir -p /volume1/configs/redefined-designs-qa/postgres
@@ -204,6 +214,8 @@ gitc() { sudo docker run --rm -it -v /volume1/docker/redefined-designs:/repo -v
 gitc pull origin main
 gitc log --oneline -3
 
+# Rebuild the QA image before restarting the stack — the stack does not build
+# anything itself, and will otherwise run whatever was last tagged :qa.
 sudo docker build --no-cache -t redefined-designs:qa /volume1/docker/redefined-designs
 # start the redefined-designs-qa stack in Portainer
 

docker-compose.qa.yml

@@ -17,12 +17,23 @@
 #   QA_DB_PASSWORD  — deliberately not named DB_PASSWORD, so pasting the
 #                     production stack's variables here does nothing silently.
 #
-# Build the image on the NAS before starting the stack:
+# BUILD THE IMAGE BEFORE DEPLOYING THIS STACK. redefined-designs:qa exists only
+# on the NAS and is never pushed to a registry, so deploying first makes Compose
+# fall back to pulling from Docker Hub and fail with a misleading
+# "pull access denied ... repository does not exist or may require docker login".
+#
 #   sudo docker build --no-cache -t redefined-designs:qa /volume1/docker/redefined-designs
+#
+# For the same reason, leave Portainer's "Pull latest image" toggle off.
+# `pull_policy: never` below makes a missing image report itself as missing
+# rather than as a registry authentication problem. If the Docker Compose
+# version on the NAS ever rejects that key, it is safe to delete the line — it
+# only improves the error message.
 
 services:
   redefined-designs-qa:
     image: redefined-designs:qa
+    pull_policy: never
     container_name: redefined-designs-qa-syn
     environment:
       - TZ=America/Chicago