diff --git a/deployment/docker-compose-azure.yaml b/deployment/docker-compose-azure.yaml
index 99cd0988..97873a35 100644
--- a/deployment/docker-compose-azure.yaml
+++ b/deployment/docker-compose-azure.yaml
@@ -14,6 +14,8 @@ services:
       context: ../application
       args:
         INSTALL_DOCLING: ${INSTALL_DOCLING:-false}
+        # Off by default; deployments running OCR_ENABLED=true with tesseract
+        # must set INSTALL_TESSERACT=true before rebuilding (see docker-compose.yaml).
         INSTALL_TESSERACT: ${INSTALL_TESSERACT:-false}
     env_file:
       - ../.env
@@ -39,6 +41,8 @@ services:
       context: ../application
       args:
         INSTALL_DOCLING: ${INSTALL_DOCLING:-false}
+        # Off by default; deployments running OCR_ENABLED=true with tesseract
+        # must set INSTALL_TESSERACT=true before rebuilding (see docker-compose.yaml).
         INSTALL_TESSERACT: ${INSTALL_TESSERACT:-false}
     # `parsing` queue carries read_document/parse_document; required for its await to resolve.
     command: celery -A application.app.celery worker -l INFO -Q docsgpt,parsing
diff --git a/deployment/docker-compose.yaml b/deployment/docker-compose.yaml
index 4835c4f9..3b10ce5f 100644
--- a/deployment/docker-compose.yaml
+++ b/deployment/docker-compose.yaml
@@ -23,7 +23,10 @@ services:
         INSTALL_DOCLING: ${INSTALL_DOCLING:-false}
         # Bake the tesseract binary behind OCR_ENABLED=true (~35 MB): set
         # INSTALL_TESSERACT=true in ../.env or the shell (setup.sh does this
-        # when OCR is enabled). Off by default, like docling.
+        # when OCR is enabled). Off by default, like docling. Upgrading a
+        # deployment that already runs OCR_ENABLED=true with tesseract: add
+        # INSTALL_TESSERACT=true to ../.env before rebuilding, or scanned
+        # pages fail with an install hint.
         INSTALL_TESSERACT: ${INSTALL_TESSERACT:-false}
     env_file:
       - ../.env
diff --git a/docs/content/Guides/ocr.mdx b/docs/content/Guides/ocr.mdx
index 4850d8ea..8bac7e9b 100644
--- a/docs/content/Guides/ocr.mdx
+++ b/docs/content/Guides/ocr.mdx
@@ -71,6 +71,13 @@ there, point `OCR_ENGINE=deepseek` at a DeepSeek-OCR endpoint or install
 `PATH`, scanned pages fail with an install hint (text-layer documents are
 unaffected).
 
+<Callout type="warning" emoji="⚠️">
+**Upgrading:** earlier images always included tesseract. If your deployment
+runs `OCR_ENABLED=true` with the `tesseract` engine, add
+`INSTALL_TESSERACT=true` to `.env` before rebuilding, or OCR of scanned pages
+stops working after the rebuild.
+</Callout>
+
 ## Installing the docling engine
 
 docling is not part of the base install, and OCR does not need it (see
diff --git a/setup.sh b/setup.sh
index 29089f86..a7fc8a78 100755
--- a/setup.sh
+++ b/setup.sh
@@ -367,7 +367,7 @@ configure_doc_processing() {
     # pre-built Docker Hub images ship without it, so there OCR stays off
     # (its default) rather than being switched on to fail on every scan.
     if [[ "$COMPOSE_FILE" != "$COMPOSE_FILE_LOCAL" ]]; then
-        echo -e "${YELLOW}OCR for scanned PDFs and images stays off: the pre-built Docker Hub images do not include tesseract. To use OCR, rerun setup and choose option 5 (build images locally), or point OCR_ENGINE=deepseek at a DeepSeek-OCR endpoint in .env.${NC}"
+        echo -e "${YELLOW}OCR for scanned PDFs and images stays off: the pre-built Docker Hub images do not include tesseract. To use OCR, rerun setup and choose option 5 (build images locally), or use a DeepSeek-OCR endpoint by adding OCR_ENABLED=true, OCR_ENGINE=deepseek and OCR_DEEPSEEK_URL=<endpoint> to .env.${NC}"
         return
     fi