Installation

Detailed installation guide for OpenShorts with Docker and environment configuration

Installation Guide

This guide covers the complete installation process for OpenShorts, including environment configuration, optional integrations, and troubleshooting.

System Requirements

Required

• Docker (version 20.10+)
• Docker Compose (version 2.0+)
• 4GB RAM minimum (8GB+ recommended for concurrent processing)
• 10GB free disk space (more for processing large videos)

Recommended

• GPU support (optional, for faster YOLOv8 processing)
• SSD storage (for faster video I/O)
• Multi-core CPU (for parallel clip processing)

OpenShorts runs entirely CPU-optimized by default. GPU acceleration is optional and provides marginal performance improvements.

Docker Installation

1. Clone the Repository

   git clone https://github.com/mutonby/openshorts.git
   cd OpenShorts
   
2. Review Docker Compose Configuration

   The docker-compose.yml defines two services:

   docker-compose.yml

   services:
     backend:
       build: .
       container_name: openshorts-backend
       ports:
         - "8000:8000"
       volumes:
         - .:/app
         - /app/__pycache__
       restart: unless-stopped
   
     frontend:
       build: ./dashboard
       container_name: openshorts-frontend
       ports:
         - "5175:5173"
       volumes:
         - ./dashboard:/app
         - /app/node_modules
       restart: unless-stopped
       depends_on:
         - backend
   

   Backend (Python FastAPI):

   • Runs on port 8000
   • Handles video processing, AI analysis, and API endpoints
   • Auto-restarts on failure

   Frontend (React + Vite):

   • Runs on port 5173 (mapped to 5175 externally)
   • Provides the web dashboard interface
   • Depends on backend service
3. Build and Start Services

   docker compose up --build
   

   First build downloads AI models (Faster-Whisper, YOLOv8, MediaPipe) and may take 3-5 minutes. Subsequent starts are instant.

   For detached mode (runs in background):

   docker compose up --build -d
   

   View logs:

   docker compose logs -f
   
4. Verify Installation

   Check that both services are running:

   docker compose ps
   

   You should see:

   NAME                     STATUS
   openshorts-backend       Up
   openshorts-frontend      Up
   

   Test the API:

   curl http://localhost:8000/health
   

   Access the dashboard:

   http://localhost:5173
   

Environment Configuration

Required API Keys

Google Gemini API Key (Required)

OpenShorts requires a Gemini API key for viral moment detection and title generation.

Get your free API key:

1. Visit Google AI Studio
2. Sign in with your Google account
3. Click “Create API Key”
4. Copy the key

Configuration:

• The key is entered via the dashboard on first launch
• Stored encrypted in browser local storage
• Never stored server-side
• Sent only to Google Gemini API via headers

The free tier has rate limits. For production use, consider upgrading to a paid Gemini plan.

Upload-Post API Key (Optional)

Required for direct social media posting to TikTok, Instagram, and YouTube.

Setup:

1. Create Account

   Sign up at app.upload-post.com/login

   Free tier available with no credit card required
2. Create Profile

   Go to Manage Users and create a user profile

3. Connect Social Accounts

   In the same section, connect your TikTok, Instagram, or YouTube accounts to the profile

4. Generate API Key

   Navigate to API Keys and generate your key

5. Add to OpenShorts

   Paste the API key in the OpenShorts dashboard settings and select your profile

ElevenLabs API Key (Optional)

Required for AI voice dubbing to 30+ languages with voice cloning.

Setup:

1. Sign up at elevenlabs.io
2. Navigate to your dashboard
3. Copy your API key
4. Enter it in OpenShorts dashboard settings

Features:

• Translate clips to 30+ languages
• Voice cloning preserves speaker characteristics
• Auto-generates subtitles in dubbed language
• Supports multiple voices per project

AWS S3 setup (optional)

Enable automatic backup of generated clips to AWS S3:

1. Create S3 Bucket

   AWS CLI

   aws s3 mb s3://your-bucket-name --region us-east-1
   

   Or use the AWS Console to create a bucket.

2. Create IAM User with S3 Access

   Create an IAM user with the following policy:

   IAM Policy

   {
     "Version": "2012-10-17",
     "Statement": [
       {
         "Effect": "Allow",
         "Action": [
           "s3:PutObject",
           "s3:GetObject",
           "s3:ListBucket"
         ],
         "Resource": [
           "arn:aws:s3:::your-bucket-name/*",
           "arn:aws:s3:::your-bucket-name"
         ]
       }
     ]
   }
   
3. Configure Environment Variables

   Create a .env file in the project root:

   .env

   # AWS S3 Configuration
   AWS_ACCESS_KEY_ID=your_aws_access_key_here
   AWS_SECRET_ACCESS_KEY=your_aws_secret_key_here
   AWS_REGION=us-east-1
   AWS_S3_BUCKET=your-bucket-name
   

   Never commit the .env file to version control. It contains sensitive credentials.

4. Restart Services

   docker compose down
   docker compose up --build
   

   S3 uploads now happen automatically in the background after clip generation.

Advanced Configuration

Concurrent Job Limit

Control how many videos can be processed simultaneously:

.env

MAX_CONCURRENT_JOBS=5

• Default: 5 concurrent jobs
• Low-end systems: Set to 1-2
• High-end servers: Set to 10+

Each concurrent job uses approximately 1-2GB RAM. Adjust based on your system’s available memory.

YouTube Cookie Authentication

Bypass bot detection for YouTube downloads:

.env

# Export cookies from your browser in Netscape format
YOUTUBE_COOKIES=# Netscape HTTP Cookie File...

Use a browser extension like “Get cookies.txt” to export cookies from youtube.com.

Production API URL

Override the frontend API URL for production deployments:

.env

VITE_API_URL=https://api.yourdomain.com

Development Setup

For local development without Docker:

Backend

# Install Python dependencies
pip install -r requirements.txt

# Start FastAPI server
uvicorn app:app --host 0.0.0.0 --port 8000 --reload

Backend runs on http://localhost:8000

Frontend

# Navigate to dashboard
cd dashboard

# Install Node dependencies
npm install

# Start dev server with hot reload
npm run dev

Frontend runs on http://localhost:5173

Troubleshooting

Port Already in Use

Error: Bind for 0.0.0.0:8000 failed: port is already allocated

Solution:

# Find and kill the process using the port
lsof -ti:8000 | xargs kill -9

# Or change the port in docker-compose.yml
ports:
  - "8001:8000"  # Use port 8001 instead

Out of Memory During Processing

Symptoms: Container crashes, “Killed” messages in logs

Solutions:

1. Reduce concurrent jobs:

   .env

   MAX_CONCURRENT_JOBS=1
   

2. Increase Docker memory limit:

   docker compose down
   # Edit Docker Desktop settings > Resources > Memory
   # Increase to 6GB+
   docker compose up --build
   

3. Process shorter videos or reduce clip count

Gemini API Rate Limit Exceeded

Error: 429 Too Many Requests from Gemini API

Solutions:

• Wait 60 seconds between requests (free tier limit)
• Upgrade to a paid Gemini API plan
• Reduce the number of clips requested per video

YouTube Download Failed

Error: ERROR: unable to download video data

Solutions:

1. Try a different video URL
2. Add YouTube cookies to .env:
   YOUTUBE_COOKIES=# Netscape HTTP Cookie File...
   
3. Update yt-dlp:
   docker compose down
   docker compose build --no-cache backend
   docker compose up
   

Frontend Can't Connect to Backend

Error: Network Error or Failed to fetch in browser console

Solutions:

1. Verify backend is running:

   curl http://localhost:8000/health
   

2. Check CORS configuration in app.py

3. Ensure frontend is proxying to correct backend URL

4. Restart both services:

   docker compose restart
   

Clips Not Uploading to S3

Symptoms: Clips generate but don’t appear in S3 bucket

Solutions:

1. Verify AWS credentials:

   aws s3 ls s3://your-bucket-name --profile default
   

2. Check IAM permissions (must include s3:PutObject)

3. Review backend logs for S3 errors:

   docker compose logs backend | grep -i s3
   

4. Ensure bucket region matches AWS_REGION in .env

Security Best Practices

OpenShorts containers run as a dedicated appuser (non-root) for security. Never modify the Dockerfile to run as root.

File Upload Security

• Max file size: 2GB (configurable in app.py)
• Automatic cleanup: Jobs purged after 1 hour
• Isolation: Each job runs in isolated directory

API Key Storage

• Client-side: Encrypted in browser localStorage
• Server-side: Never stored, only passed via headers
• Network: Use HTTPS in production

Production Deployment

For production deployments:

1. Use HTTPS: Deploy behind a reverse proxy (nginx, Traefik)
2. Set environment variables: Use secrets management (AWS Secrets Manager, etc.)
3. Enable authentication: Add auth middleware to app.py
4. Monitor resources: Set up logging and alerting
5. Backup strategy: Configure S3 lifecycle policies

Next Steps

Quickstart

Generate your first viral clip in 5 minutes

API Reference

Integrate OpenShorts into your applications

YouTube Studio

Learn about AI title and thumbnail generation

GitHub Issues

Report bugs or request features