Skip to content

installation.md

Latest commit

 

History

History
390 lines (287 loc) · 8.59 KB

installation.md

File metadata and controls

390 lines (287 loc) · 8.59 KB
Raw

📦 Installation Guide

This guide covers all installation methods for HomeTube.

🐳 Docker Installation (Recommended)

Docker provides the easiest and most reliable installation method.

Prerequisites

Quick Start with Docker

# Basic run with ephemeral storage
docker run -p 8501:8501 ghcr.io/EgalitarianMonkey/hometube:latest

# Persistent storage (recommended)
docker run -p 8501:8501 \
  -v ./downloads:/data/videos \
  -v ./cookies:/config \
  --name hometube \
  ghcr.io/EgalitarianMonkey/hometube:latest

Docker Compose Setup

  1. Clone or download the repository:

    git clone https://github.com/EgalitarianMonkey/hometube.git
cd hometube

  2. Set up configuration:

    # Copy sample files
cp docker-compose.yml.sample docker-compose.yml
cp .env.sample .env

# Edit configurations as needed
nano docker-compose.yml  # Optional: customize ports, volumes
nano .env               # Optional: customize paths, settings

  3. Start the application:

    docker-compose up -d

  4. Access the interface: Open http://localhost:8501 in your browser

Environment Configuration

Create a .env file for custom settings:

# Network configuration
PORT=8501
TZ=Europe/Paris

# Storage paths
VIDEOS_FOLDER_DOCKER_HOST=./downloads
TMP_DOWNLOAD_FOLDER_DOCKER_HOST=./tmp
YOUTUBE_COOKIES_FILE_PATH_DOCKER_HOST=./cookies/youtube_cookies.txt

💻 Local Installation

For development or systems without Docker.

Prerequisites

  • Python 3.10+: Download from python.org
  • FFmpeg: Required for video processing
  • Package manager: pip, conda, uv, or poetry

System Dependencies

Ubuntu/Debian

sudo apt update
sudo apt install python3 python3-pip ffmpeg

macOS (with Homebrew)

brew install python ffmpeg

Windows

  1. Install Python 3.10+
  2. Download FFmpeg and add to PATH

Python Environment Setup

Choose your preferred method:

Using pip/venv (Standard)

# Clone repository
git clone https://github.com/EgalitarianMonkey/hometube.git
cd hometube

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies
pip install -e .
pip install -e ".[test]"

# Run tests
make test

# Start application
streamlit run app/main.py

Using conda

# Clone repository
git clone https://github.com/EgalitarianMonkey/hometube.git
cd hometube

# ⚠️ ESSENTIAL: Configure environment
cp .env.sample .env
# Edit .env file to customize settings (see Configuration section below)

# Create conda environment
conda create -n hometube python=3.11
conda activate hometube

# Install dependencies
pip install -e .
pip install -e ".[test]"

# Run tests
make test

# Start application
streamlit run app/main.py

Using uv

# Install uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# Clone repository
git clone https://github.com/EgalitarianMonkey/hometube.git
cd hometube

# ⚠️ ESSENTIAL: Configure environment
cp .env.sample .env
# Edit .env file to customize settings (see Configuration section below)

# Setup environment
uv sync

# Run tests
uv run pytest tests/

# Start application
uv run streamlit run app/main.py

Using pip/venv (Legacy)

# Clone repository
git clone https://github.com/EgalitarianMonkey/hometube.git
cd hometube

# ⚠️ ESSENTIAL: Configure environment
cp .env.sample .env
# Edit .env file to customize settings (see Configuration section below)

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # Linux/macOS
# or
.venv\Scripts\activate     # Windows

# Install dependencies
pip install -r requirements/requirements-dev.txt

# Start application
streamlit run app/main.py

🔧 Advanced Installation

Custom Build from Source

# Clone repository
git clone https://github.com/EgalitarianMonkey/hometube.git
cd hometube

# Build custom Docker image
docker build -t my-hometube .

# Run custom image
docker run -p 8501:8501 my-hometube

Production Deployment

For production environments, see the Deployment Guide.

Development Setup

For contributing to the project, see the Contributing Guide.

⚙️ Environment Configuration

Essential: .env File Setup

The .env file is required for the application to work properly:

# Copy the sample configuration
cp .env.sample .env

# Edit with your preferred settings
nano .env  # or code .env, vim .env, etc.

Configuration Options

# Network & Port
PORT=8501                    # Application port (default: 8501)
TZ=Europe/Paris             # Your timezone

# Storage Paths (Local Installation)
VIDEOS_FOLDER=./downloads    # Where videos are saved
TMP_DOWNLOAD_FOLDER=./tmp    # Temporary processing folder
UI_LANGUAGE=en              # Interface language (en/fr)

# Audio & Subtitle Language Preferences
LANGUAGE_PRIMARY=en          # Primary audio language
LANGUAGE_PRIMARY_INCLUDE_SUBTITLES=true  # Include subtitles for primary
LANGUAGES_SECONDARIES=       # Secondary languages (comma-separated, e.g., fr,es)

# Authentication
YOUTUBE_COOKIES_FILE_PATH=./cookies/youtube_cookies.txt
# COOKIES_FROM_BROWSER=brave  # Auto-extract from browser (optional)

# Media server: Jellyfin
JELLYFIN_BASE_URL=https://jellyfin.local:8096
JELLYFIN_API_KEY=<api key allowed to refresh libraries>

# Docker Paths (Docker Installation)
VIDEOS_FOLDER_DOCKER_HOST=./downloads
TMP_DOWNLOAD_FOLDER_DOCKER_HOST=./tmp
YOUTUBE_COOKIES_FILE_PATH_DOCKER_HOST=./cookies/youtube_cookies.txt

Common Customizations

Change download location:

# Edit .env file
VIDEOS_FOLDER=/path/to/your/media/library

Configure audio and subtitle languages:

# Edit .env file
LANGUAGE_PRIMARY=en                        # Primary audio language
LANGUAGE_PRIMARY_INCLUDE_SUBTITLES=true    # Include subtitles for primary
LANGUAGES_SECONDARIES=fr,es,de,it          # Additional languages (always get subtitles)

Change interface language:

# Edit .env file
UI_LANGUAGE=fr  # French interface

🚨 Troubleshooting

Common Issues

Application won't start - Missing .env file:

# Solution: Copy and configure environment
cp .env.sample .env

FFmpeg not found:

# Verify FFmpeg installation
ffmpeg -version

# Ubuntu/Debian: Install via apt
sudo apt install ffmpeg

# macOS: Install via Homebrew
brew install ffmpeg

Permission denied (Docker):

# Linux: Add user to docker group
sudo usermod -aG docker $USER
# Then logout and login again

Port already in use:

# Check what's using port 8501
lsof -i :8501

# Use different port
docker run -p 8502:8501 ghcr.io/EgalitarianMonkey/hometube:latest

Downloads not persistent:

  • Ensure you're using volume mounts: -v ./downloads:/data/videos
  • Check directory permissions: chmod 755 ./downloads

Performance Optimization

For faster downloads:

# Increase concurrent fragments
export YTDL_CONCURRENT_FRAGMENTS=4

# Use temporary directory on SSD
docker run -v /tmp/downloads:/data/tmp ...

For lower resource usage:

# Limit Docker resources
docker run --memory=1g --cpus=1.0 ...

📋 Verification

After installation, verify everything works:

  1. Access web interface: http://localhost:8501
  2. Test download: Try downloading a public YouTube video
  3. Check logs: docker logs hometube (Docker) or console output (local)
  4. Test features: Try different quality settings, subtitle options

🔄 Updates

Docker Updates

# Pull latest image
docker pull ghcr.io/EgalitarianMonkey/hometube:latest

# Recreate container
docker-compose up -d --force-recreate

Local Updates

# Update repository
git pull origin main

# Update dependencies
make dev-setup  # or pip install -r requirements/requirements-dev.txt

# Restart application

🆘 Getting Help

If you encounter issues:

  1. Check the troubleshooting section above
  2. Review the Usage Guide for feature-specific help
  3. Check GitHub Issues
  4. Create a new issue with:
    • Installation method used
    • Error messages
    • System information (OS, Python version, etc.)

Next: Usage Guide - Learn how to use all the features