code-server/cursor-fullstack/SETUP.md

Cursor Full Stack AI IDE - Setup Guide

🚀 Quick Start

Prerequisites

• Docker and Docker Compose installed
• Git installed
• At least 4GB RAM available
• Ports 3001, 5173, 8080, 8081 available

Installation

1. Clone and Navigate

git clone <repository-url>
cd cursor-fullstack

2. Build and Start

# Option 1: Using npm scripts
npm run build

# Option 2: Using Docker Compose directly
docker compose up --build -d

# Option 3: Using the build script
./build.sh

3. Verify Installation

# Check if all services are running
docker compose ps

# Test the system
npm test

Access Points

• Frontend: http://localhost:5173
• Backend API: http://localhost:3001
• WebSocket: ws://localhost:8080
• code-server IDE: http://localhost:8081

🔧 Configuration

1. AI Provider Setup

1. Open http://localhost:5173
2. Click "AI Settings" in the sidebar
3. Select your preferred provider:
   • OpenAI: Get API key from https://platform.openai.com/api-keys
   • Anthropic: Get API key from https://console.anthropic.com/
   • Google: Get API key from https://makersuite.google.com/app/apikey
   • Mistral: Get API key from https://console.mistral.ai/
4. Enter your API key and test the connection

2. Workspace Setup

The workspace is located at ./workspace/ and is shared between all services.

3. Environment Variables

Create a .env file for custom configuration:

# Backend
NODE_ENV=production
PORT=3001
WS_PORT=8080

# Frontend
VITE_BACKEND_URL=http://localhost:3001
VITE_WS_URL=ws://localhost:8080

# code-server
CODE_SERVER_PASSWORD=your_secure_password

🛠️ Development

Local Development

# Backend development
npm run dev:backend

# Frontend development
npm run dev:frontend

Adding New Tools

1. Add tool definition in packages/backend/claudable/src/tools/index.ts
2. Add tool implementation in the ToolManager class
3. Update the tool list in the API endpoint
4. Test the tool using the frontend tool panel

Adding New AI Providers

1. Add provider implementation in packages/backend/claudable/src/ai/providers.ts
2. Update the providers list in the API endpoint
3. Add provider option in the frontend provider form

🐛 Troubleshooting

Common Issues

1. Port Already in Use

# Check what's using the port
lsof -i :3001
lsof -i :5173
lsof -i :8080
lsof -i :8081

# Kill the process or change ports in docker-compose.yml

2. Docker Build Fails

# Clean Docker cache
docker system prune -f
docker compose down -v
docker compose up --build -d

3. WebSocket Connection Issues

• Check if ports 8080 and 3001 are accessible
• Verify firewall settings
• Check browser console for errors

4. AI Provider Errors

• Verify API key is correct
• Check API key permissions
• Ensure sufficient API credits

Logs

# View all logs
npm run logs

# View specific service logs
docker compose logs -f backend
docker compose logs -f frontend
docker compose logs -f code-server

Reset Everything

# Stop and remove all containers, volumes, and networks
npm run clean

# Rebuild from scratch
npm run build

📊 Monitoring

Health Checks

# Check service status
curl http://localhost:3001/api/providers
curl http://localhost:5173
curl http://localhost:8081

# Check WebSocket
wscat -c ws://localhost:8080

Performance Monitoring

• Monitor Docker container resource usage
• Check WebSocket connection stability
• Monitor AI API response times

🚀 Production Deployment

Using Production Docker Compose

docker compose -f docker-compose.prod.yml up -d

Environment Setup

1. Set up reverse proxy (Nginx)
2. Configure SSL certificates
3. Set up domain names
4. Configure environment variables
5. Set up monitoring and logging

Scaling

• Use multiple backend instances
• Set up load balancer
• Add database for persistence
• Implement Redis for session management

📚 API Documentation

Backend Endpoints

• GET /api/providers - List AI providers
• POST /api/chat - Send chat message
• GET /api/tools - List available tools
• POST /api/tools/execute - Execute tool
• GET /api/workspace/files - List workspace files
• GET /api/workspace/file/:path - Read file
• POST /api/workspace/file/:path - Write file

WebSocket Events

• chat-message - Send message
• chat-response - Receive response
• typing-start/stop - Typing indicators

🔒 Security

Best Practices

• Use strong passwords for code-server
• Keep API keys secure
• Regularly update dependencies
• Use HTTPS in production
• Implement rate limiting
• Monitor for suspicious activity

API Key Management

• Store API keys in environment variables
• Never commit API keys to version control
• Rotate API keys regularly
• Use different keys for different environments

📞 Support

Getting Help

1. Check this setup guide
2. Review the README.md
3. Check GitHub issues
4. Create a new issue with detailed information

Reporting Issues

When reporting issues, include:

• Operating system and version
• Docker version
• Error messages and logs
• Steps to reproduce
• Expected vs actual behavior

---

Happy Coding with AI! 🚀