From 0ed0ae9ce89f056d19a9c532caa591b3410d168a Mon Sep 17 00:00:00 2001
From: Michael <michael.schapira@us.ibm.com>
Date: Mon, 23 Feb 2026 12:20:16 -0500
Subject: [PATCH] Update DEPLOYMENT.md with critical .env format requirements

- Emphasize that inline comments cause service startup failures
- Show correct .env format without inline comments
- Add example error message when inline comments are present
- Include sed command to fix existing .env files with inline comments
- Add model mapping examples in correct format
---
 DEPLOYMENT.md | 27 ++++++++++++++++++++++++---
 1 file changed, 24 insertions(+), 3 deletions(-)

diff --git a/DEPLOYMENT.md b/DEPLOYMENT.md
index 8f9c168..cd04990 100644
--- a/DEPLOYMENT.md
+++ b/DEPLOYMENT.md
@@ -56,9 +56,9 @@ Create `.env` file (copy from `.env.example`):
 cp .env.example .env
 ```
 
-**IMPORTANT**: Remove all inline comments from `.env` file. Pydantic cannot parse values with inline comments.
+**CRITICAL**: The `.env` file must NOT contain inline comments. Pydantic cannot parse environment variables with inline comments and will cause the service to fail with validation errors.
 
-**Correct format:**
+**Correct format (no inline comments):**
 ```bash
 IBM_CLOUD_API_KEY=your_api_key_here
 WATSONX_PROJECT_ID=your_project_id_here
@@ -67,14 +67,35 @@ HOST=0.0.0.0
 PORT=8000
 LOG_LEVEL=info
 TOKEN_REFRESH_INTERVAL=3000
+
+# Model mappings (optional)
+MODEL_MAP_GPT4=openai/gpt-oss-120b
+MODEL_MAP_GPT4_TURBO=meta-llama/llama-3-3-70b-instruct
+MODEL_MAP_GPT4_TURBO_PREVIEW=mistral-large-2512
 ```
 
-**Incorrect format (will cause errors):**
+**Incorrect format (will cause service startup failure):**
 ```bash
+# ❌ DO NOT USE INLINE COMMENTS - Service will fail to start
 LOG_LEVEL=info  # Options: debug, info, warning, error
 TOKEN_REFRESH_INTERVAL=3000  # Refresh token every N seconds
 ```
 
+**Error you'll see if inline comments are present:**
+```
+pydantic_core._pydantic_core.ValidationError: 1 validation error for Settings
+token_refresh_interval
+  Input should be a valid integer, unable to parse string as an integer
+```
+
+**To fix existing .env files with inline comments:**
+```bash
+# Remove all inline comments
+sed -i 's/\s*#.*$//' /home/app/watsonx-openai-proxy/.env
+
+# Or manually edit and remove everything after the value on each line
+```
+
 ## Systemd Service Setup
 
 ### 1. Create Service Unit