Deploying Invidious

Introduction

Invidious is an open-source alternative front-end to YouTube that prioritizes privacy and user experience. It allows you to watch YouTube videos without being tracked by Google, without advertisements, and without requiring JavaScript. The lightweight interface works on any browser while providing a cleaner, faster viewing experience.

Built with Crystal and leveraging PostgreSQL for data persistence, Invidious fetches video data directly from YouTube’s servers while stripping out tracking and advertising components. Users can subscribe to channels, create playlists, and customize their experience without creating a Google account or exposing their viewing habits.

Key highlights of Invidious:

• Privacy-First Design: No tracking, no analytics, no data collection from users
• Ad-Free Viewing: Watch videos without pre-roll, mid-roll, or banner advertisements
• No JavaScript Required: Basic functionality works without JavaScript enabled
• Light/Dark Themes: Customizable interface with multiple color schemes
• Subscription Management: Follow channels independently from Google accounts
• Audio-Only Mode: Stream audio without downloading video for bandwidth savings
• Customizable Homepage: Personalize your feed with preferred content categories
• API Access: Full API for building integrations and custom applications
• Proxy Support: Route video streams through the server for additional privacy
• Feed Export: Export subscriptions in OPML format for portability

This guide walks through deploying Invidious on Klutch.sh using Docker, configuring PostgreSQL for data persistence, and setting up the application for production use.

Why Deploy Invidious on Klutch.sh

Deploying Invidious on Klutch.sh provides several advantages for hosting your private YouTube front-end:

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

Persistent Storage: Attach persistent volumes for your PostgreSQL database. Your subscriptions, preferences, and user data survive container restarts and redeployments.

HTTPS by Default: Klutch.sh provides automatic SSL certificates, ensuring secure access to your Invidious 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 expected traffic and concurrent users. Start small and scale as usage grows.

Environment Variable Management: Securely store sensitive configuration like database credentials and HMAC keys through Klutch.sh’s environment variable system.

Custom Domains: Assign a custom domain to your Invidious instance for a professional, branded experience.

Always-On Availability: Your YouTube alternative remains accessible 24/7 without managing your own hardware.

Prerequisites

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

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

Understanding Invidious Architecture

Invidious consists of two main components that work together:

Invidious Application: The Crystal-based web application that handles video fetching, user interface rendering, and API requests. It communicates directly with YouTube’s servers to retrieve video data.

PostgreSQL Database: Stores user accounts, subscriptions, playlists, watch history, and application settings. Essential for maintaining state across restarts.

The application fetches video content from YouTube on-demand while caching metadata locally. Video streams can either be proxied through the Invidious server or delivered directly from YouTube’s CDN.

Preparing Your Repository

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

Repository Structure

invidious-deploy/
├── Dockerfile
├── config.yml
├── README.md
└── .dockerignore

Creating the Dockerfile

Create a Dockerfile in the root of your repository:

FROM quay.io/invidious/invidious:latest

# Configuration is handled via environment variables
# and the mounted config file

EXPOSE 3000

Creating the Configuration File

Create a config.yml file with your Invidious settings:

# Database configuration (use environment variables in production)
db:
  user: kemal
  password: kemal
  host: localhost
  port: 5432
  dbname: invidious

# Server configuration
check_tables: true
port: 3000
external_port: 443
https_only: true

# Domain configuration (set via environment variable)
domain:

# Privacy settings
statistics_enabled: false
registration_enabled: true

# Quality defaults
quality: dash
quality_dash: best

# Channel refresh settings
channel_threads: 1
feed_threads: 1

# Cache settings
cache_annotations: false

# Popular content (disabled for privacy)
popular_enabled: false

# HMAC key for signing (generate a secure random string)
hmac_key:

Creating the .dockerignore File

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

Environment Variables Reference

Variable	Required	Default	Description
INVIDIOUS_DATABASE_URL	Yes	-	PostgreSQL connection URL
INVIDIOUS_HMAC_KEY	Yes	-	Secret key for HMAC signing (generate securely)
INVIDIOUS_DOMAIN	Yes	-	Public domain for your instance
INVIDIOUS_HTTPS_ONLY	No	true	Force HTTPS connections
INVIDIOUS_REGISTRATION_ENABLED	No	true	Allow new user registrations
INVIDIOUS_EXTERNAL_PORT	No	443	External port for URL generation

Deploying Invidious on Klutch.sh

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

Generate Your HMAC Key

Generate a secure random key for HMAC signing:

openssl rand -hex 32

Save this key securely for the environment variables configuration.

Push Your Repository to GitHub

Initialize your repository and push to GitHub:

git init
git add Dockerfile config.yml .dockerignore README.md
git commit -m "Initial Invidious deployment configuration"
git remote add origin https://github.com/yourusername/invidious-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 “invidious” or “youtube-frontend”.

Deploy PostgreSQL First

Invidious requires PostgreSQL. Deploy a PostgreSQL instance on Klutch.sh first, or use an external managed database service. Note your database connection details.

Create a New App for Invidious

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

Configure HTTP Traffic

In the deployment settings:

• Select HTTP as the traffic type
• Set the internal port to 3000 (Invidious default port)

Set Environment Variables

In the environment variables section, add:

Variable	Value
INVIDIOUS_DATABASE_URL	postgres://kemal:password@your-postgres-host:5432/invidious
INVIDIOUS_HMAC_KEY	Your generated HMAC key
INVIDIOUS_DOMAIN	your-app-name.klutch.sh
INVIDIOUS_HTTPS_ONLY	true

Attach Persistent Volumes

Add persistent storage for any local caching:

Mount Path	Recommended Size	Purpose
/invidious/config	1 GB	Configuration and cache data

Deploy Your Application

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

• Detect your Dockerfile automatically
• Build the container image
• Start the Invidious container
• Provision an HTTPS certificate

Access Invidious

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

Initial Configuration

Creating an Admin Account

After deployment, create your first user account:

1. Navigate to your Invidious instance
2. Click “Login” in the top right
3. Click “Register” to create a new account
4. Your first account can be promoted to admin via database

Importing Subscriptions

If you have existing YouTube subscriptions:

1. Export your subscriptions from YouTube (Settings > Manage subscriptions > Export)
2. Log into your Invidious account
3. Navigate to Settings > Import/Export
4. Upload your subscription file

Customizing Appearance

Invidious offers extensive customization:

1. Navigate to Settings after logging in
2. Choose your preferred theme (light, dark, or system)
3. Set default video quality
4. Configure autoplay preferences
5. Enable/disable related videos

Production Best Practices

Security Recommendations

• Secure HMAC Key: Use a cryptographically random 32+ character key
• Database Security: Use strong passwords and restrict database access
• Registration Control: Disable public registration if running a private instance
• Regular Updates: Keep the Invidious image updated for security patches

Performance Optimization

• Enable Caching: Configure reverse proxy caching for static assets
• Database Tuning: Optimize PostgreSQL for your workload
• Video Proxy: Consider disabling video proxying to reduce bandwidth

Backup Strategy

1. Database Backups: Regularly back up your PostgreSQL database
2. Configuration Export: Export user subscriptions periodically
3. Subscription Sync: Encourage users to export their subscriptions

Troubleshooting Common Issues

Videos Not Loading

Symptoms: Videos fail to play or show errors.

Solutions:

• Check YouTube’s status for outages
• Verify your instance can reach YouTube servers
• Clear browser cache and cookies
• Try a different video quality setting

Database Connection Errors

Symptoms: Application won’t start or shows database errors.

Solutions:

• Verify PostgreSQL is running and accessible
• Check database credentials in environment variables
• Ensure database exists and has proper schema
• Review connection string format

Rate Limiting

Symptoms: Frequent errors or blocked requests.

Solutions:

• Reduce concurrent users if on a single IP
• Implement request rate limiting
• Consider using rotating proxy pools

Additional Resources

• Official Invidious Website
• Invidious Installation Documentation
• Invidious GitHub Repository
• Klutch.sh Persistent Volumes
• Klutch.sh Deployments

Conclusion

Deploying Invidious on Klutch.sh provides you with a private, ad-free YouTube viewing experience with automatic builds, persistent storage, and secure HTTPS access. The combination of Invidious’s privacy-first design and Klutch.sh’s deployment simplicity means you can focus on enjoying content without tracking or advertisements.

Whether you’re setting up a personal instance or providing a privacy-respecting YouTube alternative for your community, Invidious on Klutch.sh delivers the infrastructure needed for reliable, always-available video access that you control.