Add comprehensive getting started guide
This commit is contained in:
469
docs/GETTING_STARTED.md
Normal file
469
docs/GETTING_STARTED.md
Normal file
@@ -0,0 +1,469 @@
|
||||
# 🚀 Getting Started with Chat Switchboard
|
||||
|
||||
## What is Chat Switchboard?
|
||||
|
||||
Chat Switchboard is a **plugin-first, multi-model AI platform** that works in two modes:
|
||||
|
||||
- **🏠 Unmanaged Mode:** Runs entirely in your browser (like the current version)
|
||||
- **🌐 Managed Mode:** Full backend with collaboration, workflows, and advanced features
|
||||
|
||||
## Quick Start (Unmanaged Mode)
|
||||
|
||||
### 1. Download & Run
|
||||
|
||||
```bash
|
||||
# Clone the repo
|
||||
git clone https://git.gobha.me/xcaliber/chat-switchboard.git
|
||||
cd chat-switchboard
|
||||
|
||||
# Build standalone version
|
||||
./build.sh
|
||||
|
||||
# Open in browser
|
||||
xdg-open standalone/index.html
|
||||
# or serve it
|
||||
python3 -m http.server 8080 --directory standalone
|
||||
```
|
||||
|
||||
### 2. Configure Your API
|
||||
|
||||
1. Click ⚙️ Settings
|
||||
2. Enter your API details:
|
||||
- **API Endpoint:** `https://api.openai.com/v1` (or OpenRouter, Venice.ai, etc.)
|
||||
- **API Key:** Your API key
|
||||
- **Model:** Select or type model name
|
||||
3. Click "Save Settings"
|
||||
|
||||
### 3. Start Chatting
|
||||
|
||||
- Type a message and press Enter
|
||||
- Switch models per-chat using the dropdown
|
||||
- Export conversations as Markdown/JSON
|
||||
|
||||
**That's it!** No backend needed, all data stays in your browser.
|
||||
|
||||
---
|
||||
|
||||
## Full Installation (Managed Mode)
|
||||
|
||||
For teams, collaboration, and advanced features like Workflows and Channels.
|
||||
|
||||
### Prerequisites
|
||||
|
||||
- Docker & Docker Compose
|
||||
- PostgreSQL 15+
|
||||
- Go 1.21+ (for development)
|
||||
- Python 3.9+ (for AI extensions)
|
||||
|
||||
### 1. Clone & Configure
|
||||
|
||||
```bash
|
||||
git clone https://git.gobha.me/xcaliber/chat-switchboard.git
|
||||
cd chat-switchboard
|
||||
|
||||
# Copy environment template
|
||||
cp .env.example .env
|
||||
|
||||
# Edit configuration
|
||||
nano .env
|
||||
```
|
||||
|
||||
```bash
|
||||
# .env
|
||||
DATABASE_URL=postgres://user:pass@localhost:5432/chatswitch
|
||||
JWT_SECRET=your-secret-key-here
|
||||
PORT=8080
|
||||
FRONTEND_URL=http://localhost:3000
|
||||
REDIS_URL=redis://localhost:6379
|
||||
```
|
||||
|
||||
### 2. Start Services
|
||||
|
||||
```bash
|
||||
# Start everything with Docker Compose
|
||||
docker-compose up -d
|
||||
|
||||
# Services:
|
||||
# - PostgreSQL (5432)
|
||||
# - Backend API (8080)
|
||||
# - Redis (6379)
|
||||
# - Frontend (3000)
|
||||
```
|
||||
|
||||
### 3. Run Migrations
|
||||
|
||||
```bash
|
||||
# Apply database schema
|
||||
docker-compose exec backend ./migrate up
|
||||
```
|
||||
|
||||
### 4. Create Admin User
|
||||
|
||||
```bash
|
||||
curl -X POST http://localhost:8080/api/auth/register \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"username": "admin",
|
||||
"email": "admin@example.com",
|
||||
"password": "secure-password",
|
||||
"role": "admin"
|
||||
}'
|
||||
```
|
||||
|
||||
### 5. Access Frontend
|
||||
|
||||
Open http://localhost:3000
|
||||
|
||||
1. Click "Connect to Backend"
|
||||
2. Enter backend URL: `http://localhost:8080`
|
||||
3. Login with your credentials
|
||||
|
||||
---
|
||||
|
||||
## Architecture Overview
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────┐
|
||||
│ Frontend (Vanilla JS) │
|
||||
│ - Manages UI state │
|
||||
│ - Switches modes (managed/local) │
|
||||
└─────────────┬───────────────────────┘
|
||||
│
|
||||
┌─────────┴─────────┐
|
||||
│ │
|
||||
[LocalStorage] [Backend API]
|
||||
│ │
|
||||
│ ┌─────────▼──────────┐
|
||||
│ │ Go Core │
|
||||
│ │ - Auth │
|
||||
│ │ - WebSocket │
|
||||
│ │ - Extension Mgr │
|
||||
│ └─────────┬──────────┘
|
||||
│ │
|
||||
│ ┌─────────┴──────────┐
|
||||
│ │ PostgreSQL │
|
||||
│ │ - Users, chats │
|
||||
│ │ - Channels, notes │
|
||||
│ │ - Vector search │
|
||||
│ └────────────────────┘
|
||||
│
|
||||
└─── Extensions (Python/Go) ───┐
|
||||
├─ Chat Engine │
|
||||
├─ RAG Engine │
|
||||
├─ Workflows │
|
||||
└─ Custom Tools │
|
||||
```
|
||||
|
||||
## Core Features
|
||||
|
||||
### 1. Chat (User → AI)
|
||||
|
||||
**Available in:** Both modes
|
||||
|
||||
- Multi-model support (OpenAI, Anthropic, Ollama, etc.)
|
||||
- Per-conversation model switching
|
||||
- Streaming responses
|
||||
- Message history
|
||||
- Export (Markdown, JSON, Plain Text)
|
||||
|
||||
**Managed mode additions:**
|
||||
- Auto-routing (smart model selection)
|
||||
- Cost tracking
|
||||
- Shared conversations
|
||||
- Server-side tool calling
|
||||
|
||||
### 2. Channels (User → User + AI)
|
||||
|
||||
**Available in:** Managed mode only
|
||||
|
||||
Multi-user chat rooms with AI participants:
|
||||
|
||||
```
|
||||
#general
|
||||
@alice: What do you think about this design?
|
||||
@claude: I'd suggest using a darker color scheme...
|
||||
@bob: Agreed! Also, @gpt4 can you review the code?
|
||||
@gpt4: I see a potential issue in line 42...
|
||||
```
|
||||
|
||||
- Public/private/DM channels
|
||||
- @mention users and AI models
|
||||
- Threaded conversations
|
||||
- Real-time updates (WebSocket)
|
||||
- Reactions and formatting
|
||||
|
||||
### 3. Notes & Knowledge Bases
|
||||
|
||||
**Available in:** Both modes (limited in unmanaged)
|
||||
|
||||
- Markdown notes with folders
|
||||
- Tagging and search
|
||||
- Linked notes (wiki-style)
|
||||
|
||||
**Managed mode additions:**
|
||||
- Shared notes
|
||||
- Knowledge base collections
|
||||
- RAG (vector search)
|
||||
- Semantic search with embeddings
|
||||
|
||||
### 4. Workflows 🌟 (UNIQUE FEATURE)
|
||||
|
||||
**Available in:** Managed mode only
|
||||
|
||||
Chain multiple AI models and tools into automated pipelines:
|
||||
|
||||
```
|
||||
[User Query] → [Web Search] → [GPT-4 Summarize]
|
||||
↓ ↓
|
||||
[Save to KB] [Claude Verify]
|
||||
↓
|
||||
[Generate Report]
|
||||
```
|
||||
|
||||
**Use cases:**
|
||||
- Research assistants
|
||||
- Code review pipelines
|
||||
- Content creation factories
|
||||
- Data processing
|
||||
- Multi-model consensus
|
||||
|
||||
See `docs/WORKFLOWS.md` for details.
|
||||
|
||||
## Extension System
|
||||
|
||||
### Frontend Extensions (Both Modes)
|
||||
|
||||
Simple JavaScript plugins that run in the browser:
|
||||
|
||||
```javascript
|
||||
// extensions/frontend/my-plugin/main.js
|
||||
window.ChatSwitchboard.registerExtension({
|
||||
name: 'my-plugin',
|
||||
hooks: {
|
||||
onMessageSend: (msg) => {
|
||||
console.log('Sending:', msg);
|
||||
return msg; // Can modify
|
||||
}
|
||||
}
|
||||
});
|
||||
```
|
||||
|
||||
### Backend Extensions (Managed Only)
|
||||
|
||||
Full-featured plugins in any language:
|
||||
|
||||
```python
|
||||
# extensions/backend/my-tool/main.py
|
||||
from fastapi import FastAPI
|
||||
|
||||
app = FastAPI()
|
||||
|
||||
@app.post("/tools/my_tool")
|
||||
async def my_tool(input: str):
|
||||
result = process(input)
|
||||
return {"result": result}
|
||||
```
|
||||
|
||||
See `docs/PLUGIN_SPEC.md` for complete guide.
|
||||
|
||||
## Development
|
||||
|
||||
### Frontend Development
|
||||
|
||||
```bash
|
||||
# Serve source files
|
||||
python3 -m http.server 8080 --directory src
|
||||
|
||||
# Build standalone
|
||||
./build.sh
|
||||
```
|
||||
|
||||
### Backend Development
|
||||
|
||||
```bash
|
||||
# Install Go dependencies
|
||||
go mod download
|
||||
|
||||
# Run backend
|
||||
go run server/main.go
|
||||
|
||||
# Or with air (hot reload)
|
||||
air
|
||||
```
|
||||
|
||||
### Extension Development
|
||||
|
||||
```bash
|
||||
# Create from template
|
||||
cp -r extensions/_template-python extensions/my-extension
|
||||
|
||||
# Edit files
|
||||
cd extensions/my-extension
|
||||
nano extension.json
|
||||
nano main.py
|
||||
|
||||
# Test locally
|
||||
python main.py
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
### Frontend Settings
|
||||
|
||||
Stored in localStorage (unmanaged) or user profile (managed):
|
||||
|
||||
- API endpoints and keys
|
||||
- Default model
|
||||
- Stream responses
|
||||
- System prompt
|
||||
- Temperature, max tokens, etc.
|
||||
|
||||
### Backend Configuration
|
||||
|
||||
```yaml
|
||||
# config.yaml
|
||||
server:
|
||||
port: 8080
|
||||
host: 0.0.0.0
|
||||
|
||||
database:
|
||||
url: ${DATABASE_URL}
|
||||
max_connections: 20
|
||||
|
||||
redis:
|
||||
url: ${REDIS_URL}
|
||||
enabled: true
|
||||
|
||||
extensions:
|
||||
directory: ./extensions/backend
|
||||
auto_load: true
|
||||
|
||||
security:
|
||||
jwt_secret: ${JWT_SECRET}
|
||||
jwt_expiry: 24h
|
||||
rate_limit: 100/minute
|
||||
```
|
||||
|
||||
## Switching Modes
|
||||
|
||||
### From Unmanaged → Managed
|
||||
|
||||
1. Deploy backend (see Full Installation above)
|
||||
2. In Settings, enter Backend URL
|
||||
3. Login/register
|
||||
4. Your local data will be **uploaded** on first sync
|
||||
|
||||
### From Managed → Unmanaged
|
||||
|
||||
1. Export your data (Settings → Export)
|
||||
2. Remove backend URL from settings
|
||||
3. Continue using locally
|
||||
|
||||
**Note:** Managed-only features (Channels, Workflows) won't work in unmanaged mode.
|
||||
|
||||
## Common Workflows
|
||||
|
||||
### Personal Use (Unmanaged)
|
||||
```
|
||||
Open standalone/index.html → Configure API → Chat
|
||||
```
|
||||
|
||||
### Team Collaboration (Managed)
|
||||
```
|
||||
Deploy backend → Create team channels → @mention AI models
|
||||
```
|
||||
|
||||
### Development (Contributing)
|
||||
```
|
||||
Fork repo → Create extension → Test locally → Submit PR
|
||||
```
|
||||
|
||||
### Self-Hosted (Privacy)
|
||||
```
|
||||
Deploy on your server → Configure domains → Invite team
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Frontend Issues
|
||||
|
||||
**"No settings found"**
|
||||
- Click Settings ⚙️ and configure API endpoint + key
|
||||
|
||||
**"API request failed"**
|
||||
- Check API endpoint URL (trailing slash?)
|
||||
- Verify API key is correct
|
||||
- Check browser console for errors
|
||||
|
||||
**"LocalStorage full"**
|
||||
- Export old chats
|
||||
- Delete unused chats
|
||||
- Clear browser data
|
||||
|
||||
### Backend Issues
|
||||
|
||||
**"Connection refused"**
|
||||
- Is backend running? `docker-compose ps`
|
||||
- Check firewall rules
|
||||
- Verify port 8080 is open
|
||||
|
||||
**"Database migration failed"**
|
||||
- Check PostgreSQL is running
|
||||
- Verify DATABASE_URL is correct
|
||||
- Run migrations manually: `./migrate up`
|
||||
|
||||
**"Extension not loading"**
|
||||
- Check extension.json is valid
|
||||
- Verify runtime is installed (python3, go, node)
|
||||
- Check logs: `docker-compose logs backend`
|
||||
|
||||
### WebSocket Issues
|
||||
|
||||
**"Real-time updates not working"**
|
||||
- Check WebSocket connection in browser console
|
||||
- Verify Redis is running (for multi-instance setups)
|
||||
- Check nginx WebSocket proxy config
|
||||
|
||||
## Next Steps
|
||||
|
||||
1. **Explore Features:** Try Chat, Notes, and (if managed) Channels
|
||||
2. **Read Docs:**
|
||||
- `docs/ARCHITECTURE.md` - System design
|
||||
- `docs/WORKFLOWS.md` - Workflow system
|
||||
- `docs/PLUGIN_SPEC.md` - Extension development
|
||||
3. **Build Extensions:** Use templates in `extensions/`
|
||||
4. **Join Community:** Discord, GitHub Discussions
|
||||
5. **Contribute:** Submit PRs, report bugs, suggest features
|
||||
|
||||
## Resources
|
||||
|
||||
- **GitHub:** https://git.gobha.me/xcaliber/chat-switchboard
|
||||
- **Documentation:** `/docs` directory
|
||||
- **Examples:** `/examples` directory
|
||||
- **Extensions:** `/extensions` directory
|
||||
|
||||
---
|
||||
|
||||
## FAQ
|
||||
|
||||
**Q: Is my data private?**
|
||||
A: In unmanaged mode, everything stays in your browser. In managed mode, you control the backend.
|
||||
|
||||
**Q: Can I use my own models?**
|
||||
A: Yes! Configure any OpenAI-compatible API (Ollama, LM Studio, etc.)
|
||||
|
||||
**Q: How do I migrate from ChatGPT/Claude?**
|
||||
A: Export your conversations, then import via our import tool (coming soon).
|
||||
|
||||
**Q: Can I run this offline?**
|
||||
A: Unmanaged mode works offline if you pre-load the page. For LLM calls, you need internet or local models (Ollama).
|
||||
|
||||
**Q: How much does it cost?**
|
||||
A: Chat Switchboard is free and open-source. You pay for API usage (OpenAI, etc.) or use free models (Ollama).
|
||||
|
||||
**Q: Can I sell extensions?**
|
||||
A: Yes! The marketplace (coming soon) will support paid extensions.
|
||||
|
||||
---
|
||||
|
||||
**Ready to switch? Start building! 🚀**
|
||||
Reference in New Issue
Block a user