MyTube/documents/en/getting-started.md

Getting Started

Prerequisites

• Node.js (v18 or higher recommended)
• npm (v9 or higher) or yarn
• Python 3.8+ (for yt-dlp and PO Token provider)
• yt-dlp (installed via pip/pipx)
• Docker (optional, for containerized deployment)

Installation

1. Clone the Repository

git clone https://github.com/franklioxygen/mytube.git
cd mytube

2. Install Dependencies

You can install all dependencies for the root, frontend, and backend with a single command:

npm run install:all

Or manually:

npm install
cd frontend && npm install
cd ../backend && npm install

Note: The backend installation will automatically build the bgutil-ytdlp-pot-provider server. However, you must ensure yt-dlp and the bgutil-ytdlp-pot-provider python plugin are installed in your environment:

# Install yt-dlp and the plugin
pip install yt-dlp bgutil-ytdlp-pot-provider

# OR using pipx (recommended for isolation)
pipx install yt-dlp
pipx inject yt-dlp bgutil-ytdlp-pot-provider

3. Configure Environment Variables

Backend Configuration

Create a .env file in the backend/ directory:

PORT=5551
UPLOAD_DIR=uploads
VIDEO_DIR=uploads/videos
IMAGE_DIR=uploads/images
SUBTITLES_DIR=uploads/subtitles
DATA_DIR=data
MAX_FILE_SIZE=500000000

Frontend Configuration

Create a .env file in the frontend/ directory:

VITE_API_URL=http://localhost:5551/api
VITE_BACKEND_URL=http://localhost:5551

4. Database Setup

The application uses SQLite with Drizzle ORM. The database will be automatically created and migrated on first startup:

• Database location: backend/data/mytube.db
• Migrations are run automatically when the server starts
• If you have legacy JSON data, you can migrate it using the settings page or API endpoint

Running the Application

Development Mode

From the root directory, start both frontend and backend:

npm run dev

This will start:

• Frontend: http://localhost:5556 (Vite dev server with hot reload)
• Backend API: http://localhost:5551 (Express server with nodemon)

Production Mode

Build and start in production mode:

# Build frontend
npm run build

# Start both services
npm run start

Individual Services

You can also run services individually:

# Backend only
cd backend
npm run dev        # Development mode
npm run start      # Production mode

# Frontend only
cd frontend
npm run dev        # Development mode
npm run preview    # Preview production build

Available Scripts

From the root directory:

npm run dev          # Start both frontend and backend in development mode
npm run start        # Start both frontend and backend in production mode
npm run build        # Build the frontend for production
npm run install:all  # Install dependencies for root, frontend, and backend

Backend-specific scripts (from backend/ directory):

npm run dev          # Start backend with nodemon (auto-reload)
npm run start        # Start backend in production mode
npm run build        # Compile TypeScript to JavaScript
npm run test         # Run tests with Vitest
npm run test:coverage # Run tests with coverage report
npm run generate     # Generate database migrations with Drizzle Kit

Frontend-specific scripts (from frontend/ directory):

npm run dev          # Start Vite dev server
npm run build        # Build for production
npm run preview      # Preview production build
npm run lint         # Run ESLint
npm run test         # Run tests with Vitest

First-Time Setup

1. Access the Application: Open http://localhost:5556 in your browser

2. Set Up Password Protection (Optional):

   • Go to Settings → Security
   • Enable password protection and set a password

3. Configure Download Settings:

   • Go to Settings → Download Settings
   • Set concurrent download limit
   • Configure download quality preferences

4. Upload Cookies (Optional, for age-restricted/premium content):

   • Go to Settings → Cookie Settings
   • Upload your cookies.txt file

5. Start Downloading:

   • Enter a video URL in the download input
   • Supported platforms: YouTube, Bilibili, MissAV, and all yt-dlp supported sites

Architecture Overview

Backend

• Framework: Express.js with TypeScript
• Database: SQLite with Drizzle ORM
• Architecture: Layered (Routes → Controllers → Services → Database)
• Downloaders: Abstract base class pattern for platform-specific implementations

Frontend

• Framework: React 19 with TypeScript
• Build Tool: Vite
• UI Library: Material-UI (MUI)
• State Management: React Context API
• Routing: React Router v7

Key Features

• Modular Storage Service: Split into focused modules for maintainability
• Download Queue Management: Concurrent downloads with queue support
• Video Download Tracking: Prevents duplicate downloads
• Subscription System: Automatic downloads from subscribed channels
• Database Migrations: Automatic schema updates on startup

Troubleshooting

Database Issues

• If you encounter database errors, check that the backend/data/ directory exists and is writable
• To reset the database, delete backend/data/mytube.db and restart the server

Download Issues

• Ensure yt-dlp is installed and accessible in your PATH
• Check that the bgutil-ytdlp-pot-provider plugin is installed
• Verify network connectivity and firewall settings

Port Conflicts

• If ports 5551 or 5556 are in use, modify the PORT environment variables
• Update frontend VITE_API_URL and VITE_BACKEND_URL accordingly

File Watcher Limit (ENOSPC Error)

If you encounter ENOSPC: System limit for number of file watchers reached when running the frontend dev server:

Note: The project's vite.config.js is already configured with polling-based file watching as a workaround, which should prevent this error in most cases. If you still encounter this issue, try the solutions below:

On Linux (host system):

# Check current limit
cat /proc/sys/fs/inotify/max_user_watches

# Increase the limit (temporary, until reboot)
sudo sysctl fs.inotify.max_user_watches=524288

# Make it permanent
echo "fs.inotify.max_user_watches=524288" | sudo tee -a /etc/sysctl.conf
sudo sysctl -p

In Docker: Add to your docker-compose.yml under the frontend service:

services:
  frontend:
    sysctls:
      - fs.inotify.max_user_watches=524288

Or run the container with:

docker run --sysctl fs.inotify.max_user_watches=524288 ...

Alternative: Configure Vite to use polling (already configured in this project):

The vite.config.js file includes a watch configuration that uses polling instead of native file watchers, which bypasses the inotify limit entirely:

server: {
  watch: {
    usePolling: true,
    interval: 2000,
    ignored: ['/node_modules/']
  }
}

This is already configured in the project, so the error should not occur. If you're using a custom Vite config, make sure to include this configuration.

Next Steps

• Read the API Endpoints documentation
• Check the Directory Structure for code organization
• Review the Docker Deployment Guide for production deployment