lad-website/cline_docs/dockerNetworkingTroubleshooting.md

# Docker Networking Troubleshooting - OCD Website Members Admin System

## Issue Summary
**Date**: June 2, 2025, 10:22 PM  
**Problem**: Frontend container cannot communicate with backend container despite successful infrastructure setup  
**Impact**: Members admin page shows "AxiosError: Network Error" preventing member management functionality  

## Problem Timeline

### Initial Issue Discovery
- **User Report**: Members admin page showing network errors
- **Browser Console**: "AxiosError: Request failed with status code 404" initially, then "Network Error"
- **Expected Behavior**: Members page should load member data from backend API

### Diagnostic Journey

#### Phase 1: Initial API Connectivity (✅ RESOLVED)
**Problem**: Backend not responding to API calls
**Root Cause**: MongoDB connection failures due to authentication and environment variable issues

**Steps Taken**:
1. Checked container status: `docker ps` - all containers running
2. Tested backend health: `curl http://localhost:4000/health` - failing
3. Examined backend logs: MongoDB connection errors to `localhost:27017`
4. Identified issue: Backend trying to connect to `localhost` instead of `mongodb` service

**Resolution**:
1. Updated `docker-compose.dev.yml` backend environment variables:
   ```yaml
   environment:
     - MONGO_HOST=mongodb
     - MONGO_PORT=27017
     - MONGO_DB=ocd_db
     - MONGO_USER=admin
     - MONGO_PASSWORD=admin
   ```
2. Enhanced `backend/src/index.ts` MongoDB connection logic for better error handling
3. Force-recreated backend container: `docker compose -f docker-compose.dev.yml up -d --force-recreate backend`

**Result**: Backend API now responding successfully
- Health check: `{"status":"ok","timestamp":"2025-06-03T04:16:23.379Z"}`
- Members endpoint: Returns member data including test user "John Smith"

#### Phase 2: Frontend-Backend Communication (❌ STILL FAILING)
**Problem**: Frontend still showing network errors despite working backend
**Root Cause**: Frontend configured to call `localhost:4000` instead of `backend:4000`

**Steps Taken**:
1. Checked frontend environment: `NEXT_PUBLIC_API_URL=http://localhost:4000`
2. Updated `docker-compose.dev.yml` frontend environment:
   ```yaml
   environment:
     - NEXT_PUBLIC_API_URL=http://backend:4000
   ```
3. Force-recreated frontend container: `docker compose -f docker-compose.dev.yml up -d --force-recreate frontend`
4. Verified environment update: `NEXT_PUBLIC_API_URL=http://backend:4000`

**Current Status**: Frontend has correct environment but still cannot reach backend

### Parallel Work: Members Component Theme Compliance (✅ COMPLETED)
While troubleshooting networking, completed theme compliance work:

**Files Modified**:
- `frontend/src/app/admin/members/page.tsx`
  - Converted all `dark:` classes to admin CSS system
  - Updated card classes: `card` → `admin-card admin-gold-accent`
  - Updated form elements: `admin-form-label`, `admin-form-select`, `admin-form-input`
  - Updated buttons: `admin-btn-primary`, `admin-btn-secondary`
  - Updated table classes: `admin-table`, `admin-table-header`, `admin-table-body`
  - Updated page header: `admin-page-header`, `admin-page-header-title`

**Result**: Members component now fully compliant with admin theme system

## Current State Analysis

### What's Working ✅
1. **Docker Containers**: All three containers (frontend, backend, mongodb) running healthy
2. **Backend API**: Responding correctly to external requests
3. **MongoDB**: Connected and storing data successfully
4. **Test Data**: Member records created and retrievable via API
5. **Frontend Environment**: Correctly configured with `http://backend:4000`
6. **Theme System**: Members component fully theme-compliant

### What's Failing ❌
1. **Frontend-to-Backend Communication**: Network error when browser tries to fetch from backend
2. **Service Discovery**: Frontend container may not be able to resolve `backend` hostname
3. **Network Routing**: Docker network may have configuration issues

## Technical Investigation Details

### Environment Variables Verified
**Backend Container**:
```bash
MONGO_HOST=mongodb
MONGO_PORT=27017
MONGO_DB=ocd_db
MONGO_USER=admin
MONGO_PASSWORD=admin
```

**Frontend Container**:
```bash
NEXT_PUBLIC_API_URL=http://backend:4000
```

### API Testing Results
**From Host Machine**:
```bash
curl http://localhost:4000/health
# Returns: {"status":"ok","timestamp":"2025-06-03T04:16:23.379Z"}

curl http://localhost:4000/api/members
# Returns: {"members":[{"_id":"683e7679b0eebe05c945580a","firstName":"John",...}],"pagination":{...}}
```

**From Frontend Container**:
- Unable to test due to curl not being available in container
- Need to verify if `http://backend:4000` is accessible from frontend container

## Next Steps for Resolution

### Immediate Debugging Actions Needed
1. **Test Hostname Resolution**: Check if frontend container can resolve `backend` hostname
   ```bash
   docker exec ocd-website-frontend-1 nslookup backend
   ```

2. **Test Container-to-Container Connectivity**: Verify network communication
   ```bash
   docker exec ocd-website-frontend-1 wget -O- http://backend:4000/health
   ```

3. **Inspect Docker Network**: Verify network configuration
   ```bash
   docker network inspect ocd-website_app-network
   ```

4. **Check Frontend Logs**: Look for specific error details
   ```bash
   docker logs ocd-website-frontend-1 --tail 20
   ```

### Alternative Solutions to Try
1. **Use Container IP Instead of Service Name**: Get backend container IP and test direct connection
2. **Update Network Configuration**: Ensure all containers are on same network
3. **Add Network Aliases**: Configure explicit network aliases in docker-compose
4. **Check Port Conflicts**: Verify no port conflicts or firewall issues

### Browser-Side Considerations
1. **CORS Issues**: Backend CORS configuration may block frontend requests
2. **Next.js Build Issues**: Frontend may need rebuild after environment changes
3. **Cache Issues**: Browser cache may be interfering with requests

## Files Modified During Troubleshooting

### Configuration Files
1. **docker-compose.dev.yml**
   - Updated backend MongoDB environment variables
   - Updated frontend API URL environment variable

2. **backend/src/index.ts**
   - Enhanced MongoDB connection string building
   - Added connection logging for debugging
   - Improved error handling for authentication

### Frontend Components
1. **frontend/src/app/admin/members/page.tsx**
   - Complete conversion to admin CSS theme system
   - Removed all `dark:` inline classes
   - Implemented consistent admin styling patterns

## Success Criteria
**Task will be complete when**:
1. ✅ Backend API responding (ACHIEVED)
2. ✅ Frontend has correct environment configuration (ACHIEVED)
3. ✅ Members component theme-compliant (ACHIEVED)
4. ❌ Frontend can successfully fetch data from backend API
5. ❌ Members admin page displays member data without errors
6. ❌ CRUD operations work end-to-end

## Risk Assessment
**Low Risk**: Theme and backend infrastructure work is complete and stable
**Medium Risk**: Network configuration changes may require container recreation
**High Risk**: May need to modify Next.js configuration or rebuild frontend

## Estimated Resolution Time
- **Quick Fix (if simple network issue)**: 15-30 minutes
- **Configuration Changes**: 30-60 minutes  
- **Architectural Changes**: 1-2 hours

## Contact/Handoff Information
**Current Developer Environment**:
- Docker Desktop running on macOS
- All containers operational
- Test data available in MongoDB
- Frontend and backend code ready for testing

**Next Developer Should**:
1. Verify current container status
2. Test network connectivity between containers
3. Check browser network tab for specific error details
4. Consider alternative connection methods if hostname resolution fails