Sankofa/docs/phoenix/CODESPACES_IDE_SETUP.md

# Phoenix Codespaces IDE - Setup Guide

## Overview

Phoenix Codespaces IDE is a branded cloud-based development environment that provides VS Code in the browser with powerful AI capabilities similar to GitHub Copilot, plus AI agents for automation and assistance.

## Features

- **VS Code in Browser**: Full VS Code experience via code-server
- **AI Code Completion**: Copilot-like code suggestions and autocomplete
- **AI Agents**: Automated code generation, testing, and documentation
- **Git Integration**: Seamless integration with Phoenix Git server
- **Multi-Language Support**: Python, TypeScript, Go, and more
- **Phoenix Branding**: Customized interface with Phoenix branding
- **Workspace Templates**: Pre-configured environments for common stacks
- **Terminal Access**: Full terminal access within the IDE

## Architecture

```
┌─────────────────────────────────────────┐
│         Phoenix Codespaces IDE          │
├─────────────────────────────────────────┤
│  ┌──────────────────────────────────┐  │
│  │   Code-Server (VS Code)          │  │
│  │   - Extensions                   │  │
│  │   - Workspaces                   │  │
│  │   - Terminal                     │  │
│  └──────────────────────────────────┘  │
│  ┌──────────────────────────────────┐  │
│  │   AI Integration Layer           │  │
│  │   - Copilot API                  │  │
│  │   - Code Completion              │  │
│  │   - Code Generation              │  │
│  └──────────────────────────────────┘  │
│  ┌──────────────────────────────────┐  │
│  │   AI Agents                      │  │
│  │   - LangChain                    │  │
│  │   - AutoGPT                      │  │
│  │   - Custom Phoenix Agents        │  │
│  └──────────────────────────────────┘  │
│  ┌──────────────────────────────────┐  │
│  │   Git Integration                │  │
│  │   - Phoenix Git Server           │  │
│  │   - Repository Access            │  │
│  └──────────────────────────────────┘  │
└─────────────────────────────────────────┘
```

## Initial Setup

### 1. Access the IDE

After VM deployment, access the IDE at:
- **URL**: `http://codespaces.sankofa.nexus` (after DNS configuration)
- **Direct IP**: `http://<VM_IP>:8080`
- **Default Password**: Set during first login (change immediately)

### 2. Change Default Password

```bash
# SSH into the VM
ssh admin@codespaces.sankofa.nexus

# Change code-server password
code-server --config /home/admin/.config/code-server/config.yaml
# Or edit the config file directly
nano /home/admin/.config/code-server/config.yaml
```

### 3. Configure SSL/TLS

```bash
# Install SSL certificate
sudo certbot --nginx -d codespaces.sankofa.nexus

# Update Nginx config to use HTTPS
sudo nano /etc/nginx/sites-available/phoenix-codespaces
```

## AI Integration Setup

### Option 1: GitHub Copilot Integration

1. **Get Copilot Token**:
   - Visit: https://github.com/settings/tokens
   - Create a personal access token with `copilot` scope

2. **Install Copilot Extension**:
   ```bash
   # Via code-server CLI
   code-server --install-extension GitHub.copilot
   code-server --install-extension GitHub.copilot-chat
   ```

3. **Authenticate**:
   - Open VS Code in browser
   - Go to Extensions → GitHub Copilot
   - Sign in with GitHub and authorize

### Option 2: Alternative AI Services

#### Tabby (Open Source)
```bash
# Install Tabby server
docker run -d \
  --name tabby \
  -p 8081:8080 \
  -v tabby-data:/data \
  tabbyml/tabby:latest

# Configure in VS Code
# Install Tabby extension
code-server --install-extension TabbyML.tabby
```

#### Codeium (Free Alternative)
```bash
# Install Codeium extension
code-server --install-extension Codeium.codeium
# Follow authentication in VS Code
```

#### Cursor (AI-First IDE)
```bash
# Install Cursor extension
code-server --install-extension cursor.cursor
```

### Option 3: Local AI Models

For sovereign AI without external APIs:

```bash
# Install Ollama (local LLM)
curl -fsSL https://ollama.ai/install.sh | sh

# Download models
ollama pull codellama
ollama pull deepseek-coder
ollama pull starcoder

# Configure VS Code extension
code-server --install-extension continue.continue
```

## AI Agents Setup

### LangChain Agent

1. **Install Dependencies**:
   ```bash
   pip3 install langchain openai anthropic
   pip3 install langchain-community langchain-core
   ```

2. **Create Agent Script**:
   ```python
   # /opt/phoenix-ide/agents/langchain_agent.py
   from langchain.agents import initialize_agent
   from langchain.llms import OpenAI
   
   llm = OpenAI(temperature=0)
   agent = initialize_agent(
       tools=[],
       llm=llm,
       agent="zero-shot-react-description"
   )
   ```

### AutoGPT Integration

```bash
# Clone AutoGPT
cd /opt/phoenix-ide/agents
git clone https://github.com/Significant-Gravitas/AutoGPT.git
cd AutoGPT
pip3 install -r requirements.txt

# Configure
cp .env.template .env
nano .env  # Add API keys
```

### Custom Phoenix AI Agent

Create a custom agent for Phoenix-specific tasks:

```python
# /opt/phoenix-ide/agents/phoenix_agent.py
class PhoenixAgent:
    def __init__(self):
        self.capabilities = [
            "code_generation",
            "code_review",
            "test_generation",
            "documentation",
            "deployment_automation"
        ]
    
    def generate_code(self, prompt, language):
        # Implement code generation
        pass
    
    def review_code(self, code):
        # Implement code review
        pass
```

## VS Code Extensions

### Essential Extensions

```bash
# Development
code-server --install-extension ms-python.python
code-server --install-extension ms-vscode.vscode-typescript-next
code-server --install-extension golang.go
code-server --install-extension ms-vscode.vscode-json

# Git
code-server --install-extension eamodio.gitlens
code-server --install-extension mhutchie.git-graph

# Docker
code-server --install-extension ms-azuretools.vscode-docker

# AI
code-server --install-extension GitHub.copilot
code-server --install-extension GitHub.copilot-chat

# Phoenix-specific
code-server --install-extension ms-kubernetes-tools.vscode-kubernetes-tools
code-server --install-extension redhat.vscode-yaml
```

## Git Integration

### Connect to Phoenix Git Server

1. **Configure Git**:
   ```bash
   git config --global user.name "Your Name"
   git config --global user.email "your.email@sankofa.nexus"
   ```

2. **Add Git Server**:
   ```bash
   # If using Gitea/GitLab
   git remote add phoenix https://git.sankofa.nexus/username/repo.git
   ```

3. **SSH Key Setup**:
   ```bash
   # Generate SSH key
   ssh-keygen -t ed25519 -C "your.email@sankofa.nexus"
   
   # Add to Git server
   cat ~/.ssh/id_ed25519.pub
   # Copy and add to Git server SSH keys
   ```

## Workspace Templates

### Node.js/TypeScript Template

```bash
# Create template
mkdir -p /opt/phoenix-ide/templates/nodejs-ts
cd /opt/phoenix-ide/templates/nodejs-ts

# Create template files
cat > package.json <<EOF
{
  "name": "phoenix-nodejs-template",
  "version": "1.0.0",
  "scripts": {
    "dev": "next dev",
    "build": "next build"
  }
}
EOF
```

### Python Template

```bash
mkdir -p /opt/phoenix-ide/templates/python
cd /opt/phoenix-ide/templates/python

cat > requirements.txt <<EOF
fastapi==0.104.1
uvicorn==0.24.0
pydantic==2.5.0
EOF
```

## Phoenix Branding

### Custom Theme

1. **Create Theme Extension**:
   ```bash
   mkdir -p ~/.local/share/code-server/extensions/phoenix-theme
   cd ~/.local/share/code-server/extensions/phoenix-theme
   ```

2. **Theme Configuration**:
   ```json
   {
     "name": "Phoenix Theme",
     "colors": {
       "editor.background": "#1a1a1a",
       "editor.foreground": "#e0e0e0"
     }
   }
   ```

### Custom Logo

Replace code-server logo:
```bash
# Find logo location
find /usr/lib/code-server -name "*.png" -o -name "*.svg"

# Replace with Phoenix logo
sudo cp /opt/phoenix-ide/branding/logo.png /usr/lib/code-server/resources/logo.png
```

## Multi-User Support

### User Isolation

```bash
# Create systemd service for each user
sudo systemctl edit code-server@user1.service
sudo systemctl edit code-server@user2.service

# Each user gets their own port and workspace
```

### Docker-Based Isolation

```bash
# Use Docker for complete isolation
docker run -d \
  --name codespaces-user1 \
  -p 8081:8080 \
  -v user1-workspace:/home/coder/workspace \
  codercom/code-server:latest
```

## Performance Optimization

### Resource Limits

```bash
# Set CPU limits
sudo systemctl edit code-server@admin
# Add:
[Service]
CPUQuota=400%
```

### Cache Configuration

```bash
# Increase Node.js cache
export NODE_OPTIONS="--max-old-space-size=4096"

# Docker cache
docker system prune -a --volumes
```

## Security

### Firewall Rules

```bash
# Only allow specific IPs
sudo ufw allow from 192.168.11.0/24 to any port 8080
sudo ufw deny 8080
```

### Authentication

```bash
# Use OAuth2 with Keycloak
# Configure in code-server config.yaml
auth: oauth2
oauth2:
  provider: keycloak
  client-id: phoenix-codespaces
  client-secret: <secret>
  auth-url: https://keycloak.sankofa.nexus/auth
```

## Monitoring

### Health Checks

```bash
# Check code-server status
systemctl status code-server@admin

# Check Nginx
systemctl status nginx

# Check AI agent status
ps aux | grep phoenix-ai-agent
```

### Logs

```bash
# Code-server logs
journalctl -u code-server@admin -f

# Nginx logs
tail -f /var/log/nginx/access.log
tail -f /var/log/nginx/error.log
```

## Troubleshooting

### Code-Server Won't Start

```bash
# Check config
code-server --config /home/admin/.config/code-server/config.yaml --check

# Check ports
sudo netstat -tulpn | grep 8080

# Check permissions
ls -la /home/admin/.config/code-server/
```

### AI Not Working

```bash
# Check API keys
echo $OPENAI_API_KEY
echo $GITHUB_TOKEN

# Test API connection
curl https://api.openai.com/v1/models -H "Authorization: Bearer $OPENAI_API_KEY"
```

### Extension Issues

```bash
# Reinstall extensions
code-server --uninstall-extension <extension-id>
code-server --install-extension <extension-id>

# Clear extension cache
rm -rf ~/.local/share/code-server/extensions/*
```

## Next Steps

1. ✅ Configure SSL/TLS certificates
2. ✅ Set up AI integration (Copilot or alternative)
3. ✅ Install essential VS Code extensions
4. ✅ Connect to Phoenix Git server
5. ✅ Create workspace templates
6. ✅ Configure Phoenix branding
7. ✅ Set up AI agents
8. ✅ Configure multi-user support (if needed)
9. ✅ Set up monitoring and alerts
10. ✅ Document custom configurations

---

**Last Updated**: 2025-12-08  
**Status**: Production Ready  
**Maintainer**: Phoenix DevOps Team