Deploying MeTube

Introduction

MeTube is a self-hosted web GUI for youtube-dl (using the yt-dlp fork) that provides a clean, modern interface for downloading videos and audio from YouTube and hundreds of other supported sites. Built with Angular on the frontend and Python on the backend, MeTube makes it easy to download content without needing command-line knowledge.

The application runs as a lightweight container and supports features like download queues, format selection, playlist support, and automatic metadata embedding. MeTube is designed to be simple yet powerful, offering both quick downloads and advanced options for users who need more control.

Key highlights of MeTube:

Web-Based Interface: Download videos from any browser without installing desktop applications
Multi-Site Support: Works with YouTube, Vimeo, SoundCloud, and hundreds of other sites supported by yt-dlp
Format Selection: Choose video quality, audio-only extraction, or specific formats
Playlist Support: Download entire playlists or channels with a single URL
Queue Management: Queue multiple downloads and monitor progress in real-time
Metadata Embedding: Automatically embeds metadata like thumbnails, titles, and descriptions
Custom Output Templates: Configure file naming patterns and output directories
Browser Extension Support: Integrate with browser extensions for one-click downloads
Dark Mode: Clean, modern interface with dark mode support
100% Open Source: Licensed under AGPL-3.0

This guide walks through deploying MeTube on Klutch.sh using Docker, configuring persistent storage for your downloads, and setting up the application for personal use.

Why Deploy MeTube on Klutch.sh

Deploying MeTube on Klutch.sh provides several advantages for self-hosted video downloading:

Simplified Deployment: Klutch.sh automatically detects your Dockerfile and builds MeTube without complex orchestration. Push to GitHub, and your download service deploys automatically.

Persistent Storage: Attach persistent volumes for your downloaded content. Your video library survives container restarts and redeployments without data loss.

HTTPS by Default: Klutch.sh provides automatic SSL certificates, ensuring secure access to your MeTube instance from anywhere.

GitHub Integration: Connect your configuration repository directly from GitHub. Updates to your Dockerfile trigger automatic redeployments.

Scalable Resources: Allocate CPU and memory based on your expected download volume and transcoding needs.

Always-On Availability: Your download service remains accessible 24/7 without managing your own hardware or dealing with home network configuration.

Custom Domains: Assign a custom domain to your MeTube instance for easy access.

Prerequisites

Before deploying MeTube on Klutch.sh, ensure you have:

A Klutch.sh account
A GitHub account with a repository for your MeTube configuration
Basic familiarity with Docker and containerization concepts
(Optional) A custom domain for your MeTube instance

Preparing Your Repository

To deploy MeTube on Klutch.sh, create a GitHub repository containing your Dockerfile and any custom configuration.

Repository Structure

metube-deploy/
├── Dockerfile
├── README.md
└── .dockerignore

Creating the Dockerfile

Create a Dockerfile in the root of your repository:

FROM ghcr.io/alexta69/metube:latest

# Set environment variables
ENV UID=${UID:-1000}
ENV GID=${GID:-1000}

# Optional: Set default download directory
ENV DOWNLOAD_DIR=${DOWNLOAD_DIR:-/downloads}

# Optional: Set output template for downloaded files
ENV OUTPUT_TEMPLATE=${OUTPUT_TEMPLATE:-%(title)s.%(ext)s}

# Optional: Set default audio format for audio-only downloads
ENV AUDIO_FORMAT=${AUDIO_FORMAT:-mp3}

# Create download directory
RUN mkdir -p /downloads

# Expose the web interface port
EXPOSE 8081

# Health check
HEALTHCHECK --interval=30s --timeout=10s --start-period=30s --retries=3 \
  CMD wget --no-verbose --tries=1 --spider http://localhost:8081/ || exit 1

Environment Variables Reference

Variable	Required	Default	Description
`UID`	No	1000	User ID for file ownership
`GID`	No	1000	Group ID for file ownership
`DOWNLOAD_DIR`	No	/downloads	Directory for downloaded files
`AUDIO_DOWNLOAD_DIR`	No	Same as DOWNLOAD_DIR	Separate directory for audio downloads
`OUTPUT_TEMPLATE`	No	%(title)s.%(ext)s	yt-dlp output template for file naming
`OUTPUT_TEMPLATE_CHAPTER`	No	Same as OUTPUT_TEMPLATE	Template for chapter downloads
`STATE_DIR`	No	/downloads/.metube	Directory for queue state persistence
`YTDL_OPTIONS`	No	{}	Additional yt-dlp options as JSON
`AUDIO_FORMAT`	No	mp3	Default audio format (mp3, m4a, opus, wav)
`DEFAULT_QUALITY`	No	best	Default video quality
`HTTPS_ONLY`	No	false	Only allow HTTPS URLs

Deploying on Klutch.sh

Push Your Repository to GitHub

Initialize your repository and push to GitHub:

git init
git add Dockerfile .dockerignore README.md
git commit -m "Initial MeTube deployment configuration"
git remote add origin https://github.com/yourusername/metube-deploy.git
git push -u origin main

Create a New Project on Klutch.sh

Navigate to the Klutch.sh dashboard and create a new project. Give it a descriptive name like “metube” or “video-downloader”.

Create a New App

Within your project, create a new app. Connect your GitHub account if you haven’t already, then select the repository containing your MeTube Dockerfile.

Configure HTTP Traffic

MeTube serves its web interface over HTTP. In the deployment settings:

Select HTTP as the traffic type
Set the internal port to 8081 (MeTube’s default port)

Set Environment Variables

Add the following environment variables:

Variable	Value
`UID`	`1000`
`GID`	`1000`
`DOWNLOAD_DIR`	`/downloads`
`OUTPUT_TEMPLATE`	`%(title)s.%(ext)s`

Attach Persistent Volumes

Add the following volumes:

Mount Path	Recommended Size	Purpose
`/downloads`	100+ GB	Downloaded videos and audio files

Deploy Your Application

Click Deploy to start the build process. Klutch.sh will:

Detect your Dockerfile automatically
Build the container image
Attach the persistent volumes
Start the MeTube container
Provision an HTTPS certificate

Access MeTube

Once deployment completes, access your MeTube instance at https://example-app.klutch.sh.

Using MeTube

Basic Downloads

Copy the URL of a video you want to download
Paste the URL into MeTube’s input field
Select your preferred quality (best, 1080p, 720p, etc.)
Click Add to start the download

Audio-Only Downloads

Toggle the Audio Only switch to extract just the audio track from videos. MeTube will:

Download the best available audio quality
Convert to your preferred audio format (MP3, M4A, OPUS, WAV)
Embed metadata and album art when available

Playlist Downloads

Paste a playlist URL and MeTube will:

Detect the playlist automatically
Queue all videos for download
Show progress for each item in the playlist

Custom Output Templates

Configure output templates using yt-dlp syntax:

# Include uploader and date
%(uploader)s - %(upload_date)s - %(title)s.%(ext)s

# Organize by channel
%(channel)s/%(title)s.%(ext)s

# Include video ID for uniqueness
%(title)s [%(id)s].%(ext)s

Advanced Options

Set custom yt-dlp options via the YTDL_OPTIONS environment variable:

{
  "writesubtitles": true,
  "subtitleslangs": ["en", "es"],
  "postprocessors": [{
    "key": "FFmpegEmbedSubtitle"
  }]
}

Browser Extension Integration

MeTube supports browser extensions for one-click downloads:

Configuring the Browser Extension

Install a browser bookmarklet or extension that supports custom download servers
Configure the extension with your MeTube URL
Click the extension while on a supported video page to send it to MeTube

Bookmarklet

Create a bookmarklet with:

javascript:window.open('https://your-metube.klutch.sh/add?url=' + encodeURIComponent(location.href));

Managing Downloads

Queue Management

View active downloads with real-time progress
See download speed and estimated time remaining
Cancel downloads in progress
Clear completed downloads from the list

Download History

MeTube persists your download queue in the state directory, allowing you to:

Resume interrupted downloads
Track what you’ve downloaded
Retry failed downloads

Accessing Downloaded Files

Direct Access

Downloaded files are stored in the /downloads volume. Options for accessing them:

Deploy a file browser application alongside MeTube
Use SFTP/SCP to transfer files
Sync with cloud storage using rclone

Organizing Downloads

Use output templates to organize files automatically:

# By content type
Video/%(title)s.%(ext)s
Audio/%(title)s.%(ext)s

# By source
%(extractor)s/%(channel)s/%(title)s.%(ext)s

Troubleshooting

Download Fails Immediately

Check if the URL is from a supported site
Verify the video is publicly accessible
Review container logs for specific error messages

Poor Download Speed

Check your Klutch.sh deployment’s network connectivity
Some sites may throttle download speeds
Consider adjusting concurrent download limits

Missing Audio or Video

Ensure ffmpeg is available (included in the default image)
Check that the requested format is available for the video
Try a different quality setting

Files Not Persisting

Verify the persistent volume is mounted correctly
Check that downloads are going to the mounted directory
Ensure proper file permissions (UID/GID settings)

Additional Resources

Conclusion

Deploying MeTube on Klutch.sh gives you a powerful, self-hosted video downloading solution with a clean web interface. The combination of yt-dlp’s extensive site support and MeTube’s user-friendly interface makes it easy to build a personal media library.

With persistent storage for your downloads and Klutch.sh’s always-on infrastructure, you can access your download service from anywhere and build a collection of content on your own terms. Whether you’re archiving educational content, saving music, or building a personal video library, MeTube on Klutch.sh provides the foundation for a reliable download service that you control.