fix: allow compose to start without MODEL_URL; defer missing-model error to runtime

The hard ${MODEL_URL:?...} gate made 'docker compose up' fail at config
parsing if no .env existed — container never started, no logs beyond
compose's own error. Now:

- MODEL_URL defaults to empty in compose. The Python loader checks at
  startup and raises a clear FileNotFoundError naming the missing path
  and the two ways to fix it (set MODEL_URL, or mount a local file).
- Document an alternative local-mount flow in README, mirroring
  word2sim's ./vectors.bin pattern.
- Add container_name: phow2sim for easier docker ps / docker logs.

README.md

@@ -103,6 +103,20 @@ tries exact → lowercase → space-to-underscore variants.
    restarts load in ~10s. Health check start period is 10 min to cover
    the first-boot cost.
 
+### Alternative: mount a local file instead
+
+If you've already downloaded the `.txt` locally and don't want to
+re-upload anywhere, skip `MODEL_URL` entirely and mount the file. In
+`docker-compose.yml`, uncomment the bind mount:
+
+```yaml
+volumes:
+  - phow2v-cache:/data/phow2v
+  - ./models/word2vec_vi_words_300dims.txt:/data/phow2v/word2vec_vi_words_300dims.txt:ro
+```
+
+Then `docker compose up` boots straight into parse — no download step.
+
 ## Switching variant
 
 Host the desired zip and update `.env`:

app/vectors.py

@@ -75,10 +75,11 @@ def load_model() -> KeyedVectors:
         return _MODEL
 
     if not txt_path.exists():
-        url = os.environ.get("MODEL_URL")
+        url = os.environ.get("MODEL_URL", "").strip()
         if not url:
             raise FileNotFoundError(
-                f"MODEL_PATH {txt_path} missing and no MODEL_URL set for auto-download"
+                f"no vectors at MODEL_PATH={txt_path}; set MODEL_URL in .env "
+                f"(or mount a local .txt into {txt_path.parent}) and retry"
             )
         _download_and_extract(url, txt_path)
 

docker-compose.yml

@@ -1,18 +1,20 @@
 services:
   phow2sim:
     build: .
+    container_name: phow2sim
     ports:
       - "8001:8000"
     environment:
-      # MODEL_URL: a URL that serves the PhoW2V zip with a plain GET.
-      # Any auth (share token, signed URL, etc.) must be encoded in the
-      # URL itself — the service does not send Authorization headers.
-      # Example (Nextcloud public share):
-      #   https://cloud.example.com/s/<shareToken>/download
-      MODEL_URL: ${MODEL_URL:?set MODEL_URL in .env to your PhoW2V zip URL}
+      # URL serving the PhoW2V zip with a plain GET. Any auth goes in
+      # the URL itself (share token, signed URL, etc.) — the service
+      # sends no Authorization header. Leave empty only if you've
+      # pre-populated the volume (see the volume mount below).
+      MODEL_URL: ${MODEL_URL:-}
       MODEL_PATH: ${MODEL_PATH:-/data/phow2v/word2vec_vi_words_300dims.txt}
     volumes:
       - phow2v-cache:/data/phow2v
+      # Or mount a locally-downloaded .txt and skip MODEL_URL entirely:
+      # - ./models/word2vec_vi_words_300dims.txt:/data/phow2v/word2vec_vi_words_300dims.txt:ro
     restart: unless-stopped
 
 volumes: