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)

Docker Installation

Clone the Repository

git clone https://github.com/mutonby/openshorts.git
cd OpenShorts

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

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

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:

Visit Google AI Studio
Sign in with your Google account
Click “Create API Key”
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:

Create Account

Free tier available with no credit card required

Create Profile

Go to Manage Users and create a user profile

Connect Social Accounts

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

Generate API Key

Navigate to API Keys and generate your key

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:

Sign up at elevenlabs.io
Navigate to your dashboard
Copy your API key
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:

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.

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"
      ]
    }
  ]
}

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.

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.

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
Frontend

# 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

# 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 allocatedSolution:

# 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 logsSolutions:

Reduce concurrent jobs:
.env
```
MAX_CONCURRENT_JOBS=1
```

Increase Docker memory limit:

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

Process shorter videos or reduce clip count

Gemini API Rate Limit Exceeded

Error: 429 Too Many Requests from Gemini APISolutions:

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 dataSolutions:

Try a different video URL

Add YouTube cookies to .env:

YOUTUBE_COOKIES=# Netscape HTTP Cookie File...

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 consoleSolutions:

Verify backend is running:
```
curl http://localhost:8000/health
```
Check CORS configuration in app.py
Ensure frontend is proxying to correct backend URL
Restart both services:
```
docker compose restart
```

Clips Not Uploading to S3

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

Verify AWS credentials:

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

Check IAM permissions (must include s3:PutObject)

Review backend logs for S3 errors:

docker compose logs backend | grep -i s3

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:

Use HTTPS: Deploy behind a reverse proxy (nginx, Traefik)
Set environment variables: Use secrets management (AWS Secrets Manager, etc.)
Enable authentication: Add auth middleware to app.py
Monitor resources: Set up logging and alerting
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

Get Started

Core Features

Guides

Configuration

Installation

Installation Guide

System Requirements

Required

Recommended

Docker Installation

Environment Configuration

Required API Keys

AWS S3 setup (optional)

Advanced Configuration

Concurrent Job Limit

Production API URL

Development Setup

Troubleshooting

Security Best Practices

File Upload Security

API Key Storage

Production Deployment

Next Steps

Quickstart

API Reference

YouTube Studio

GitHub Issues

Build docs developers (and LLMs) love

Get Started

Core Features

Guides

Configuration

​Installation Guide

​System Requirements

​Required

​Recommended

​Docker Installation

​Environment Configuration

​Required API Keys

​AWS S3 setup (optional)

​Advanced Configuration

​Concurrent Job Limit

​YouTube Cookie Authentication

​Production API URL

​Development Setup

​Troubleshooting

​Security Best Practices

​File Upload Security

​API Key Storage

​Production Deployment

​Next Steps

Quickstart

API Reference

YouTube Studio

GitHub Issues

Build docs developers (and LLMs) love

Installation Guide

System Requirements

Required

Recommended

Docker Installation

Environment Configuration

Required API Keys

AWS S3 setup (optional)

Advanced Configuration

Concurrent Job Limit

YouTube Cookie Authentication

Production API URL

Development Setup

Troubleshooting

Security Best Practices

File Upload Security

API Key Storage

Production Deployment

Next Steps