03 - Running the API¶

This guide covers how to start the API server, verify it's running correctly, and perform basic health checks.

🚀 Step 1: Activate Virtual Environment¶

Navigate to Project Directory¶

cd /home/supradmin/apiv2

Activate Virtual Environment¶

# Activate the virtual environment
source bin/activate

# You should see (apiv2) in your terminal prompt
# Example: (apiv2) user@hostname:/home/supradmin/apiv2$

Verify Environment¶

# Check Python version
python --version
# Should show Python 3.8+

# Check if in correct directory
pwd
# Should show: /home/supradmin/apiv2

# Verify key files exist
ls main.py requirements.txt .env

🔧 Step 2: Pre-Flight Checks¶

Verify Dependencies¶

# Check if all packages are installed
pip list | grep -E "(fastapi|uvicorn|google-generativeai|moviepy)"

# If missing packages, reinstall
pip install -r requirements.txt

Validate Environment¶

# Run environment validation
python -c "
from internal.config.settings import settings
try:
    settings.validate_required_settings()
    print('✅ Environment validation passed!')
except Exception as e:
    print(f'❌ Environment validation failed: {e}')
    exit(1)
"

Test Directory Structure¶

# Verify required directories exist
python -c "
from internal.config.settings import settings
settings.create_directories()
print('✅ Directory structure verified!')
"

🌟 Step 3: Start the API Server¶

Method 1: Direct Python Execution (Recommended)¶

# Start the server using main.py
python main.py

Method 2: Using Uvicorn Directly¶

# Alternative method using uvicorn
uvicorn main:app --host 0.0.0.0 --port 8000 --reload

Method 3: Background Process¶

# Run in background (for production)
nohup python main.py > server.log 2>&1 &

# Check if running
ps aux | grep python | grep main.py

Expected Output¶

When successful, you should see:

INFO:     Started server process [12345]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)

✅ Step 4: Verify API is Running¶

Health Check Endpoint¶

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

# Expected response:
{
  "status": "healthy",
  "version": "2.0.0",
  "services": {
    "text_summarizer": "active",
    "tts_service": "active",
    "video_service": "active",
    "youtube_service": "configured",
    "shortlink_service": "active"
  }
}

Interactive API Documentation¶

Open your web browser and visit:

http://localhost:8000/docs

This will show the Swagger UI with interactive API documentation.

Alternative Documentation¶

You can also visit:

http://localhost:8000/redoc

This shows the ReDoc documentation interface.

🧪 Step 5: Basic API Tests¶

Test 1: Simple Text Summarization¶

curl -X POST "http://localhost:8000/summarize" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "This is a test text that we want to summarize. It contains multiple sentences to test the summarization functionality. The API should return a shorter version of this text.",
    "max_length": 50
  }'

Expected response:

{
  "summary": "Test text for summarization functionality, expecting shorter output."
}

Test 2: Health Check with curl¶

curl -X GET "http://localhost:8000/health" \
  -H "accept: application/json"

Test 3: Product Marketing Test¶

curl -X POST "http://localhost:8000/product" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Wireless Bluetooth Headphones",
    "price": "$29.99",
    "link": "https://example.com/product"
  }'

🔄 Server Management¶

Starting the Server¶

Development Mode (with auto-reload):¶

python main.py
# or
uvicorn main:app --reload --host 0.0.0.0 --port 8000

Production Mode:¶

uvicorn main:app --host 0.0.0.0 --port 8000 --workers 4

Stopping the Server¶

If running in foreground:¶

# Press Ctrl+C in the terminal

If running in background:¶

# Find the process ID
ps aux | grep "python main.py"

# Kill the process (replace XXXX with actual PID)
kill XXXX

# Or kill all Python processes (be careful!)
pkill -f "python main.py"

Restarting the Server¶

# Stop the server (Ctrl+C or kill command)
# Then start again
python main.py

📊 Monitoring and Logs¶

Viewing Logs (if running in background)¶

# View server logs
tail -f server.log

# View last 50 lines
tail -n 50 server.log

# Follow logs with timestamps
tail -f server.log | while read line; do echo "$(date): $line"; done

Checking Server Status¶

# Check if port 8000 is being used
netstat -tlnp | grep :8000

# Or using ss
ss -tlnp | grep :8000

# Check server response
curl -s -o /dev/null -w "%{http_code}" http://localhost:8000/health
# Should return: 200

Resource Usage Monitoring¶

# Monitor CPU and memory usage
top -p $(pgrep -f "python main.py")

# Or using htop (if installed)
htop -p $(pgrep -f "python main.py")

🚨 Troubleshooting Server Issues¶

Issue: Port Already in Use¶

# Find what's using port 8000
sudo lsof -i :8000

# Kill the process
sudo kill -9 $(sudo lsof -t -i:8000)

# Or use a different port
uvicorn main:app --host 0.0.0.0 --port 8001

Issue: Module Not Found Errors¶

# Make sure virtual environment is activated
source bin/activate

# Reinstall requirements
pip install -r requirements.txt

# Check Python path
python -c "import sys; print(sys.path)"

Issue: Environment Variables Not Loaded¶

# Verify .env file exists and is readable
ls -la .env
cat .env

# Test environment loading
python -c "
from dotenv import load_dotenv
import os
load_dotenv()
print('GEMINI_API exists:', bool(os.getenv('GEMINI_API')))
"

Issue: Permission Denied¶

# Fix file permissions
chmod +x main.py
chmod 644 .env

# Fix directory permissions
chmod 755 audio images videos_output tts

Issue: Google Cloud Authentication¶

# Verify service account file
ls -la sa/supradmin-0c4280905b78.json

# Test authentication
python -c "
from google.cloud import storage
client = storage.Client()
print('GCS authentication successful!')
"

🔧 Server Configuration Options¶

Environment Variables for Server¶

# Set custom port
export PORT=8001
python main.py

# Set host binding
export HOST=127.0.0.1
python main.py

Uvicorn Configuration Options¶

# Production settings
uvicorn main:app \
  --host 0.0.0.0 \
  --port 8000 \
  --workers 4 \
  --access-log \
  --log-level info

# Development settings
uvicorn main:app \
  --host 127.0.0.1 \
  --port 8000 \
  --reload \
  --log-level debug

📈 Performance Considerations¶

For Production Use:¶

# Use multiple workers
uvicorn main:app --workers 4 --host 0.0.0.0 --port 8000

# Or use gunicorn
pip install gunicorn
gunicorn main:app -w 4 -k uvicorn.workers.UvicornWorker --bind 0.0.0.0:8000

Resource Limits:¶

# Set memory limits (if needed)
ulimit -v 2097152  # 2GB virtual memory limit

# Monitor resource usage
watch -n 1 'ps aux | grep python'

🎯 Next Steps¶

Once the server is running successfully, proceed to: - 04-api-endpoints.md - Detailed endpoint documentation and usage examples

📝 Quick Reference¶

Common Commands:¶

# Start server
python main.py

# Health check
curl http://localhost:8000/health

# View logs
tail -f server.log

# Stop server
Ctrl+C (or kill process)

# Check server status
curl -s -o /dev/null -w "%{http_code}" http://localhost:8000/health

Default URLs:¶

API Server: http://localhost:8000
Interactive Docs: http://localhost:8000/docs
ReDoc: http://localhost:8000/redoc
Health Check: http://localhost:8000/health