Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions Makefile
Original file line number Diff line number Diff line change
Expand Up @@ -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 \
Expand Down
64 changes: 64 additions & 0 deletions QUICK_START_IMPROVEMENTS.md
Original file line number Diff line number Diff line change
@@ -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