FASTAPI_SETUP_GUIDE.md

# FastAPI Server Setup Guide

This guide will help you set up and run the FastAPI server for the T2M (Text-to-Media) video generation system.

## Prerequisites

- Python 3.11 or higher
- Redis server (for caching and job queuing)
- Git (for cloning the repository)

## Quick Start

### 1. Environment Setup

Your `.env` file is already configured with your Clerk keys. You just need to add the webhook secret once you create the webhook endpoint.

### 2. Get ngrok Auth Token (if not already set)

If you don't have an ngrok auth token in your `.env` file:

1. Go to [ngrok Dashboard](https://dashboard.ngrok.com/get-started/your-authtoken)
2. Sign up/login and copy your auth token
3. Add it to your `.env` file:
   ```env
   NGROK_AUTHTOKEN=your_token_here
   ```

### 3. Quick Setup with Docker (Recommended)

Run the automated setup script:

**On Windows:**

```cmd
setup-dev.bat
```

**On Linux/macOS:**

```bash
chmod +x setup-dev.sh
./setup-dev.sh
```

**Or manually with Make:**

```bash
make dev-services
```

### 4. Get Your Public ngrok URL

After running the setup script:

1. Visit the ngrok dashboard: http://localhost:4040
2. Copy the HTTPS URL (e.g., `https://abc123.ngrok.io`)
3. This is your public URL for webhooks

**Or get it via command:**

```bash
make get-ngrok-url
```

### 5. Configure Clerk Webhook

1. Go to [Clerk Dashboard](https://dashboard.clerk.com/)
2. Navigate to **Webhooks**
3. Click **"Add Endpoint"**
4. Enter your ngrok URL + webhook path:
   ```
   https://your-ngrok-url.ngrok.io/api/v1/auth/webhooks/clerk
   ```
5. Select events: `user.created`, `user.updated`, `user.deleted`, `session.created`, `session.ended`
6. Copy the **Signing Secret** and add it to your `.env`:
   ```env
   CLERK_WEBHOOK_SECRET=whsec_your_webhook_signing_secret_here
   ```

### 6. Install Python Dependencies

```bash
pip install -r requirements.txt
```

### 7. Start the FastAPI Server

#### Method 1: Using the Makefile (Recommended)

```bash
make serve-api
```

#### Method 2: Using uvicorn directly

```bash
python -m uvicorn src.app.main:app --reload --host 0.0.0.0 --port 8000
```

#### Method 3: Full development workflow (services + API)

```bash
make dev-start
```

## Verification

Once the server is running, you can verify it's working by:

### 1. Health Check

```bash
curl http://localhost:8000/health
```

Expected response:

```json
{
  "status": "healthy",
  "app_name": "FastAPI Video Backend",
  "version": "0.1.0",
  "environment": "development"
}
```

### 2. API Documentation

Visit these URLs in your browser:

- **Local Swagger UI**: http://localhost:8000/docs
- **Public Swagger UI**: https://your-ngrok-url.ngrok.io/docs
- **ReDoc**: http://localhost:8000/redoc
- **OpenAPI JSON**: http://localhost:8000/openapi.json
- **ngrok Dashboard**: http://localhost:4040

### 3. Test Public Endpoint

```bash
# Test local endpoint
curl http://localhost:8000/

# Test public ngrok endpoint
curl https://your-ngrok-url.ngrok.io/health
```

## Docker Services Management

### Available Commands

```bash
# Start development services (Redis + ngrok)
make dev-services

# Stop development services
make dev-services-stop

# View service logs
make dev-services-logs

# Get current ngrok public URL
make get-ngrok-url

# Full development workflow
make dev-start
```

### Manual Docker Commands

```bash
# Start services
docker-compose -f docker-compose.dev.yml up -d

# Stop services
docker-compose -f docker-compose.dev.yml down

# View logs
docker-compose -f docker-compose.dev.yml logs -f

# Check service status
docker-compose -f docker-compose.dev.yml ps
```

## Available API Endpoints

The server provides the following main endpoint groups:

- **Authentication** (`/api/v1/auth/*`) - User authentication and authorization
- **Videos** (`/api/v1/videos/*`) - Video generation and management
- **Jobs** (`/api/v1/jobs/*`) - Background job management
- **Files** (`/api/v1/files/*`) - File upload and management
- **System** (`/api/v1/system/*`) - System health and monitoring

## Development Features

### Auto-reload

The server runs with auto-reload enabled in development mode, so changes to your code will automatically restart the server.

### Debug Mode

When `DEBUG=true` in your `.env` file:

- Detailed error messages are shown
- API documentation is available
- CORS is configured for local development

### Logging

The application uses structured logging. Logs will show:

- Request/response information
- Performance metrics
- Error details
- Authentication events

## Troubleshooting

### Common Issues

#### 1. Redis Connection Error

```
Failed to initialize Redis: [Errno 111] Connection refused
```

**Solution**: Make sure Redis server is running on the configured host and port.

#### 2. Clerk Authentication Error

```
Failed to initialize Clerk: Invalid secret key
```

**Solution**: Verify your Clerk API keys in the `.env` file are correct.

#### 3. Port Already in Use

```
[Errno 48] Address already in use
```

**Solution**: Either stop the process using port 8000 or change the `PORT` in your `.env` file.

#### 4. Import Errors

```
ModuleNotFoundError: No module named 'src'
```

**Solution**: Make sure you're running the server from the project root directory.

### Checking Server Status

```bash
# Check if server is running
curl -f http://localhost:8000/health

# Check Redis connection
redis-cli ping

# View server logs (if running in background)
tail -f logs/app.log
```

## Production Deployment

For production deployment:

1. Set `ENVIRONMENT=production` in your `.env`
2. Set `DEBUG=false`
3. Use a strong `SECRET_KEY`
4. Configure proper `ALLOWED_ORIGINS` for CORS
5. Set up proper Redis configuration with authentication
6. Use a production ASGI server like Gunicorn with Uvicorn workers

```bash
# Production server example
gunicorn src.app.main:app -w 4 -k uvicorn.workers.UvicornWorker --bind 0.0.0.0:8000
```

## Next Steps

After setting up the server:

1. **Generate Client SDKs**: Use `make generate-clients` to create client libraries
2. **Test the API**: Use `make test-clients` to run integration tests
3. **Explore the Documentation**: Visit `/docs` to understand available endpoints
4. **Set up Authentication**: Configure Clerk for user management
5. **Upload Files**: Test file upload functionality through the API

## Support

If you encounter issues:

1. Check the server logs for detailed error messages
2. Verify all environment variables are set correctly
3. Ensure all dependencies are installed
4. Make sure Redis is running and accessible
5. Check that your API keys are valid and have proper permissions

For additional help, refer to the project documentation or create an issue in the repository.