llm-gateway/DEPLOYMENT-BRIDGES.md

# OpenAI Bridge Deployment Guide

## Overview
This document covers deploying the OpenAI Bridge service to Erik for ChatGPT/Codex integration.

## Architecture
- **openai-bridge** (Port 3251): HTTP wrapper around OpenAI CLI, provides OpenAI-compatible /v1/chat/completions endpoint
- **Integration**: Registered in `external-providers.ts` as fallback provider after Ollama and Claude
- **Authentication**: Uses OPENAI_API_KEY environment variable (OpenAI subscription required)

## Prerequisites on Erik
- OpenAI CLI tool: `openai` command available (homebrew: `brew install openai-cli`)
- Node.js 20+ installed
- PM2 process manager available
- /opt directory writable (for service deployment)
- /var/log/llm-gateway directory exists for logs

## Deployment Steps

### 1. Automatic Setup (Recommended)
The `ensure-bridges.sh` script handles automatic deployment:

```bash
# Run on Erik
cd /opt/llm-gateway
bash scripts/ensure-bridges.sh
```

This will:
- Create `/opt/openai-bridge` directory if missing
- Deploy `server.js` and `package.json`
- Create logs directory

### 2. Manual Setup (Alternative)
If automatic script fails, deploy manually:

```bash
# On Erik
mkdir -p /opt/openai-bridge /var/log/llm-gateway

# Copy openai-bridge files from repo
cp /opt/llm-gateway/openai-bridge/server.js /opt/openai-bridge/
cp /opt/llm-gateway/openai-bridge/package.json /opt/openai-bridge/
```

### 3. Configuration

#### Update ecosystem.config.cjs
Edit `/opt/llm-gateway/deploy/ecosystem.config.cjs`:

```javascript
env: {
  OPENAI_API_KEY: 'sk-proj-xxxxx...', // Your OpenAI subscription key
  OPENAI_BRIDGE_PORT: 3251,
  OPENAI_MODEL: 'gpt-4-turbo',
}
```

**Important**: Do NOT commit API keys to git. Use environment variables or .env files.

### 4. Deploy with PM2

```bash
# On Erik
cd /opt/llm-gateway
pm2 start deploy/ecosystem.config.cjs --update-env
```

This will start:
- `llm-gateway` (main service, port 3103)
- `openai-bridge` (ChatGPT bridge, port 3251)
- `llm-learning` (auto-learning engine)

### 5. Verification

```bash
# Check service status
pm2 status

# Health check
curl http://localhost:3251/health

# Sample request
curl -X POST http://localhost:3251/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4-turbo",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

# View logs
pm2 logs openai-bridge
```

## Environment Variables

| Variable | Required | Default | Notes |
|----------|----------|---------|-------|
| OPENAI_API_KEY | Yes | (empty) | OpenAI subscription API key |
| OPENAI_BRIDGE_PORT | No | 3251 | Service port |
| OPENAI_MODEL | No | gpt-4-turbo | Default model |
| OPENAI_BRIDGE_URL | Yes* | http://localhost:3251 | Set in ecosystem.config.cjs |

*Required in gateway's environment for proper routing

## Troubleshooting

### Bridge Service Won't Start
```bash
# Check if openai CLI is installed
which openai
openai --version

# Install if missing (requires homebrew)
brew install openai-cli
```

### Port 3251 Already in Use
```bash
# Find process using port
lsof -i :3251
# Kill process if needed
kill -9 <PID>
```

### OPENAI_API_KEY Not Configured
```bash
# Check environment
pm2 show openai-bridge | grep OPENAI_API_KEY

# Update if missing
pm2 set openai-bridge OPENAI_API_KEY "sk-proj-xxxxx..."
pm2 restart openai-bridge
```

### Health Check Fails
```bash
# Manual test of openai CLI
OPENAI_API_KEY="sk-proj-xxxxx..." openai api chat.completions.create \
  -m gpt-4-turbo \
  -g user "hello" \
  -t 0.3 \
  -M 100
```

## Integration with LLM Gateway

Once deployed, openai-bridge is automatically:
1. Registered in provider fallback chain (after claude-bridge, cerebras, groq, etc.)
2. Used when:
   - Ollama is unavailable
   - Request specifically targets "openai" or "chatgpt" provider
   - Confidence threshold requires higher-tier reasoning
3. Monitored for:
   - Rate limits (90 requests/min)
   - Response quality and latency
   - Error rates

## Rollback / Removal

```bash
# Stop openai-bridge service
pm2 stop openai-bridge
pm2 delete openai-bridge

# Remove service directory (keeps config for reinstall)
rm -rf /opt/openai-bridge

# Or keep for reinstall (without logs)
rm -rf /opt/openai-bridge/node_modules
```

## Next Steps

1. **Microsoft Copilot Integration**: Similar bridge pattern once CLI available
2. **Rate Limiting**: Implement adaptive rate limiting per provider
3. **Cost Tracking**: Monitor OpenAI API usage and costs
4. **Monitoring**: Add Prometheus metrics for bridge health

---

**Last Updated**: 2026-04-25  
**Status**: Ready for deployment