01 - Installation Guide¶
This guide covers everything needed to install and set up the API v2 environment from scratch.
📋 System Requirements¶
Operating System¶
- Linux (Ubuntu 18.04+, CentOS 7+, etc.)
- macOS (10.14+)
- Windows (Windows 10+ with WSL2 recommended)
Software Requirements¶
- Python 3.8+ (Python 3.9+ recommended)
- pip (Python package manager)
- FFmpeg (for video processing)
- Git (for version control)
🔧 Step 1: System Dependencies¶
On Ubuntu/Debian:¶
# Update package manager
sudo apt update
# Install Python 3.9+ and pip
sudo apt install python3.9 python3.9-pip python3.9-venv
# Install FFmpeg for video processing
sudo apt install ffmpeg
# Install additional dependencies
sudo apt install curl wget git
On CentOS/RHEL:¶
# Install EPEL repository
sudo yum install epel-release
# Install Python 3.9+
sudo yum install python39 python39-pip
# Install FFmpeg
sudo yum install ffmpeg
# Install additional tools
sudo yum install curl wget git
On macOS:¶
# Install Homebrew if not installed
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
# Install Python 3.9+
brew install [email protected]
# Install FFmpeg
brew install ffmpeg
# Install additional tools
brew install curl wget git
On Windows (WSL2):¶
# Install Python 3.9+
sudo apt update
sudo apt install python3.9 python3.9-pip python3.9-venv
# Install FFmpeg
sudo apt install ffmpeg
# Install additional tools
sudo apt install curl wget git
🐍 Step 2: Python Virtual Environment¶
Navigate to Project Directory¶
Create Virtual Environment¶
# Create virtual environment in the project directory
python3 -m venv .
# Alternative method if you have virtualenv
# virtualenv -p python3.9 .
Activate Virtual Environment¶
You should see (apiv2) in your terminal prompt, indicating the virtual environment is active.
Verify Python Version¶
python --version
# Should show Python 3.8+ (3.9+ recommended)
pip --version
# Should show pip version
📦 Step 3: Install Python Dependencies¶
Install from Requirements File¶
# Make sure you're in the project directory with venv activated
pip install --upgrade pip
# Install all required packages
pip install -r requirements.txt
Verify Installation¶
# Check installed packages
pip list
# Should include packages like:
# fastapi==0.104.1
# uvicorn==0.24.0
# google-generativeai==0.3.2
# moviepy==1.0.3
# playwright==1.52.0
# etc.
# Additional setup for Playwright
# After installing all dependencies from requirements.txt, you need to install Playwright browsers and system dependencies.
# Install Playwright browsers (Chromium, Firefox, WebKit)
playwright install chromium
# (Linux only) Install required system libraries for Playwright
playwright install-deps
🔍 Step 4: Verify FFmpeg Installation¶
# Check FFmpeg version
ffmpeg -version
# Should show FFmpeg version information
# Example output:
# ffmpeg version 4.4.2-0ubuntu0.22.04.1
If FFmpeg is Not Working:¶
Additional FFmpeg Setup (if needed):¶
# On Ubuntu, if ffmpeg doesn't work:
sudo apt install ffmpeg libavcodec-extra
# On CentOS, enable additional repositories:
sudo yum install https://download1.rpmfusion.org/free/el/rpmfusion-free-release-7.noarch.rpm
sudo yum install ffmpeg
# Test with simple command:
ffmpeg -f lavfi -i testsrc=duration=1:size=320x240:rate=1 test.mp4
📁 Step 5: Verify Project Structure¶
# Check that all necessary directories exist
ls -la
# Should see:
# - main.py (main application file)
# - requirements.txt
# - internal/ (directory with services)
# - audio/ (directory for audio files)
# - images/ (directory for image files)
# - sa/ (directory for service account files)
# - videos_output/ (directory for generated videos)
Create Missing Directories (if needed):¶
🧪 Step 6: Test Installation¶
Test Python Imports¶
python -c "
import fastapi
import uvicorn
import google.generativeai as genai
import moviepy
import requests
print('All major packages imported successfully!')
"
Test FFmpeg from Python¶
python -c "
import ffmpeg
print('FFmpeg-python imported successfully!')
import moviepy.config as mp_config
print('MoviePy config loaded successfully!')
"
🚨 Common Installation Issues¶
Issue: Python 3.8+ Not Available¶
# Install Python 3.9 from source (Ubuntu/Debian)
sudo apt update
sudo apt install build-essential zlib1g-dev libncurses5-dev libgdbm-dev libnss3-dev libssl-dev libsqlite3-dev libreadline-dev libffi-dev curl libbz2-dev
wget https://www.python.org/ftp/python/3.9.16/Python-3.9.16.tgz
tar -xf Python-3.9.16.tgz
cd Python-3.9.16
./configure --enable-optimizations
make -j 8
sudo make altinstall
Issue: FFmpeg Not Found¶
# Alternative FFmpeg installation
sudo snap install ffmpeg
# Or build from source
wget https://ffmpeg.org/releases/ffmpeg-4.4.2.tar.xz
tar -xf ffmpeg-4.4.2.tar.xz
cd ffmpeg-4.4.2
./configure --enable-gpl --enable-libx264
make
sudo make install
Issue: Permission Denied¶
# Fix pip permissions
python -m pip install --user --upgrade pip
# Or use sudo (not recommended for venv)
sudo pip install -r requirements.txt
Issue: Virtual Environment Not Working¶
# Alternative venv creation
python3 -m pip install virtualenv
python3 -m virtualenv .
source bin/activate
✅ Installation Verification Checklist¶
Before proceeding to the next step, verify:
- Python 3.8+ is installed and accessible
- Virtual environment is created and activated
- All packages from requirements.txt are installed
- FFmpeg is installed and accessible
- Project directory structure is correct
- No import errors when testing major packages
Final Test Command:¶
# Run this to verify everything is working
python -c "
import sys
print(f'Python version: {sys.version}')
import fastapi, uvicorn, google.generativeai, moviepy, ffmpeg
print('✅ All major dependencies imported successfully!')
import os
print(f'Current directory: {os.getcwd()}')
print(f'Virtual environment: {sys.prefix}')
print('✅ Installation complete!')
"
🎯 Next Steps¶
Once installation is complete, proceed to: - 02-environment-setup.md - Set up environment variables and API keys
📝 Notes¶
- Virtual Environment: Always activate the virtual environment before working with the project
- FFmpeg: Required for video processing features
- Python Version: Python 3.9+ is recommended for best compatibility
- Disk Space: Ensure at least 2GB free space for dependencies and generated files