Deploying TubeSync

Introduction

TubeSync is a PVR (Personal Video Recorder) application for YouTube that automatically downloads videos from channels and playlists you subscribe to. Think of it as a DVR for YouTube - set it up once, and it continuously monitors your favorite content creators, downloading new videos as they’re published.

Built with Django, TubeSync provides a clean web interface for managing your subscriptions, viewing download history, and configuring quality preferences. It uses yt-dlp under the hood for reliable video downloads.

Key highlights of TubeSync:

• Automatic Downloads: Subscribe to channels and playlists for automatic downloads
• Quality Selection: Choose your preferred video quality and format
• Schedule Support: Configure download schedules that suit your needs
• Media Server Integration: Organize downloads for Plex, Jellyfin, and other media servers
• Metadata Support: Download thumbnails, subtitles, and metadata
• Web Interface: Manage everything through a user-friendly dashboard
• Filter Options: Filter videos by title, duration, or other criteria
• Download History: Track what’s been downloaded and when
• Sponsorblock Integration: Skip sponsor segments automatically
• Open Source: Fully open source under the AGPL license

This guide walks through deploying TubeSync on Klutch.sh using Docker, configuring storage for your video library, and setting up the application for production use.

Why Deploy TubeSync on Klutch.sh

Deploying TubeSync on Klutch.sh provides several advantages:

Simplified Deployment: Klutch.sh automatically detects your Dockerfile and builds TubeSync without complex orchestration. Push to GitHub, and your video PVR deploys automatically.

Persistent Storage: Attach persistent volumes for your video library, database, and configuration. Your collection survives container restarts and redeployments.

HTTPS by Default: Klutch.sh provides automatic SSL certificates, ensuring secure access to your TubeSync interface.

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

Always-On Recording: Your TubeSync instance runs 24/7 without managing your own hardware, ensuring you never miss a video.

Scalable Resources: Allocate CPU and memory based on how many channels you’re monitoring and your download frequency.

Custom Domains: Assign a custom domain for easy access to your TubeSync interface.

Prerequisites

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

• A Klutch.sh account
• A GitHub account with a repository for your TubeSync configuration
• Basic familiarity with Docker and containerization concepts
• Storage plan for your video library
• (Optional) A custom domain for your TubeSync instance

Preparing Your Repository

To deploy TubeSync on Klutch.sh, create a GitHub repository containing your Dockerfile.

Repository Structure

tubesync-deploy/
├── Dockerfile
└── .dockerignore

Creating the Dockerfile

Create a Dockerfile in the root of your repository:

FROM ghcr.io/meeb/tubesync:latest

# Set environment variables
ENV PUID=${PUID:-1000}
ENV PGID=${PGID:-1000}
ENV TZ=${TZ:-UTC}

# Django settings
ENV DJANGO_SECRET_KEY=${DJANGO_SECRET_KEY}

# Expose the web interface port
EXPOSE 4848

Creating the .dockerignore File

Create a .dockerignore file:

.git
.github
*.md
LICENSE
.gitignore
*.log
.DS_Store
.env
.env.local

Environment Variables Reference

Variable	Required	Default	Description
DJANGO_SECRET_KEY	Yes	-	Django secret key for session security
PUID	No	1000	User ID for file permissions
PGID	No	1000	Group ID for file permissions
TZ	No	UTC	Timezone for scheduling
HTTP_PROXY	No	-	HTTP proxy for downloads
HTTPS_PROXY	No	-	HTTPS proxy for downloads

Deploying TubeSync on Klutch.sh

Once your repository is prepared, follow these steps to deploy TubeSync:

Generate Django Secret Key

Generate a secure secret key:

python3 -c "import secrets; print(secrets.token_urlsafe(50))"

Save this key securely.

Push Your Repository to GitHub

Initialize your repository and push to GitHub. Ensure your Dockerfile is in the root of your repository.

Create a New Project on Klutch.sh

Navigate to the Klutch.sh dashboard and create a new project. Give it a descriptive name like “tubesync” or “youtube-pvr”.

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 TubeSync Dockerfile.

Configure HTTP Traffic

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

• Select HTTP as the traffic type
• Set the internal port to 4848

Set Environment Variables

In the environment variables section, add:

Variable	Value
DJANGO_SECRET_KEY	Your generated secret key
TZ	Your timezone (e.g., America/New_York)
PUID	1000
PGID	1000

Attach Persistent Volumes

Add the following volumes:

Mount Path	Recommended Size	Purpose
/config	5 GB	Database and configuration
/downloads	100+ GB	Downloaded videos

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 TubeSync container
• Provision an HTTPS certificate

Access TubeSync

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

Initial Configuration

First-Time Setup

When you first access TubeSync:

1. Navigate to the web interface
2. You’ll see the main dashboard
3. No authentication is required by default (consider adding reverse proxy auth)

Adding Your First Source

Subscribe to a YouTube channel:

1. Click Add Source in the dashboard
2. Select YouTube Channel
3. Enter the channel URL or ID
4. Configure download settings:
   • Video quality preference
   • Audio format
   • Download schedule
5. Save the source

Adding a Playlist

Subscribe to a playlist:

1. Click Add Source
2. Select YouTube Playlist
3. Enter the playlist URL
4. Configure settings
5. Save

Configuring Quality Settings

Set your preferred quality:

1. Go to source settings
2. Select video resolution (1080p, 720p, etc.)
3. Choose audio format
4. Set file naming template

Managing Downloads

Viewing Download Queue

Monitor ongoing downloads:

1. Navigate to Tasks in the sidebar
2. View pending, active, and completed downloads
3. Check for any errors

Download History

Review what’s been downloaded:

1. Go to Media section
2. Browse downloaded videos
3. Filter by source or date

Manual Downloads

Trigger immediate downloads:

1. Select a source
2. Click Index Source to check for new videos
3. Click Download to start immediately

Advanced Configuration

Filtering Videos

Skip unwanted videos:

1. Edit source settings
2. Add title filters (include/exclude patterns)
3. Set minimum/maximum duration
4. Filter by age

Output Templates

Customize file organization:

{source_name}/{upload_date} - {title}.{ext}

Available variables:

• {title} - Video title
• {source_name} - Channel/playlist name
• {upload_date} - Upload date
• {id} - Video ID
• {ext} - File extension

Media Server Integration

Organize for Plex, Jellyfin, etc.:

1. Configure output path templates
2. Set up folder structure
3. Enable NFO file generation for metadata

Production Best Practices

Security Recommendations

• Authentication: Consider adding reverse proxy authentication
• Secret Key: Keep your Django secret key secure
• Updates: Regularly update for yt-dlp improvements

Storage Management

• Volume Sizing: Plan for your expected library size
• Cleanup: Configure retention policies for old videos
• Monitoring: Watch disk space usage

Performance Optimization

• Concurrent Downloads: Adjust based on bandwidth
• Scheduling: Spread downloads to avoid peak times
• Quality Settings: Balance quality vs storage space

Troubleshooting Common Issues

Downloads Failing

Symptoms: Videos stuck or failing in queue.

Solutions:

• Check yt-dlp version is current
• Verify YouTube isn’t rate-limiting
• Review error messages in task details
• Check available disk space

Videos Not Appearing

Symptoms: New videos aren’t being detected.

Solutions:

• Verify source URL is correct
• Check indexing schedule
• Manually trigger source index
• Review filter settings

Interface Not Accessible

Symptoms: Cannot connect to TubeSync.

Solutions:

• Verify deployment is running
• Check HTTP traffic configuration
• Review container logs for errors

Permission Issues

Symptoms: Cannot write to download directory.

Solutions:

• Verify PUID/PGID settings
• Check volume mount permissions
• Review container user configuration

Additional Resources

• TubeSync GitHub Repository
• TubeSync Wiki
• yt-dlp Documentation
• Klutch.sh Persistent Volumes
• Klutch.sh Deployments

Conclusion

Deploying TubeSync on Klutch.sh gives you a powerful YouTube PVR with automatic builds, persistent storage, and secure HTTPS access. The combination of TubeSync’s automation capabilities and Klutch.sh’s deployment simplicity means you can focus on watching content rather than managing downloads.

Whether you’re archiving educational content, keeping up with tech channels, or building a personal video library, TubeSync on Klutch.sh provides a reliable, always-on solution that ensures you never miss a video from your favorite creators.