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
2. Sign up/login and copy your auth token
3. Add it to your .env file:

   NGROK_AUTHTOKEN=your_token_here
   

3. Quick Setup with Docker (Recommended)

Run the automated setup script:

On Windows:

setup-dev.bat

On Linux/macOS:

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

Or manually with Make:

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:

make get-ngrok-url

5. Configure Clerk Webhook

1. Go to Clerk Dashboard
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:

   CLERK_WEBHOOK_SECRET=whsec_your_webhook_signing_secret_here
   

6. Install Python Dependencies

pip install -r requirements.txt

7. Start the FastAPI Server

Method 1: Using the Makefile (Recommended)

make serve-api

Method 2: Using uvicorn directly

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

Method 3: Full development workflow (services + API)

make dev-start

Verification

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

1. Health Check

curl http://localhost:8000/health

Expected response:

{
  "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

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

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

Docker Services Management

Available Commands

# 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

# 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

# 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

# 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.