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:

   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:

   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:

MONGO_HOST=mongodb
MONGO_PORT=27017
MONGO_DB=ocd_db
MONGO_USER=admin
MONGO_PASSWORD=admin

Frontend Container:

NEXT_PUBLIC_API_URL=http://backend:4000

API Testing Results

From Host Machine:

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

   docker exec ocd-website-frontend-1 nslookup backend
   

2. Test Container-to-Container Connectivity: Verify network communication

   docker exec ocd-website-frontend-1 wget -O- http://backend:4000/health
   

3. Inspect Docker Network: Verify network configuration

   docker network inspect ocd-website_app-network
   

4. Check Frontend Logs: Look for specific error details

   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