154 lines
4.0 KiB
Markdown
154 lines
4.0 KiB
Markdown
# Environment Configuration Guide
|
|
|
|
This guide explains how to configure the Chatterbox TTS application for different environments using environment variables.
|
|
|
|
## Quick Setup
|
|
|
|
1. **Run the setup script:**
|
|
```bash
|
|
python setup.py
|
|
```
|
|
|
|
2. **Install backend dependencies:**
|
|
```bash
|
|
cd backend
|
|
pip install -r requirements.txt
|
|
```
|
|
|
|
3. **Start the servers:**
|
|
```bash
|
|
# Terminal 1 - Backend
|
|
cd backend
|
|
python start_server.py
|
|
|
|
# Terminal 2 - Frontend
|
|
cd frontend
|
|
python start_dev_server.py
|
|
```
|
|
|
|
4. **Open the application:**
|
|
Open http://127.0.0.1:8001 in your browser
|
|
|
|
## Manual Configuration
|
|
|
|
### Environment Files
|
|
|
|
The application uses environment variables for configuration. Three `.env` files control different aspects:
|
|
|
|
- **Root `.env`**: Global configuration
|
|
- **`backend/.env`**: Backend-specific settings
|
|
- **`frontend/.env`**: Frontend-specific settings
|
|
|
|
### Key Configuration Options
|
|
|
|
#### Paths
|
|
- `PROJECT_ROOT`: Base directory for the project
|
|
- `SPEAKER_SAMPLES_DIR`: Directory containing speaker audio samples
|
|
- `TTS_TEMP_OUTPUT_DIR`: Temporary directory for TTS processing
|
|
- `DIALOG_GENERATED_DIR`: Directory for generated dialog audio files
|
|
|
|
#### Server Configuration
|
|
- `HOST`: Backend server host (default: 0.0.0.0)
|
|
- `PORT`: Backend server port (default: 8000)
|
|
- `RELOAD`: Enable auto-reload for development (default: true)
|
|
|
|
#### Frontend Configuration
|
|
- `VITE_API_BASE_URL`: Backend API base URL
|
|
- `VITE_DEV_SERVER_PORT`: Frontend development server port
|
|
- `VITE_DEV_SERVER_HOST`: Frontend development server host
|
|
|
|
#### CORS Configuration
|
|
- `CORS_ORIGINS`: Comma-separated list of allowed origins
|
|
|
|
#### Device Configuration
|
|
- `DEVICE`: Device for TTS model (auto, cpu, cuda, mps)
|
|
|
|
## Example Configurations
|
|
|
|
### Development Environment
|
|
```bash
|
|
# .env
|
|
PROJECT_ROOT=/Users/yourname/chatterbox-ui
|
|
BACKEND_PORT=8000
|
|
FRONTEND_PORT=8001
|
|
DEVICE=auto
|
|
CORS_ORIGINS=http://localhost:8001,http://127.0.0.1:8001
|
|
```
|
|
|
|
### Production Environment
|
|
```bash
|
|
# .env
|
|
PROJECT_ROOT=/opt/chatterbox-ui
|
|
BACKEND_HOST=0.0.0.0
|
|
BACKEND_PORT=8000
|
|
FRONTEND_PORT=3000
|
|
DEVICE=cuda
|
|
CORS_ORIGINS=https://yourdomain.com
|
|
```
|
|
|
|
### Docker Environment
|
|
```bash
|
|
# .env
|
|
PROJECT_ROOT=/app
|
|
BACKEND_HOST=0.0.0.0
|
|
BACKEND_PORT=8000
|
|
DEVICE=cpu
|
|
CORS_ORIGINS=http://localhost:3000
|
|
```
|
|
|
|
## Troubleshooting
|
|
|
|
### Common Issues
|
|
|
|
1. **Permission Errors**: Ensure the `PROJECT_ROOT` directory is writable
|
|
2. **CORS Errors**: Check that your frontend URL is in `CORS_ORIGINS`
|
|
3. **Model Loading Errors**: Verify `DEVICE` setting matches your hardware
|
|
4. **Path Errors**: Ensure all path variables point to existing, accessible directories
|
|
|
|
### Debugging
|
|
|
|
Enable debug logging by setting:
|
|
```bash
|
|
export PYTHONPATH="${PYTHONPATH}:$(pwd)"
|
|
export DEBUG=1
|
|
```
|
|
|
|
### Resetting Configuration
|
|
|
|
To reset to defaults:
|
|
```bash
|
|
rm .env backend/.env frontend/.env
|
|
python setup.py
|
|
```
|
|
|
|
## File Structure
|
|
|
|
```
|
|
chatterbox-ui/
|
|
├── .env # Global configuration
|
|
├── .env.example # Template for global config
|
|
├── setup.py # Automated setup script
|
|
├── backend/
|
|
│ ├── .env # Backend configuration
|
|
│ ├── .env.example # Template for backend config
|
|
│ ├── start_server.py # Backend startup script
|
|
│ └── app/
|
|
│ └── config.py # Configuration loader
|
|
├── frontend/
|
|
│ ├── .env # Frontend configuration
|
|
│ ├── .env.example # Template for frontend config
|
|
│ ├── start_dev_server.py # Frontend dev server
|
|
│ └── js/
|
|
│ └── config.js # Frontend configuration loader
|
|
└── speaker_data/
|
|
└── speaker_samples/ # Speaker audio files
|
|
```
|
|
|
|
## Security Notes
|
|
|
|
- Never commit `.env` files to version control
|
|
- Use strong, unique values for production
|
|
- Restrict CORS origins in production
|
|
- Use HTTPS in production environments
|
|
- Regularly update dependencies
|