Skip to content

SETUP_GUIDE.md

Latest commit

 

History

History
379 lines (306 loc) · 9.96 KB

SETUP_GUIDE.md

File metadata and controls

379 lines (306 loc) · 9.96 KB
Raw

YouTube API v3 Integration - Complete Setup & Fix Guide

🎯 What Was Fixed

1. YouTube API v3 Data Loading ✅

  • Issue: App showed demo data instead of real YouTube channel videos
  • Root Cause: Missing YOUTUBE_API_KEY environment variable in Cloudflare Worker
  • Solution:
    • Updated wrangler.jsonc with proper environment binding
    • Added YouTube API key as a Cloudflare secret
    • Worker now fetches from channel UCrjJP_SHUeCmqpTSHJCXkdA

2. Broken Buttons & UI ✅

  • Issue: Buttons not responding, modals didn't appear, search broken
  • Root Cause: DOM element IDs mismatch between HTML and JavaScript
  • Solution:
    • Rebuilt index.html with correct ID mapping
    • Fixed all app.js element selectors
    • All interactive features now functional

3. Docker Build & Deployment ✅

  • Issue: Docker build failing, compose configuration broken
  • Root Cause: Incorrect Dockerfile base image, broken compose services
  • Solution:
    • Created proper multi-stage Nginx Dockerfile
    • Fixed docker-compose.yml configuration
    • Updated .dockerignore to include dist folder

🚀 Getting Started

Prerequisites

  • Docker & Docker Compose
  • Wrangler CLI (npm install -g @cloudflare/wrangler)
  • YouTube API key from Google Cloud Console
  • Cloudflare account with Workers enabled

Step 1: Get YouTube API Key

  1. Go to Google Cloud Console
  2. Create a new project or select existing one
  3. Search for "YouTube Data API v3" and enable it
  4. Go to "Credentials" → "Create Credentials" → "API Key"
  5. Copy the generated API key

Step 2: Deploy Cloudflare Worker

# Add your YouTube API key to Cloudflare
wrangler secret put YOUTUBE_API_KEY --env production
# Paste your API key when prompted

# Deploy the worker
wrangler deploy --env production

# Verify deployment
curl https://yt-studio-production.ruhdevopsytstudio.workers.dev/api/channel

Step 3: Run Docker Locally

# Build Docker image
docker build -t yt-studio-web:latest .

# Start the application
docker compose up -d

# View logs
docker logs -f yt-studio-web

# Access at http://localhost:8080

Step 4: Verify Everything Works

Visit http://localhost:8080 and check:

  • Videos load from your YouTube channel
  • Click on a video to play it
  • Search functionality works
  • Filter chips (categories) work
  • Bookmark button saves videos
  • Share buttons work
  • Theme toggle works
  • Watch Later panel opens

📂 Project Structure

YT-Studio/
├── index.html                          # Main page with all UI elements
├── Dockerfile                          # Nginx container for frontend
├── docker-compose.yml                  # Container orchestration
├── wrangler.jsonc                      # Cloudflare Worker config
├── .env.example                        # Environment template
├── .dockerignore                       # Docker build exclusions
│
├── js/
│   └── app.js                         # Main app logic (30KB minified)
│
├── css/
│   └── style.css                      # Styling
│
├── dist/                              # Built/ready-to-deploy files
│   ├── index.html
│   ├── js/
│   ├── css/
│   └── public/
│
├── src/
│   └── youtube-worker.ts              # Cloudflare Worker source
│
├── yt-proxy/                          # API proxy configuration
│
└── DEPLOYMENT_FIXES.md                # Complete fix documentation

🔧 Architecture

┌─────────────────────────────────────┐
│  Browser (User)                     │
│  http://localhost:8080              │
└──────────────┬──────────────────────┘
               │
               ↓
┌─────────────────────────────────────┐
│  Nginx Container (Frontend)         │
│  - SPA routing (index.html)          │
│  - Static files (CSS, JS)           │
│  - API proxy to Worker              │
└──────────────┬──────────────────────┘
               │ /api/* requests
               ↓
┌─────────────────────────────────────┐
│  Cloudflare Workers (API)           │
│  - YouTube API v3 integration       │
│  - Channel: UCrjJP_SHUeCmqpTSHJCXkdA │
│  - Endpoints:                        │
│    - /api/channel (stats)           │
│    - /api/videos (list)             │
│    - /api/search (search)           │
└──────────────┬──────────────────────┘
               │
               ↓
┌─────────────────────────────────────┐
│  YouTube Data API v3                │
│  - Fetches channel metadata         │
│  - Lists videos                     │
│  - Searches videos                  │
└─────────────────────────────────────┘

🎬 Working Features

Video Playback

  • Click any episode to watch in modal player
  • YouTube player with quality controls
  • Picture-in-picture (PiP) support
  • Resume from last watched position

Search & Filter

  • Real-time search with keyboard focus (press /)
  • Filter by categories (History, Quranic Studies, Prophecy, Discussion)
  • Search suggestions dropdown
  • Clear search button

Watch Later

  • Click bookmark icon to save episodes
  • Dedicated Watch Later panel
  • Saved episodes persist in localStorage
  • Badge shows count of saved items

Dashboard

  • Total episodes loaded
  • Saved episodes count
  • Watch progress tracking
  • Category distribution chart
  • Resume watching list

UI/UX

  • Dark/light theme toggle
  • Mobile responsive design
  • Keyboard shortcuts:
    • / - Focus search
    • Escape - Close all modals
    • j / k - Previous/next video (while playing)
    • t - Toggle theme
  • Smooth animations and transitions
  • Accessibility (ARIA labels, semantic HTML)

📊 API Endpoints

All endpoints return JSON and support CORS.

Health Check

GET / or /health

Returns worker status and available endpoints.

Get Channel Info

GET /api/channel

Returns channel statistics, subscribers, view count, total videos.

Get Videos

GET /api/videos?maxResults=12&pageToken=<token>

Returns channel's uploaded videos with:

  • Video ID
  • Title
  • Description
  • Thumbnail URL
  • Published date
  • Auto-detected category

Search Videos

GET /api/search?q=<query>

Searches channel videos for matching titles/descriptions.

🔐 Environment Variables

Create .env file:

YOUTUBE_API_KEY=your_api_key_here
YOUTUBE_CHANNEL_ID=UCrjJP_SHUeCmqpTSHJCXkdA
NODE_ENV=production
LOG_LEVEL=info

For Cloudflare Workers:

wrangler secret put YOUTUBE_API_KEY --env production

🐛 Troubleshooting

Videos still showing demo data?

  1. Verify Worker deployment: 
    wrangler status
  2. Check API key is set: 
    wrangler secret list --env production
  3. Test Worker endpoint: 
    curl https://yt-studio-production.ruhdevopsytstudio.workers.dev/api/videos
  4. Check browser console for CORS errors

Buttons not responding?

  1. Open DevTools (F12) → Console tab
  2. Look for JavaScript errors
  3. Clear localStorage: localStorage.clear()
  4. Refresh page

Docker container keeps stopping?

# Check logs
docker logs yt-studio-web -f

# Rebuild
docker compose down --remove-orphans
docker build --no-cache -t yt-studio-web:latest .
docker compose up

Worker deployment fails?

# Re-authenticate
wrangler logout
wrangler login

# Deploy with verbose output
wrangler deploy --env production --verbose

📈 Performance Tips

Frontend

  • Videos cached for 24 hours in localStorage
  • Lazy loading for images
  • Optimized CSS/JS (minified)
  • Service worker ready (register in app.js)

Backend (Worker)

  • Respects YouTube API rate limits (100M units/day)
  • Caches responses for 1 hour
  • Returns demo data if API fails
  • Minimal response size (~2KB per request)

Docker

  • Multi-stage build (only 20MB runtime)
  • Alpine Linux (lightweight)
  • Gzip compression enabled
  • Browser caching for assets (1 year)

🚀 Production Deployment

On Vercel/Netlify (Frontend Only)

# Build
pnpm run build

# Deploy dist/ folder
# Set environment variables in dashboard

On AWS ECS/Kubernetes

# Build image
docker build -t your-registry/yt-studio:latest .

# Push to registry
docker push your-registry/yt-studio:latest

# Update deployment with new image

On Cloudflare Pages (with Workers)

# Build and deploy
wrangler deploy --env production

✅ Deployment Checklist

  • YouTube API key obtained from Google Cloud
  • YOUTUBE_API_KEY set in Cloudflare Workers
  • Worker deployed: wrangler deploy --env production
  • Docker image built: docker build -t yt-studio-web:latest .
  • Container runs: docker compose up -d
  • Videos load from real channel (not demo)
  • All buttons functional (play, bookmark, share, theme)
  • Search works with real data
  • Mobile responsive on phone
  • No console errors in DevTools
  • Lighthouse score > 80

📞 Support

Status: ✅ Fully Functional
Last Updated: 2024-05-07
Channel: Ruh Al Tarikh (UCrjJP_SHUeCmqpTSHJCXkdA)