first commit
This commit is contained in:
@@ -0,0 +1,204 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user