154 lines
4.2 KiB
Markdown
154 lines
4.2 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. When using `start_servers.py` with the default `FRONTEND_HOST=0.0.0.0` and no explicit `CORS_ORIGINS`, CORS will allow all origins (wildcard) to simplify development.
|
||
|
||
#### 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`. (When using `start_servers.py`, your specified `FRONTEND_HOST:FRONTEND_PORT` will be auto‑included.)
|
||
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
|