How I solved the disconnection issues

[angelarose210]

I'm using podman instead of docker desktop. I had claude write a troubleshooting guide including the steps I took to solve it. Just thought I'd share since I spent a couple hours going in circles and I see some other people having similar problems.

Archon Troubleshooting Guide

Common Issues and Solutions

Issue: Frontend 500 Errors and WebSocket Connection Failures

Symptoms:

• Frontend shows 500 Internal Server Error for API calls
• Projects page fails to load with "Failed to load resource: the server responded with a status of 500"
• WebSocket connection errors: "WebSocket connection to 'ws://localhost:3738/socket.io/' failed"
• API endpoints like /api/projects and /api/health return 500 errors when accessed through frontend

Root Cause:
The frontend container's Vite proxy configuration was trying to connect to localhost:8181 instead of the Docker service name archon-server:8181. Inside Docker containers, localhost refers to the container itself, not the Docker host or other containers.

Solution:

1. Add DOCKER_ENV=true to frontend container environment in docker-compose.yml:

   archon-frontend:
     environment:
       - DOCKER_ENV=true
       # ... other env vars

2. Rebuild frontend container to pick up the environment variable:

   podman-compose stop archon-frontend
   podman build --no-cache -t archon_archon-frontend:latest ./archon-ui-main
   podman-compose up archon-frontend -d

Technical Details:

• The vite.config.ts file checks DOCKER_ENV to determine proxy target
• When DOCKER_ENV=true: uses archon-server:8181 (Docker service name)
• When DOCKER_ENV=false or unset: uses localhost:8181 (for local development)

---

Issue: Port 3737 Already in Use

Symptoms:

• Error: "bind: address already in use" for port 3737
• Frontend container fails to start

Solution:

1. Change port in .env file:

   ARCHON_UI_PORT=3738  # or any available port

2. Restart services:

   podman-compose restart archon-frontend

---

Issue: podman-compose Dockerfile Recognition Problems

Symptoms:

• podman-compose ignores Dockerfile specifications
• Containers fail to build properly

Solution:
Use manual build commands instead of relying on compose build:

# Build each service manually
podman build -f python/Dockerfile.server -t archon_archon-server:latest ./python
podman build -f python/Dockerfile.mcp -t archon_archon-mcp:latest ./python
podman build -f python/Dockerfile.agents -t archon_archon-agents:latest ./python
podman build -t archon_archon-frontend:latest ./archon-ui-main
 
# Then start services
podman-compose --profile full up -d --no-build

---

Issue: Container Name Conflicts

Symptoms:

• Error: "container name is already in use"
• Services fail to start due to existing containers

Solution:
Clean up existing containers:

podman-compose down
podman container rm -f archon-server archon-mcp archon-agents archon-ui
podman pod rm -f archon_default

---

Issue: Authentication/Credentials Problems

Symptoms:

• 403 Forbidden errors from internal services
• "Permission denied" errors in logs

Common Causes & Solutions:

1. Windows Environment Variables Override:

   • Remove conflicting SUPABASE_ACCESS_TOKEN from Windows environment
   • Ensure only SUPABASE_SERVICE_KEY is set in .env file

2. Wrong Supabase Key Type:

   • Must use service_role key, NOT anon key
   • Service role key is longer and contains "service_role" in JWT

3. OpenAI/Gemini Conflicts:

   • If using Gemini, unset OPENAI_API_KEY in Windows environment
   • Set API keys through Archon's Settings UI instead of environment variables

---

Environment Configuration Reference

Required .env Variables:

# Core Database
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_SERVICE_KEY=your-service-role-key-here
 
# API Configuration
GOOGLE_API_KEY=your-gemini-api-key
LLM_PROVIDER=gemini
MODEL_CHOICE=gemini-1.5-pro
 
# Port Configuration
ARCHON_SERVER_PORT=8181
ARCHON_MCP_PORT=8051
ARCHON_AGENTS_PORT=8052
ARCHON_UI_PORT=3738  # Changed from 3737 due to conflict
 
# Frontend Networking (important for Docker)
DOCKER_ENV=false  # Set to false in .env, true in docker-compose.yml
VITE_API_URL=http://localhost:8181
VITE_ARCHON_SERVER_PORT=8181

Docker Compose Environment:

archon-frontend:
  environment:
    - DOCKER_ENV=true  # Key for proper Docker networking
    - VITE_API_URL=http://${HOST:-localhost}:${ARCHON_SERVER_PORT:-8181}
    - ARCHON_SERVER_PORT=${ARCHON_SERVER_PORT:-8181}

---

Diagnostic Commands

Check Service Health:

curl http://localhost:8181/health  # Backend
curl http://localhost:8051/health  # MCP (might return 404 - normal)
curl http://localhost:8052/health  # Agents
curl http://localhost:3738/        # Frontend

Test API Proxy:

curl http://localhost:3738/api/health     # Through frontend proxy
curl http://localhost:3738/api/projects   # Projects endpoint

Check Container Status:

podman-compose ps
podman-compose logs archon-server --tail=20
podman-compose logs archon-frontend --tail=20

Verify Environment Variables:

podman exec archon-ui env | grep VITE
podman exec archon-ui env | grep DOCKER_ENV

---

Clean Restart Procedure

When experiencing multiple issues, use this complete restart:

1. Stop all services:

   podman-compose down

2. Clean up containers and networks:

   podman container rm -f archon-server archon-mcp archon-agents archon-ui
   podman pod rm -f archon_default

3. Rebuild all images:

   podman build -f python/Dockerfile.server -t archon_archon-server:latest ./python
   podman build -f python/Dockerfile.mcp -t archon_archon-mcp:latest ./python
   podman build -f python/Dockerfile.agents -t archon_archon-agents:latest ./python
   podman build --no-cache -t archon_archon-frontend:latest ./archon-ui-main

4. Start services:

   podman-compose --profile full up -d --no-build

5. Verify all services:

   sleep 15  # Wait for startup
   podman-compose ps
   curl http://localhost:3738/api/health

---

Prevention Tips

1. Always set DOCKER_ENV=true in docker-compose.yml for frontend container
2. Use service names (archon-server) for inter-container communication
3. Rebuild frontend after environment changes - Vite config is evaluated at build time
4. Keep Windows environment variables minimal - prefer .env file and UI settings
5. Use unique ports to avoid conflicts with other services
6. Test proxy endpoints after any networking changes

---

Network Architecture

Browser → localhost:3738 (Frontend Container)
       ↓
Vite Proxy → archon-server:8181 (Backend Container)
           ↓
Backend APIs → archon-mcp:8051 (MCP Container)
            → archon-agents:8052 (Agents Container)
            → Supabase (External)

[coleam00]

Catching up on issues and PRs right now - thanks for this @angelarose210! Did you make a PR for this already? I would appreciate that a lot!

[Wirasm]

@angelarose210 Thank you, will move this to the show and tell area, please put up a PR if you have ideas for this and how to make it part of Archon