[Docs] docker: Add troubleshooting guide

[Ahmed3abbas]

🐳 Problem Statement

The current README has Docker setup instructions:
docker-compose up --build

However, new contributors frequently face
platform-specific issues not covered anywhere:

Windows Issues:

• WSL2 not configured properly
• Docker Desktop not running
• Port conflicts on 8000/5173/6379
• Line ending (CRLF vs LF) errors
• Volume mount permission issues

Mac Issues:

• Apple Silicon (M1/M2/M3) compatibility
• Rosetta 2 requirements for some images
• File system performance with volumes
• Redis connection issues on macOS

🎯 Proposed Solution

Add a DOCKER_TROUBLESHOOTING.md file covering:

Windows Setup:

• WSL2 installation & configuration
• Docker Desktop settings for WSL2
• Common error messages + fixes
• Port conflict resolution commands

Mac Setup:

• Apple Silicon compatibility notes
• Docker Desktop memory allocation
• Common permission fixes

Common Issues (All Platforms):

• Redis connection refused → fix
• Database migration failures → fix
• Frontend not hot-reloading → fix
• Container build failures → fix
• Environment variable not found → fix

Quick Diagnostic Commands:

# Check all containers running
docker-compose ps

# View logs for specific service  
docker-compose logs backend
docker-compose logs frontend
docker-compose logs redis

# Reset everything
docker-compose down -v
docker-compose up --build

📁 Files to Add/Modify

• Add: DOCKER_TROUBLESHOOTING.md
• Update: README.md (link to new guide)

✅ Acceptance Criteria

• Windows WSL2 setup guide included
• Mac Apple Silicon notes included
• Common errors documented with fixes
• Diagnostic commands provided
• README links to the new guide
• Tested on at least one platform

💡 Why This Matters

Docker setup is the #1 blocker for new
GSSoC contributors. A troubleshooting guide
will unblock dozens of contributors instantly.

🙋 About Me

GSSoC 2026 Contributor — AI/Agents Track
Certifications: Docker & Kubernetes (Scaler)
Experience: Docker containers, volumes,
Docker Compose, cloud deployments

[Ahmed3abbas]

Hi team 👋

I'm a GSSoC 2026 contributor with Docker &
Kubernetes certification from Scaler.

I've personally faced Docker setup challenges
and want to document solutions for the whole
community. Could you please assign this to me?

I'll have the complete guide ready in 2 days. 🙏

[sathwikshetty33]

We do not think we do need an extensive docker troubleshooting guide here as docker docs does have a very good one. Instead we might update the readme to point to this.

[Ahmed3abbas]

Totally understand and agree Docker's
official docs are already comprehensive!

I can help update the README to include
direct links to the most relevant Docker
troubleshooting pages for this specific
project setup, so contributors don't have
to search through all of Docker's docs.

Specifically I'd add links for:

• WSL2 setup (Windows users)
• Apple Silicon compatibility (Mac users)
• Docker Compose troubleshooting

Would you like me to go ahead with this
smaller README update instead?

It would be a quick, clean PR!

[sathwikshetty33]

Sure please update the issue title something like docker: Add troubleshooting guide and same for the pr. Assigning this to you. Make sure you use ai effieciently and hoping you won't create a aai slop pr.

[Ahmed3abbas]

Thank you for the assignment @sathwikshetty33!

Updated the issue title to:
docker: Add troubleshooting guide

I'll make sure the guide is:

• Genuinely researched & tested
• Specific to InterXAI's docker-compose setup
• Not AI-generated filler content
• Practical and contributor-focused

Will have the PR ready soon working on it !

[Ahmed3abbas]

can you review the PR and accpet it

[Aasritha-sure]

Sure please update the issue title something like docker: Add troubleshooting guide and same for the pr. Assigning this to you. Make sure you use ai effieciently and hoping you won't create a slop pr.

[Ahmed3abbas]

Okay working on it .