docs: add docker compose quickstart

docker/README.md

@@ -1,58 +1,113 @@
-# Docker Compose Quick Start Guide
+# Docker Compose (v2) Quick Start Guide
 
-This Docker Compose configuration allows you to quickly run Semantic Router + Envoy proxy locally.
+Run Semantic Router + Envoy locally using Docker Compose v2.
 
 ## Prerequisites
 
-- Docker and Docker Compose
-- Ensure ports 8801, 50051, 19000 are not in use
+- Docker Engine and Docker Compose v2 (use the `docker compose` command, not the legacy `docker-compose`)
+- Ensure ports 8801, 50051, 19000 are free
 
-## Install in Docker Compose
+## Install and Run with Docker Compose v2
 
-1. **Clone the repository and navigate to the project directory**
+1) Clone the repo and move into it (from your workspace root):
 
-   ```bash
-   git clone https://github.com/vllm-project/semantic-router.git
-   cd semantic_router
-   ```
+```bash
+git clone https://github.com/vllm-project/semantic-router.git
+cd semantic-router
+```
 
-2. **Download required models** (if not already present):
+2) Download required models (classification models):
+
+```bash
+make download-models
+```
 
-   ```bash
-   make download-models
-   ```
+This downloads the classification models used by the router:
 
-   This will download the necessary ML models for classification:
-   - Category classifier (ModernBERT-base)
-   - PII classifier (ModernBERT-base)
-   - Jailbreak classifier (ModernBERT-base)
+- Category classifier (ModernBERT-base)
+- PII classifier (ModernBERT-base)
+- Jailbreak classifier (ModernBERT-base)
 
-3. **Start the services using Docker Compose**
+Note: The BERT similarity model defaults to a remote Hugging Face model. See Troubleshooting for offline/local usage.
 
-   ```bash
-   # Start core services (semantic-router + envoy)
-   docker-compose up --build
+3) Start the services with Docker Compose v2:
 
-   # Or run in background
-   docker-compose up --build -d
+```bash
+# Start core services (semantic-router + envoy)
+docker compose up --build
 
-   # Start with testing services (includes mock vLLM)
-   docker-compose --profile testing up --build
-   ```
+# Or run in background (recommended)
+docker compose up --build -d
 
-4. **Verify the installation**
-   - Semantic Router: http://localhost:50051 (gRPC service)
-   - Envoy Proxy: http://localhost:8801 (main endpoint)
-   - Envoy Admin: http://localhost:19000 (admin interface)
+# With testing profile (includes mock vLLM)
+docker compose --profile testing up --build
+```
 
-## Quick Start
+4) Verify
 
-### 1. Build and Start Services
+- Semantic Router (gRPC): localhost:50051
+- Envoy Proxy: http://localhost:8801
+- Envoy Admin: http://localhost:19000
+
+## Common Operations
 
 ```bash
-# Start core services (semantic-router + envoy)
-docker-compose up --build
+# View service status
+docker compose ps
+
+# Follow logs for the router service
+docker compose logs -f semantic-router
+
+# Exec into the router container
+docker compose exec semantic-router bash
+
+# Stop and clean up containers
+docker compose down
+```
+
+## Troubleshooting
+
+### 1) Router exits immediately with a Hugging Face DNS/download error
+
+Symptoms (from `docker compose logs -f semantic-router`):
+
+```
+Failed to initialize BERT: request error: https://huggingface.co/... Dns Failed: resolve dns name 'huggingface.co:443'
+```
+
+Why: `bert_model.model_id` in `config/config.yaml` points to a remote model (`sentence-transformers/all-MiniLM-L12-v2`). If the container cannot resolve or reach the internet, startup fails.
+
+Fix options:
+
+- Allow network access in the container (recommended):
+  - Ensure your host can resolve DNS, or add DNS servers to the `semantic-router` service in `docker-compose.yml`:
+
+      ```yaml
+      services:
+         semantic-router:
+            # ...
+            dns:
+               - 1.1.1.1
+               - 8.8.8.8
+      ```
+
+  - If behind a proxy, set `http_proxy/https_proxy/no_proxy` env vars for the service.
+
+- Use a local copy of the model (offline):
+   1. Download `sentence-transformers/all-MiniLM-L12-v2` to `./models/sentence-transformers/all-MiniLM-L12-v2/` on the host.
+   2. Update `config/config.yaml` to use the local path (mounted into the container at `/app/models`):
+
+       ```yaml
+       bert_model:
+          model_id: "models/sentence-transformers/all-MiniLM-L12-v2"
+          threshold: 0.6
+          use_cpu: true
+       ```
+
+   3. Recreate services: `docker compose up -d --build`
+
+### 2) Port already in use
+
+Make sure 8801, 50051, 19000 are not bound by other processes. Adjust ports in `docker-compose.yml` if needed.
 
-# Or run in background
-docker-compose up --build -d
 ```