Skip to content

docker.md

Latest commit

 

History

History
257 lines (194 loc) · 7.12 KB

docker.md

File metadata and controls

257 lines (194 loc) · 7.12 KB
Raw

Docker Usage

This guide explains how to use the HomeTube Docker image.

Available Images

The image is available on GitHub Container Registry:

  • ghcr.io/EgalitarianMonkey/hometube:latest - Stable version (main branch)
  • ghcr.io/EgalitarianMonkey/hometube:2.4.1 - Specific tagged version
  • ghcr.io/EgalitarianMonkey/hometube:main - Development version

Quick Usage

With docker run

# Basic usage
docker run -p 8501:8501 ghcr.io/EgalitarianMonkey/hometube:latest

# With volumes for download persistence
docker run -p 8501:8501 \
  -v ./downloads:/data/videos \
  -v ./cookies:/config \
  ghcr.io/EgalitarianMonkey/hometube:latest

# With complete configuration
docker run -p 8501:8501 \
  -v ./downloads:/data/videos \
  -v ./tmp:/data/tmp \
  -v ./cookies:/config \
  -e STREAMLIT_SERVER_PORT=8501 \
  ghcr.io/EgalitarianMonkey/hometube:latest

With docker-compose

Step 1: Create your configuration

# Copy the sample configuration
cp docker-compose.yml.sample docker-compose.yml

# Edit the file to customize your setup
nano docker-compose.yml  # or use your preferred editor

Step 2: Deploy

docker-compose up -d

Sample configuration (docker-compose.yml.sample):

services:
  hometube:
    image: ghcr.io/EgalitarianMonkey/hometube:latest
    ports:
      - "8501:8501"
    volumes:
      - ./downloads:/data/videos
      - ./tmp:/data/tmp
      - ./cookies:/config
    environment:
      - STREAMLIT_SERVER_PORT=8501
      - STREAMLIT_SERVER_ADDRESS=0.0.0.0
    restart: unless-stopped

Volumes

Volume Description Required
/data/videos Output folder for downloaded videos Recommended
/data/tmp Temporary processing files Optional
/config Cookie files and configuration Optional

Environment Variables

Core System Variables

Variable Default Value Description
STREAMLIT_SERVER_PORT 8501 Application listening port
STREAMLIT_SERVER_ADDRESS 0.0.0.0 Listening address
TZ UTC Container timezone (e.g., America/New_York, Europe/Paris)
DEBUG false Enable debug logging mode

Path Configuration

Variable Default Value Description
VIDEOS_FOLDER /data/videos Output folder for downloaded videos
TMP_DOWNLOAD_FOLDER /data/tmp Temporary processing folder
YOUTUBE_COOKIES_FILE_PATH /config/youtube_cookies.txt Authentication cookie file path

Quality & Download Preferences

Variable Default Value Description
QUALITY_PROFILE auto Default quality profile (mkv_av1_opus, mkv_vp9_opus, mp4_av1_aac, mp4_h264_aac)
VIDEO_QUALITY_MAX max Maximum video resolution (max, 2160, 1440, 1080, 720, 480, 360)
QUALITY_DOWNGRADE true Allow quality downgrade on profile failure
EMBED_CHAPTERS true Embed chapters by default
EMBED_SUBTITLES true Embed subtitles by default
CUTTING_MODE keyframes Video cutting precision (keyframes, precise)

Audio Language Preferences

Variable Default Value Description
LANGUAGE_PRIMARY en Primary audio language preference
LANGUAGES_SECONDARIES (empty) Secondary audio languages (comma-separated)
LANGUAGE_PRIMARY_INCLUDE_SUBTITLES true Include subtitles for primary language
VO_FIRST true Prioritize original voice (VO) before primary language

Localization

Variable Default Value Description
UI_LANGUAGE en Interface language (en, fr)

Note: Subtitle languages are automatically determined by LANGUAGE_PRIMARY_INCLUDE_SUBTITLES and LANGUAGES_SECONDARIES settings (see Audio Language Preferences above).

Advanced Options

Variable Default Value Description
YTDLP_CUSTOM_ARGS (empty) Custom yt-dlp arguments
BROWSER_SELECT chrome Default browser for cookie extraction
REMOVE_TMP_FILES_AFTER_DOWNLOAD false Remove temporary files after successful download
NEW_DOWNLOAD_WITHOUT_TMP_FILES false Clean tmp folder before each new download

Media Server Integration

Variable Default Value Description
JELLYFIN_BASE_URL Base URL of your Jellyfin server (e.g., https://jellyfin.local:8096)
JELLYFIN_API_KEY Jellyfin API key used for triggering library refreshes

Access

Once the container is started, access the application via:

Configuration

Personal Configuration

The repository includes a sample Docker Compose configuration that you should copy and customize:

# Copy the sample configuration
cp docker-compose.yml.sample docker-compose.yml

# Edit to match your setup
nano docker-compose.yml

💡 Note: docker-compose.yml is ignored by Git, so you can safely customize it without affecting the repository.

Configuration Options

You can customize the following in your docker-compose.yml:

  • Ports: Change the exposed port
  • Volumes: Modify mount paths for your system
  • Environment variables: Set timezone, server options, etc.
  • Resource limits: Add CPU/memory constraints

Security

For production usage

# With basic authentication (to be configured in a reverse proxy)
docker run -p 127.0.0.1:8501:8501 \
  -v ./downloads:/data/videos \
  -v ./cookies:/config \
  ghcr.io/EgalitarianMonkey/hometube:latest

Reverse proxy (nginx)

server {
    listen 80;
    server_name videos.example.com;
    
    location / {
        proxy_pass http://localhost:8501;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        
        # WebSocket support for Streamlit
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

Updates

# Stop the container
docker stop hometube

# Remove the old container
docker rm hometube

# Download the new image
docker pull ghcr.io/EgalitarianMonkey/hometube:latest

# Restart with the new image
docker run -p 8501:8501 \
  -v ./downloads:/data/videos \
  -v ./cookies:/config \
  --name hometube \
  ghcr.io/EgalitarianMonkey/hometube:latest

Troubleshooting

Container logs

docker logs hometube

Access the container

docker exec -it hometube /bin/bash

Check volumes

# Check disk space
docker exec hometube df -h

# List downloaded files
docker exec hometube ls -la /data/videos

Local Build

To build the image locally:

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

# Build the image
docker build -t hometube:local .

# Run the local image
docker run -p 8501:8501 hometube:local