Retry deploy.sh registry pull; document the registry /etc/hosts gotcha (#31)

deploy/deploy.sh

@@ -70,7 +70,26 @@ echo "==> Logging in to the registry ($REGISTRY_HOST)"
 echo "$REGISTRY_TOKEN" | docker login "$REGISTRY_HOST" --username emi --password-stdin
 
 echo "==> Pulling images ($IMAGE_TAG)"
-docker compose pull backend frontend
+# Retry: build-push.yml (triggered by the same push) has no ordering
+# guarantee against this deploy -- Forgejo/GitHub Actions `needs:` only
+# works between jobs in ONE workflow file, not across two workflows
+# triggered by the same event. Confirmed live: a real deploy raced ahead of
+# the push and failed with "not found". A bounded retry (~5 min) comfortably
+# covers a normal build; a genuine problem (bad tag, registry down) still
+# fails loudly after that, just a bit slower to surface.
+pull_ok=0
+for i in $(seq 1 30); do
+  if docker compose pull backend frontend; then
+    pull_ok=1
+    break
+  fi
+  echo "   pull attempt $i/30 failed (image may not be pushed yet); retrying in 10s..." >&2
+  sleep 10
+done
+if [ "$pull_ok" != 1 ]; then
+  echo "!! docker compose pull failed after 30 attempts" >&2
+  exit 1
+fi
 
 # Schema migrations run inside the backend container's entrypoint (alembic
 # upgrade head) before uvicorn starts, so there's no separate migrate step or