Skip to main content

Deployment

Quick Start​

Prerequisites
  • Docker and Docker Compose installed
  • Supabase account (free tier works)
  • Git for cloning the repository

1. Clone & Setup​

# Clone repository
git clone <repository-url>
cd archon

# Create environment file
cp .env.example .env

2. Configure​

Edit .env with your credentials:

SUPABASE_URL=https://your-project.supabase.co
SUPABASE_SERVICE_KEY=eyJ0eXAi...

3. Launch​

# Start all services
docker-compose up -d

# Check status
docker-compose ps

4. Access​

Hot Module Reload (HMR)​

Built-in Hot Reload

Archon automatically includes Hot Module Reload for both Python server and React UI. Code changes are reflected immediately without container rebuilds.

What Changes Without Rebuild​

✅ No Rebuild Required:

  • Python source code changes (.py files)
  • Configuration changes in code
  • Business logic updates
  • API endpoint modifications
  • Socket.IO event handlers
  • Service layer changes

❌ Rebuild Required:

  • New pip dependencies in requirements.*.txt
  • System package installations
  • Dockerfile modifications
  • Environment variable changes in docker-compose

How HMR Works​

Python Server:

  • Uses uvicorn --reload
  • Watches file changes automatically
  • Restarts on save
  • WebSocket connections re-establish after reload

React UI:

  • Vite's built-in HMR
  • Component state preserved when possible
  • CSS updates without page reload
  • Fast refresh for React components

Tips​

  1. Monitor Logs: Watch for reload messages

    docker logs -f Archon-Server

  2. Handle Disconnects: The UI shows a disconnect screen during server reload

  3. State Persistence: Server state resets on reload, but database state persists

MCP Service Note

The MCP service doesn't support hot reload. Restart manually after changes:

docker-compose restart archon-mcp

Service Architecture​

Common Commands​

# Start services
docker-compose up -d

# Stop services
docker-compose down

# View logs
docker-compose logs -f

# Restart a service
docker-compose restart archon-frontend

Advanced Configuration​

Scaling Archon

For team deployments, consider:

  • Using a reverse proxy (nginx/Caddy) for multiple users
  • Setting up SSL certificates for secure connections
  • Configuring resource limits based on usage
  • Using managed Supabase instances

Database Management​

Reset Database​

Data Loss Warning

This will delete ALL data in your database!

-- Run in Supabase SQL editor
-- migration/RESET_DB.sql

Backup Data​

# Export data before reset
pg_dump -h your-db-host -U postgres -d postgres > backup.sql

Monitoring​

Health Checks​

# API Health
curl http://localhost:8080/health

# Check all services
echo "Frontend: http://localhost:3737"
curl -s http://localhost:3737 > /dev/null && echo "✓ Running" || echo "✗ Not running"

echo "API: http://localhost:8080/health"
curl -s http://localhost:8080/health | jq '.status' || echo "✗ Not running"

echo "MCP: http://localhost:8051/sse"
curl -s http://localhost:8051/sse > /dev/null && echo "✓ Running" || echo "✗ Not running"

echo "Agents: http://localhost:8052/health"
curl -s http://localhost:8052/health | jq '.status' || echo "✗ Not running"

Container Resources​

# View resource usage
docker stats

# Check disk usage
docker system df

Next Steps​

Ready to Go!

Your Archon instance is now running. Next:

  1. Set up API keys in Settings
  2. Configure MCP for AI agents
  3. Start crawling knowledge sources
  4. Create projects and tasks