205 lines
4.3 KiB
Markdown
205 lines
4.3 KiB
Markdown
# Reason Flow Setup Guide
|
|
|
|
This guide will help you set up the Reason Flow AI engineering reasoning system.
|
|
|
|
## Prerequisites
|
|
|
|
- Node.js (v16 or higher)
|
|
- PostgreSQL (v12 or higher)
|
|
- Git
|
|
|
|
## Quick Start
|
|
|
|
### 1. Clone and Install Dependencies
|
|
|
|
```bash
|
|
git clone <repository-url>
|
|
cd reason_flow
|
|
npm run install-all
|
|
```
|
|
|
|
### 2. Environment Configuration
|
|
|
|
#### Option A: Interactive Setup (Recommended)
|
|
```bash
|
|
npm run env:setup
|
|
```
|
|
|
|
#### Option B: Manual Setup
|
|
```bash
|
|
cp env.example .env
|
|
# Edit .env with your configuration
|
|
```
|
|
|
|
### 3. Database Setup
|
|
|
|
```bash
|
|
npm run db:setup
|
|
```
|
|
|
|
### 4. Validate Configuration
|
|
|
|
```bash
|
|
npm run config:validate
|
|
```
|
|
|
|
### 5. Start Development Server
|
|
|
|
```bash
|
|
npm run dev
|
|
```
|
|
|
|
## Detailed Setup
|
|
|
|
### Environment Variables
|
|
|
|
The system uses environment variables for configuration. Key variables include:
|
|
|
|
#### Required Variables
|
|
- `GROQ_API_KEY` - Your Groq API key for Kimi K2 model
|
|
- `DB_PASSWORD` - PostgreSQL database password
|
|
- `JWT_SECRET` - Secret key for JWT tokens
|
|
|
|
#### Optional Variables
|
|
- `OPENAI_API_KEY` - For additional AI capabilities
|
|
- `SERP_API_KEY` - For web search functionality
|
|
- `REDIS_URL` - For caching (optional)
|
|
|
|
### Database Configuration
|
|
|
|
The system supports multiple environments:
|
|
|
|
- **Development**: `reason_flow_dev`
|
|
- **Test**: `reason_flow_test`
|
|
- **Production**: `reason_flow_prod`
|
|
|
|
### API Keys Setup
|
|
|
|
1. **Groq API Key**: Get from [Groq Console](https://console.groq.com/)
|
|
2. **OpenAI API Key**: Get from [OpenAI Platform](https://platform.openai.com/)
|
|
3. **SERP API Key**: Get from [SERP API](https://serpapi.com/)
|
|
|
|
## Available Scripts
|
|
|
|
### Environment Management
|
|
- `npm run env:setup` - Interactive environment setup
|
|
- `npm run env:validate` - Validate environment configuration
|
|
- `npm run env:show` - Show current configuration
|
|
|
|
### Database Management
|
|
- `npm run db:setup` - Complete database setup
|
|
- `npm run db:init` - Initialize database
|
|
- `npm run db:reset` - Reset database
|
|
- `npm run db:migrate` - Run migrations
|
|
- `npm run db:seed` - Run seeders
|
|
- `npm run db:status` - Check database status
|
|
- `npm run db:info` - Show database information
|
|
|
|
### Development
|
|
- `npm run dev` - Start development server
|
|
- `npm run dev-full` - Start both backend and frontend
|
|
- `npm run test:groq` - Test Groq API integration
|
|
|
|
### Configuration
|
|
- `npm run config:validate` - Validate all configuration
|
|
- `npm run config:show` - Show current configuration
|
|
|
|
## Environment-Specific Configuration
|
|
|
|
### Development
|
|
- Debug mode enabled
|
|
- Verbose logging
|
|
- Relaxed rate limiting
|
|
- Hot reload enabled
|
|
|
|
### Production
|
|
- Debug mode disabled
|
|
- Optimized logging
|
|
- Strict rate limiting
|
|
- SSL recommended
|
|
- Security headers enabled
|
|
|
|
### Test
|
|
- Minimal logging
|
|
- Test database
|
|
- Mock external services
|
|
|
|
## Troubleshooting
|
|
|
|
### Common Issues
|
|
|
|
1. **Database Connection Failed**
|
|
- Check PostgreSQL is running
|
|
- Verify database credentials
|
|
- Ensure database exists
|
|
|
|
2. **Groq API Errors**
|
|
- Verify API key is correct
|
|
- Check API quota and limits
|
|
- Test connection: `npm run test:groq`
|
|
|
|
3. **Configuration Errors**
|
|
- Run: `npm run config:validate`
|
|
- Check required variables are set
|
|
- Verify environment file exists
|
|
|
|
### Logs
|
|
|
|
- Application logs: `./logs/app.log`
|
|
- Error logs: `./logs/error.log`
|
|
- Combined logs: `./logs/combined.log`
|
|
|
|
### Health Checks
|
|
|
|
- API Health: `GET /api/health`
|
|
- Model Status: `GET /api/models/status`
|
|
- Database Status: `npm run db:status`
|
|
|
|
## Security Considerations
|
|
|
|
### Production Deployment
|
|
|
|
1. **Change Default Secrets**
|
|
- Update JWT_SECRET
|
|
- Change admin password
|
|
- Use strong database passwords
|
|
|
|
2. **Enable SSL**
|
|
- Set DB_SSL=true
|
|
- Use HTTPS in production
|
|
- Configure proper CORS origins
|
|
|
|
3. **Environment Variables**
|
|
- Never commit .env files
|
|
- Use secure secret management
|
|
- Rotate keys regularly
|
|
|
|
## Monitoring
|
|
|
|
### Health Endpoints
|
|
- `/api/health` - Basic health check
|
|
- `/api/models/status` - Model status
|
|
- `/api/feedback/stats` - Feedback statistics
|
|
|
|
### Logging
|
|
- Structured JSON logging
|
|
- Log rotation configured
|
|
- Error tracking enabled
|
|
|
|
## Support
|
|
|
|
For issues and questions:
|
|
1. Check the logs for errors
|
|
2. Validate configuration
|
|
3. Test individual components
|
|
4. Review the troubleshooting section
|
|
|
|
## Next Steps
|
|
|
|
After setup:
|
|
1. Test the API endpoints
|
|
2. Upload sample documents
|
|
3. Create test conversations
|
|
4. Verify model responses
|
|
5. Set up monitoring
|