Skip to content

Fix Linux Docker Networking and Add Flexible Port Configuration #195

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
hebelmx wants to merge 4 commits into from
Closed

Fix Linux Docker Networking and Add Flexible Port Configuration #195

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
d2e51cb
Network Isolation
hebelmx Aug 14, 2025
c8a8e77
aded pr draft
hebelmx Aug 14, 2025
81ee4f8
Merge branch 'main' into coleArchon
hebelmx Aug 22, 2025
e6f5a03
Update start_archon.sh
hebelmx Aug 25, 2025
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
108 changes: 108 additions & 0 deletions DEPLOYMENT_SUCCESS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,108 @@
# Archon Deployment Success - August 14, 2025

## 🎉 Successfully Deployed Archon with Custom Configuration

### Deployment Summary
Successfully deployed Archon with local Supabase integration, custom ports, and Ollama configuration for local LLM usage.

### Key Achievements

#### 1. ✅ Fixed Docker Connection Issues
- Resolved DOCKER_HOST environment variable conflict with Podman
- Created startup script to properly unset DOCKER_HOST
- Ensured Docker daemon connectivity

#### 2. ✅ Configured Custom Ports (No Conflicts)
**External → Internal Port Mappings:**
- Web UI: `4838 → 5173`
- API Server: `9282 → 8181`
- MCP Server: `9151 → 8051`
- Agents Service: `9152 → 8052`

**Avoided conflicts with:**
- Existing Supabase (54321-54327)
- CubExplorer Streamlit apps (8501, 8504)

#### 3. ✅ Solved Network Connectivity
**Problem:** Archon containers couldn't reach Supabase on localhost
**Solution:** Connected Archon containers to Supabase's Docker network (`supabase_network_Archon`)
- Changed from isolated network to shared Supabase network
- Updated connection URLs to use container names (`supabase_kong_Archon:8000`)

#### 4. ✅ Environment Configuration
```bash
# .env configuration
SUPABASE_URL=http://localhost:54321
SUPABASE_SERVICE_KEY=eyJhbGc... # Local Supabase default key
ARCHON_SERVER_PORT=9282
ARCHON_MCP_PORT=9151
ARCHON_AGENTS_PORT=9152
ARCHON_UI_PORT=4838
OLLAMA_HOST=http://host.docker.internal:11434
```
Comment on lines +33 to +42
Copy link
Copy Markdown

@coderabbitai coderabbitai Bot Aug 22, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue

Correct SUPABASE_URL for shared Docker network (localhost:54321 is likely wrong here).

This doc states containers use the shared Supabase network and container-name URLs (Line 30), but the .env sample still points SUPABASE_URL to localhost:54321, which is the Postgres port, not the Supabase REST gateway. For in-network service-to-service calls, use Kong on port 8000 via the container name. Add a remote option for non-local setups.

Apply this diff to fix and clarify:

-# .env configuration
-SUPABASE_URL=http://localhost:54321
-SUPABASE_SERVICE_KEY=eyJhbGc...  # Local Supabase default key
-ARCHON_SERVER_PORT=9282
-ARCHON_MCP_PORT=9151
-ARCHON_AGENTS_PORT=9152
-ARCHON_UI_PORT=4838
-OLLAMA_HOST=http://host.docker.internal:11434
+# .env configuration
+# For shared Docker network (recommended for local dev):
+SUPABASE_URL=http://supabase_kong_Archon:8000
+SUPABASE_SERVICE_KEY=eyJhbGc...  # Local Supabase default key
+# For remote Supabase project, override with your project's URL instead:
+# SUPABASE_URL=https://<your-project-ref>.supabase.co
+ARCHON_SERVER_PORT=9282
+ARCHON_MCP_PORT=9151
+ARCHON_AGENTS_PORT=9152
+ARCHON_UI_PORT=4838
+OLLAMA_HOST=http://host.docker.internal:11434
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
```bash
# .env configuration
SUPABASE_URL=http://localhost:54321
SUPABASE_SERVICE_KEY=eyJhbGc... # Local Supabase default key
ARCHON_SERVER_PORT=9282
ARCHON_MCP_PORT=9151
ARCHON_AGENTS_PORT=9152
ARCHON_UI_PORT=4838
OLLAMA_HOST=http://host.docker.internal:11434
```
🤖 Prompt for AI Agents 
In DEPLOYMENT_SUCCESS.md around lines 33 to 42, the .env sample incorrectly sets
SUPABASE_URL to localhost:54321 (Postgres port) despite containers using the
shared Supabase network; update the example to use the Supabase Kong gateway via
the service container name and port 8000 (e.g., http://supabase:8000) for
in-network service-to-service calls, and add an alternative note showing a
remote/public SUPABASE_URL option for non-Docker/local setups so users know when
to use localhost vs the container gateway.


#### 5. ✅ Database Setup
- Archon tables already initialized in local Supabase
- All migrations successfully applied
- Settings table ready for configuration

### Docker Architecture
```
Archon Containers → supabase_network_Archon ← Supabase Containers
↓
Internal Communication
(using container names)
```

### Quick Commands

#### Start Archon
```bash
unset DOCKER_HOST && docker compose up -d
# OR use the startup script:
./start_archon.sh
```

#### Stop Archon
```bash
unset DOCKER_HOST && docker compose down
```

#### View Logs
```bash
unset DOCKER_HOST && docker compose logs -f
```

#### Check Health
```bash
curl http://localhost:9282/health # API Server
curl http://localhost:9152/health # Agents Service
```

### Access Points
- **Web UI**: http://localhost:4838
- **API Server**: http://localhost:9282
- **MCP Server**: http://localhost:9151
- **Agents Service**: http://localhost:9152
- **Supabase Studio**: http://localhost:54323

### Next Steps
1. Open Web UI at http://localhost:4838
2. Configure Ollama in Settings
3. Start using Knowledge Base features
4. Set up MCP integration with AI coding assistants

### Troubleshooting Tips
- Always use `unset DOCKER_HOST` before Docker commands
- Containers use internal ports (8181, 8051, 8052)
- External ports are mapped for browser access
- All services share `supabase_network_Archon` network

### Port Mapping Reminder
Docker syntax: `EXTERNAL:INTERNAL`
- Example: `4838:5173` means:
- Access via browser: `localhost:4838`
- Container listens on: `5173`

---
*Deployment completed successfully on August 14, 2025*
239 changes: 239 additions & 0 deletions DEPLOYMENT_TROUBLESHOOTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,239 @@
# Archon Deployment Troubleshooting Guide

## Common Issues and Solutions

### 1. Container Can't Connect to Supabase (Connection Timeout)

**Symptoms:**
```
httpx.ConnectTimeout: timed out
ERROR: Application startup failed. Exiting.
```

**Causes & Solutions:**

#### A. Network Isolation (Most Common on Linux)
**Problem:** Docker containers can't reach host services through `localhost` or `host.docker.internal`

**Solution 1 - Use Docker Bridge Gateway:**
```yaml
# docker-compose.yml
environment:
- SUPABASE_URL=http://172.17.0.1:54321 # Docker bridge gateway IP
```

**Solution 2 - Share Supabase Network:**
```yaml
# docker-compose.yml
networks:
app-network:
external: true
name: supabase_network_name # Find with: docker network ls

environment:
- SUPABASE_URL=http://supabase_kong:8000 # Use container name
```

#### B. Incorrect Host Resolution
**Problem:** `host.docker.internal` doesn't work on Linux

**Solution:**
```yaml
# docker-compose.yml
extra_hosts:
- "host.docker.internal:host-gateway" # Let Docker resolve it
```
Comment on lines +25 to +45
Copy link
Copy Markdown

@coderabbitai coderabbitai Bot Aug 22, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Verification agent

🧩 Analysis chain

Prefer one consistent example for Supabase addressing and verify the actual service name.

Docs toggle between supabase_kong and supabase_kong_Archon. Confirm the real container name on the shared network and stick to it to prevent copy/paste failures.

To verify, run:

Then update all occurrences in docs and compose to the single correct name (e.g., supabase_kong or supabase-kong) and keep the examples consistent.

🏁 Script executed:

#!/bin/bash
# Inspect the network and list service names reachable by Archon
docker network inspect supabase_network_Archon | jq '.[0].Containers | to_entries[] | .value.Name' -r

Length of output: 200

🏁 Script executed:

#!/bin/bash
# Locate all docker-compose.yml files in the repo and inspect for supabase references
compose_files=$(find . -type f -name 'docker-compose.yml')
if [ -z "$compose_files" ]; then
  echo "No docker-compose.yml found"
  exit 0
fi

for f in $compose_files; do
  echo "----- File: $f -----"
  rg -n 'supabase_' -C3 "$f" || echo "No supabase references in $f"
done

Length of output: 1233

🏁 Script executed:

#!/bin/bash
# Display the full docker-compose.yml to confirm service names and container_name overrides
sed -n '1,200p' docker-compose.yml

Length of output: 5343

Consolidate Supabase Network & Container Naming in Docs

Please update DEPLOYMENT_TROUBLESHOOTING.md so that the Supabase network and container names match those configured in your docker-compose.yml (which uses supabase_network_Archon and supabase_kong_Archon). Also, add a brief reminder to verify the actual names on your machine.

• File: DEPLOYMENT_TROUBLESHOOTING.md (lines 25–45)
– Replace supabase_network_name with supabase_network_Archon.
– Replace http://supabase_kong:8000 with http://supabase_kong_Archon:8000.
– Add a note: “Verify your Supabase network and container names via docker network inspect supabase_network_Archon and adjust accordingly.”

Updated snippet:

 networks:
   app-network:
-    external: true
-    name: supabase_network_name  # Find with: docker network ls
+    external: true
+    name: supabase_network_Archon  # Replace with your actual Supabase network name

 environment:
-  - SUPABASE_URL=http://supabase_kong:8000  # Use container name
+  - SUPABASE_URL=http://supabase_kong_Archon:8000  # Use actual container name

 # (…rest of troubleshooting steps…)

+> **Note:** Container names may be prefixed by your project name.  
+> Run `docker network inspect supabase_network_Archon | jq '.[0].Containers | to_entries[] | .value.Name' -r`  
+> to confirm the correct Supabase container name on your network.
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
**Solution 2 - Share Supabase Network:**
```yaml
# docker-compose.yml
networks:
app-network:
external: true
name: supabase_network_name # Find with: docker network ls
environment:
- SUPABASE_URL=http://supabase_kong:8000 # Use container name
```
#### B. Incorrect Host Resolution
**Problem:** `host.docker.internal` doesn't work on Linux
**Solution:**
```yaml
# docker-compose.yml
extra_hosts:
- "host.docker.internal:host-gateway" # Let Docker resolve it
```
**Solution 2 - Share Supabase Network:**
🧰 Tools
🪛 LanguageTool

[grammar] ~37-~37: There might be a mistake here.
Context: ...e ``` #### B. Incorrect Host Resolution Problem: host.docker.internal doesn'...

(QB_NEW_EN)

🤖 Prompt for AI Agents 
In DEPLOYMENT_TROUBLESHOOTING.md around lines 25 to 45, the doc uses generic
Supabase network/container names that don't match our docker-compose; update the
references so they match the actual names: replace supabase_network_name with
supabase_network_Archon and replace http://supabase_kong:8000 with
http://supabase_kong_Archon:8000, and add a one-line reminder to verify and
adjust names on the host (e.g., “Verify your Supabase network and container
names via docker network inspect supabase_network_Archon and docker ps and
adjust accordingly”).


### 2. Port Conflicts

**Symptoms:**
```
Error response from daemon: driver failed programming external connectivity
Bind for 0.0.0.0:8181 failed: port is already allocated
```

**Solution:**
```bash
# .env - Use different external ports
ARCHON_SERVER_PORT=9282 # Instead of 8181
ARCHON_MCP_PORT=9151 # Instead of 8051
ARCHON_AGENTS_PORT=9152 # Instead of 8052
ARCHON_UI_PORT=4838 # Instead of 3737
```

### 3. DOCKER_HOST Environment Conflicts

**Symptoms:**
```
Cannot connect to the Docker daemon at unix:///run/user/1000/podman/podman.sock
```

**Cause:** System has Podman or custom Docker configuration

**Solution:**
```bash
# Always unset DOCKER_HOST before Docker commands
unset DOCKER_HOST && docker compose up -d

# Or add to ~/.bashrc for permanent fix:
alias docker-compose='unset DOCKER_HOST && docker compose'
```

### 4. Container Health Check Failures

**Symptoms:**
- Container shows as `(unhealthy)` in docker ps
- Services don't respond on expected ports

**Debugging Steps:**
```bash
# Check detailed logs
docker logs Archon-Server --tail=50

# Test internal connectivity
docker exec Archon-Server python -c "import urllib.request; print(urllib.request.urlopen('http://localhost:8181/health').read())"

# Check network connectivity
docker exec Archon-Server ping -c 1 supabase_kong
```

### 5. Supabase Not Accessible

**Symptoms:**
- Can't connect to Supabase from Archon
- API calls timeout

**Debugging:**
```bash
# Find Supabase container name and network
docker ps | grep supabase
docker inspect [supabase_container] | grep NetworkMode

# Test connectivity from host
curl http://localhost:54321/rest/v1/

# Test from Archon container
docker exec Archon-Server curl http://host.docker.internal:54321/rest/v1/
```

### 6. Frontend Can't Connect to Backend

**Symptoms:**
- UI loads but API calls fail
- CORS errors in browser console

**Solution:**
```yaml
# docker-compose.yml - Ensure frontend knows external port
environment:
- VITE_API_URL=http://localhost:${ARCHON_SERVER_PORT:-8181}
```
Comment on lines +127 to +130
Copy link
Copy Markdown

@coderabbitai coderabbitai Bot Aug 22, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🛠️ Refactor suggestion

Align VITE_API_URL default with the new external server port default (9282).

Else, the UI will point at 8181 while archon-server listens on 9282 by default.

-  - VITE_API_URL=http://localhost:${ARCHON_SERVER_PORT:-8181}
+  - VITE_API_URL=http://localhost:${ARCHON_SERVER_PORT:-9282}
🤖 Prompt for AI Agents 
In DEPLOYMENT_TROUBLESHOOTING.md around lines 127 to 130, the VITE_API_URL
default in the docker-compose example still points to port 8181 while the server
default was changed to 9282; update the example so the environment line uses
VITE_API_URL=http://localhost:${ARCHON_SERVER_PORT:-9282} (or otherwise document
9282 as the external port) to keep the frontend default aligned with the new
server port.


### 7. Database Migration Issues

**Symptoms:**
- Tables don't exist errors
- Missing functions or procedures

**Solution:**
```sql
-- Run in Supabase SQL Editor
-- 1. First check if tables exist
SELECT tablename FROM pg_tables WHERE schemaname = 'public' AND tablename LIKE 'archon_%';

-- 2. If missing, run migration
-- Execute contents of migration/complete_setup.sql

-- 3. If partial, reset and retry
-- Execute contents of migration/RESET_DB.sql
-- Then migration/complete_setup.sql
```

## Platform-Specific Issues

### Linux (Ubuntu/Debian)
- `host.docker.internal` doesn't work by default
- Use `host-gateway` or Docker bridge IP (172.17.0.1)
- May need to configure firewall for Docker

### macOS
- `host.docker.internal` works out of the box
- Resource limits may need adjustment in Docker Desktop
- File sharing permissions in Docker Desktop settings

### Windows (WSL2)
- Ensure WSL2 backend is enabled in Docker Desktop
- `host.docker.internal` works but may have firewall issues
- Check Windows Defender firewall rules

## Quick Diagnostic Commands

```bash
# Check all Archon services
docker compose ps

# Check port availability
netstat -tuln | grep -E "8181|8051|8052|3737"

# Test service health
curl http://localhost:${ARCHON_SERVER_PORT:-8181}/health
curl http://localhost:${ARCHON_AGENTS_PORT:-8052}/health

Comment on lines +175 to +181
Copy link
Copy Markdown

@coderabbitai coderabbitai Bot Aug 22, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🛠️ Refactor suggestion

Update “port availability” and health test commands to the new external defaults.

The earlier ports (8181/8051/8052) are internal container ports; externally you mapped to 9282/9151/9152. Keep UI at 3737 unless you change compose.

-# Check port availability
-netstat -tuln | grep -E "8181|8051|8052|3737"
+# Check port availability (external host ports)
+ss -tulpen | rg -nP '(?<=:)(9282|9151|9152|3737)\b'
 
 # Test service health
-curl http://localhost:${ARCHON_SERVER_PORT:-8181}/health
-curl http://localhost:${ARCHON_AGENTS_PORT:-8052}/health
+curl http://localhost:${ARCHON_SERVER_PORT:-9282}/health
+curl http://localhost:${ARCHON_AGENTS_PORT:-9152}/health
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
# Check port availability
netstat -tuln | grep -E "8181|8051|8052|3737"
# Test service health
curl http://localhost:${ARCHON_SERVER_PORT:-8181}/health
curl http://localhost:${ARCHON_AGENTS_PORT:-8052}/health
# Check port availability (external host ports)
ss -tulpen | rg -nP '(?<=:)(9282|9151|9152|3737)\b'
# Test service health
curl http://localhost:${ARCHON_SERVER_PORT:-9282}/health
curl http://localhost:${ARCHON_AGENTS_PORT:-9152}/health
🤖 Prompt for AI Agents 
In DEPLOYMENT_TROUBLESHOOTING.md around lines 175 to 181, the port availability
and health test commands still reference internal container ports
(8181/8051/8052); update them to the external mapped defaults 9282 (server),
9151 (agents health port mapping for services previously 8051/8052) while
keeping the UI port at 3737 unless docker-compose was changed, and update the
netstat and curl examples to use 9282/9151/9152 and 3737 accordingly so the docs
match the external port mappings.

# View real-time logs
docker compose logs -f

# Restart everything
docker compose down && docker compose up -d

# Full reset
docker compose down -v # Warning: removes volumes
docker compose up --build -d
```

## Environment Variable Reference

```bash
# Required
SUPABASE_URL= # Your Supabase instance URL
SUPABASE_SERVICE_KEY= # Service role key (not anon key)

# Optional - Ports (defaults shown)
ARCHON_SERVER_PORT=8181
ARCHON_MCP_PORT=8051
ARCHON_AGENTS_PORT=8052
ARCHON_UI_PORT=3737

# Optional - Services
OPENAI_API_KEY= # For OpenAI models
OLLAMA_HOST= # For local Ollama
LOG_LEVEL=INFO # DEBUG for more details
```
Comment on lines +195 to +210
Copy link
Copy Markdown

@coderabbitai coderabbitai Bot Aug 22, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🛠️ Refactor suggestion

Environment variable defaults should reflect external port mappings.

These are presented as “defaults,” but your docker-compose maps external defaults to 9282/9151/9152 (UI remains 3737). Update to avoid operator mistakes.

 # Optional - Ports (defaults shown)
-ARCHON_SERVER_PORT=8181
-ARCHON_MCP_PORT=8051
-ARCHON_AGENTS_PORT=8052
-ARCHON_UI_PORT=3737
+ARCHON_SERVER_PORT=9282
+ARCHON_MCP_PORT=9151
+ARCHON_AGENTS_PORT=9152
+ARCHON_UI_PORT=3737
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
```bash
# Required
SUPABASE_URL= # Your Supabase instance URL
SUPABASE_SERVICE_KEY= # Service role key (not anon key)
# Optional - Ports (defaults shown)
ARCHON_SERVER_PORT=8181
ARCHON_MCP_PORT=8051
ARCHON_AGENTS_PORT=8052
ARCHON_UI_PORT=3737
# Optional - Services
OPENAI_API_KEY= # For OpenAI models
OLLAMA_HOST= # For local Ollama
LOG_LEVEL=INFO # DEBUG for more details
```
🤖 Prompt for AI Agents 
In DEPLOYMENT_TROUBLESHOOTING.md around lines 195 to 210, the listed “defaults”
for ARCHON_SERVER_PORT, ARCHON_MCP_PORT and ARCHON_AGENTS_PORT currently show
internal container ports but your docker-compose exposes external ports 9282,
9151 and 9152; update the documented defaults to reflect the external mappings
(ARCHON_SERVER_PORT=9282, ARCHON_MCP_PORT=9151, ARCHON_AGENTS_PORT=9152) while
keeping ARCHON_UI_PORT=3737 and add a brief parenthetical note that these are
external host ports mapped to container ports to avoid operator confusion.


## Getting Help

1. Check logs first: `docker compose logs [service-name]`
2. Verify network: `docker network ls` and `docker network inspect`
3. Test connectivity: Use curl or docker exec to test endpoints
4. Check resource usage: `docker stats`
5. Search existing issues on GitHub
6. Create new issue with:
- Docker version: `docker --version`
- OS and version
- Full error logs
- docker-compose.yml (sanitized)
- .env (without secrets)

## Common Fixes Summary

| Problem | Quick Fix |
|---------|-----------|
| Connection timeout | Use shared network or bridge IP |
| Port conflict | Change external ports in .env |
| DOCKER_HOST error | Run: `unset DOCKER_HOST` |
| Unhealthy container | Check logs, verify network |
| Frontend API errors | Update VITE_API_URL |
| Database errors | Run migrations |

---

*Remember: Most issues are network-related. When in doubt, check network configuration first!*
Loading