From 822c254b197cd463f78ede40a07757b63a15f25f Mon Sep 17 00:00:00 2001
From: Vicky Kuo <vicky.kuo@ibm.com>
Date: Sun, 1 Feb 2026 21:04:42 -0500
Subject: [PATCH] fix: Auto-create volume directories to prevent infrastructure
 startup errors

- Added automatic creation of volumes/etcd, volumes/milvus, and volumes/postgres directories in Makefile
- Prevents 'failed to mount local volume' error on first run of make local-dev-infra
- Added QUICK_START_IMPROVEMENTS.md documenting the issue, solution, and testing

Fixes the Docker volume mount error that occurred when running infrastructure services
for the first time without pre-existing volume directories.

Signed-off-by: Vicky Kuo <vicky.kuo@ibm.com>
---
 Makefile                    |  1 +
 QUICK_START_IMPROVEMENTS.md | 64 +++++++++++++++++++++++++++++++++++++
 2 files changed, 65 insertions(+)
 create mode 100644 QUICK_START_IMPROVEMENTS.md

diff --git a/Makefile b/Makefile
index 9d1ff28e..c5c026a7 100644
--- a/Makefile
+++ b/Makefile
@@ -119,6 +119,7 @@ local-dev-setup:
 
 local-dev-infra:
 	@echo "$(CYAN)🏗️  Starting infrastructure (Postgres, Milvus, MinIO, MLFlow)...$(NC)"
+	@mkdir -p volumes/etcd volumes/milvus volumes/postgres
 	@if docker ps --format '{{.Names}}' | grep -q 'milvus-etcd'; then \
 		echo "$(YELLOW)⚠️  Infrastructure containers already running$(NC)"; \
 	else \
diff --git a/QUICK_START_IMPROVEMENTS.md b/QUICK_START_IMPROVEMENTS.md
new file mode 100644
index 00000000..d9cababd
--- /dev/null
+++ b/QUICK_START_IMPROVEMENTS.md
@@ -0,0 +1,64 @@
+# Quick Start Guide Improvements
+
+## Problem Identified
+
+During the initial setup following the Quick Start guide in README.md, the following error occurred when running `make local-dev-infra`:
+
+```
+Error response from daemon: error while mounting volume '/var/lib/docker/volumes/rag_modulo_etcd_data/_data': 
+failed to mount local volume: mount /Users/vicky/Desktop/rag_modulo/volumes/etcd:/var/lib/docker/volumes/rag_modulo_etcd_data/_data, 
+flags: 0x1000: no such file or directory
+```
+
+**Root Cause**: The Docker volume mount directories (`volumes/etcd`, `volumes/milvus`, `volumes/postgres`) did not exist, causing the infrastructure services to fail on first run.
+
+## Solution Implemented
+
+### Makefile Fix
+**File**: `Makefile`
+**Change**: Added automatic directory creation in the `local-dev-infra` target
+
+```makefile
+local-dev-infra:
+	@echo "$(CYAN)🏗️  Starting infrastructure (Postgres, Milvus, MinIO, MLFlow)...$(NC)"
+	@mkdir -p volumes/etcd volumes/milvus volumes/postgres  # <-- Added this line
+	@if docker ps --format '{{.Names}}' | grep -q 'milvus-etcd'; then \
+		...
+```
+
+**Benefits**:
+- ✅ Automatic - no manual user intervention required
+- ✅ Idempotent - safe to run multiple times
+- ✅ Prevents the error from occurring
+- ✅ Better user experience
+
+## Testing
+
+The fix was validated by:
+1. ✅ Running `make local-dev-infra` successfully after the fix
+2. ✅ Verifying all infrastructure services started correctly:
+   - PostgreSQL (healthy)
+   - Milvus (healthy)
+   - MinIO (healthy)
+   - MLFlow (running)
+   - Milvus-etcd (healthy)
+3. ✅ Running `make local-dev-all` successfully
+4. ✅ Verifying backend and frontend services started correctly
+
+## Impact
+
+**Before**: Users would encounter a cryptic Docker volume mount error on first run, requiring manual troubleshooting and directory creation.
+
+**After**: Setup works seamlessly on first run with no manual intervention required.
+
+## Files Changed
+
+1. `Makefile` - Added automatic volume directory creation
+
+## Recommendation
+
+This PR should be merged to improve the first-time user experience and prevent setup failures. The fix is:
+- Non-breaking
+- Backward compatible
+- Improves reliability
+- Requires no changes to existing workflows
\ No newline at end of file