Skip to content
Klutch.sh Docs

Deploying ChannelTube

ChannelTube is a self-hosted, privacy-focused video streaming platform that enables you to build your own YouTube-like service. It supports video uploading, streaming, playlists, comments, and subscriptions while maintaining complete control over your data. ChannelTube is ideal for content creators, educational institutions, and organizations that want to host and stream video content privately.

This guide will walk you through deploying ChannelTube on Klutch.sh, a modern cloud platform that simplifies containerized application deployment. By the end of this guide, you’ll have a fully functional ChannelTube instance running on your own domain.

Why Deploy ChannelTube on Klutch.sh?

Klutch.sh provides an excellent platform for hosting ChannelTube:

  • Docker-native deployment - Klutch.sh automatically detects and deploys Dockerized applications
  • Persistent storage - Attach volumes for video content, database files, and user uploads
  • Custom domains - Point your domain to your ChannelTube instance
  • Environment configuration - Manage secrets and configuration through the dashboard
  • Zero-downtime updates - Deploy new versions of your application seamlessly
  • Scalability - Easily allocate resources as your user base grows

Prerequisites

Before deploying ChannelTube on Klutch.sh, you’ll need:

  • A Klutch.sh account (sign up for free)
  • Access to the Klutch.sh dashboard
  • A GitHub repository to store your ChannelTube deployment configuration
  • A custom domain (optional but recommended for production use)
  • Understanding of Docker and containerization basics

Deployment Steps

  1. Create a Dockerfile

    Create a Dockerfile in the root of your repository to containerize ChannelTube:

    FROM node:20-alpine
    

    # Install system dependencies
    RUN apk add --no-cache \
        build-base \
        python3 \
        git \
        ffmpeg \
        imagemagick
    

    # Set working directory
    WORKDIR /app
    

    # Clone ChannelTube repository
    RUN git clone https://github.com/ggerganov/ChannelTube.git . && \
        git checkout main
    

    # Install dependencies
    RUN npm install
    

    # Build the application
    RUN npm run build
    

    # Create necessary directories
    RUN mkdir -p /app/uploads /app/config
    

    # Expose port
    EXPOSE 3000
    

    # Health check
    HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
        CMD node -e "require('http').get('http://localhost:3000/health', (r) => {if (r.statusCode !== 200) throw new Error(r.statusCode)})"
    

    # Start the application
    CMD ["npm", "start"]

  2. Create Environment Configuration File

    Create a .env.example file to document required environment variables:

    # ChannelTube Environment Configuration
    

    # Application Host and Port
    NODE_ENV=production
    HOST=0.0.0.0
    PORT=3000
    

    # Database Configuration
    DATABASE_URL=postgresql://channeltube:channeltubepass@localhost:5432/channeltube
    DATABASE_HOST=db
    DATABASE_PORT=5432
    DATABASE_USER=channeltube
    DATABASE_PASSWORD=channeltubepass
    DATABASE_NAME=channeltube
    

    # Redis Configuration (for caching and sessions)
    REDIS_URL=redis://redis:6379
    

    # JWT Secret (generate with: openssl rand -base64 32)
    JWT_SECRET=your-jwt-secret-here-change-in-production
    

    # File Upload Configuration
    MAX_FILE_SIZE=5368709120
    UPLOAD_DIR=/app/uploads
    THUMBNAIL_DIR=/app/uploads/thumbnails
    

    # Video Processing
    ENABLE_TRANSCODING=true
    FFMPEG_PATH=/usr/bin/ffmpeg
    

    # Email Configuration (Optional)
    SMTP_HOST=smtp.gmail.com
    SMTP_PORT=587
    SMTP_USER=your-email@gmail.com
    SMTP_PASSWORD=your-app-password
    SMTP_FROM=noreply@example.com
    

    # Administration
    ADMIN_EMAIL=admin@example.com
    ADMIN_PASSWORD=change-me-in-production
    

    # API Configuration
    API_BASE_URL=https://example-app.klutch.sh
    CORS_ORIGIN=https://example-app.klutch.sh
    

    # Logging
    LOG_LEVEL=info

  3. Create Node.js Configuration File

    Create a ecosystem.config.js file for production process management:

    module.exports = {
      apps: [
        {
          name: 'channeltube',
          script: './dist/index.js',
          instances: 'max',
          exec_mode: 'cluster',
          env: {
            NODE_ENV: 'production',
            PORT: 3000
          },
          error_file: '/app/logs/err.log',
          out_file: '/app/logs/out.log',
          log_date_format: 'YYYY-MM-DD HH:mm:ss Z',
          merge_logs: true,
          autorestart: true,
          watch: false,
          max_memory_restart: '1G'
        }
      ]
    };

  4. Create Database Initialization Script

    Create an init-db.sh file to set up the PostgreSQL database:

    #!/bin/bash
    

    set -e
    

    echo "Initializing ChannelTube database..."
    

    # Wait for PostgreSQL to be ready
    until PGPASSWORD=$DATABASE_PASSWORD psql -h "$DATABASE_HOST" -U "$DATABASE_USER" -d "postgres" -c "\q"; do
      echo 'Waiting for postgres...'
      sleep 1
    done
    

    echo "PostgreSQL is ready!"
    

    # Create database if it doesn't exist
    PGPASSWORD=$DATABASE_PASSWORD psql -h "$DATABASE_HOST" -U "$DATABASE_USER" -d "postgres" << EOF
    CREATE DATABASE $DATABASE_NAME;
    EOF
    

    echo "Database initialization complete!"
    

    # Run migrations
    npm run migrate
    

    echo "Database migrations completed!"

    Make it executable:

    Terminal window
    chmod +x init-db.sh

  5. Create Docker Compose for Local Development

    Create a docker-compose.yml file for local development and testing (not used for Klutch.sh deployment):

    version: '3.8'
    

    services:
      channeltube:
        build: .
        container_name: channeltube-dev
        ports:
          - "3000:3000"
        environment:
          - NODE_ENV=development
          - DATABASE_URL=postgresql://channeltube:channeltubepass@db:5432/channeltube
          - DATABASE_HOST=db
          - DATABASE_USER=channeltube
          - DATABASE_PASSWORD=channeltubepass
          - DATABASE_NAME=channeltube
          - REDIS_URL=redis://redis:6379
          - JWT_SECRET=dev-secret-key-change-in-production
          - UPLOAD_DIR=/app/uploads
          - THUMBNAIL_DIR=/app/uploads/thumbnails
          - API_BASE_URL=http://localhost:3000
          - CORS_ORIGIN=http://localhost:3000
          - ADMIN_EMAIL=admin@localhost
          - ADMIN_PASSWORD=admin123
        depends_on:
          - db
          - redis
        volumes:
          - ./uploads:/app/uploads
          - ./src:/app/src
        networks:
          - channeltube-network
    

      db:
        image: postgres:16-alpine
        container_name: channeltube-db
        environment:
          - POSTGRES_USER=channeltube
          - POSTGRES_PASSWORD=channeltubepass
          - POSTGRES_DB=channeltube
        volumes:
          - channeltube_db_data:/var/lib/postgresql/data
        networks:
          - channeltube-network
        healthcheck:
          test: ["CMD-SHELL", "pg_isready -U channeltube"]
          interval: 10s
          timeout: 5s
          retries: 5
    

      redis:
        image: redis:7-alpine
        container_name: channeltube-redis
        networks:
          - channeltube-network
        healthcheck:
          test: ["CMD", "redis-cli", "ping"]
          interval: 10s
          timeout: 5s
          retries: 5
    

    volumes:
      channeltube_db_data:
    

    networks:
      channeltube-network:
        driver: bridge

  6. Create .gitignore File

    Create a .gitignore file to exclude sensitive data from version control:

    # Environment files
    .env
    .env.local
    .env.*.local
    

    # Node.js
    node_modules/
    npm-debug.log
    yarn-error.log
    package-lock.json
    yarn.lock
    

    # Build artifacts
    dist/
    build/
    .next/
    out/
    

    # Video uploads and media
    uploads/
    public/uploads/
    

    # Database
    *.sqlite
    *.sqlite3
    data/
    

    # Process management
    ecosystem-lock.json
    

    # IDE
    .vscode/
    .idea/
    *.swp
    *.swo
    *~
    .DS_Store
    

    # Logs
    logs/
    *.log
    

    # Cache
    .cache/
    .turbo/

  7. Push Configuration to GitHub

    Push your repository to GitHub with all configuration files:

    Terminal window
    git add Dockerfile .env.example ecosystem.config.js init-db.sh \
      docker-compose.yml .gitignore
    git commit -m "Initial ChannelTube deployment configuration for Klutch.sh"
    git push origin main

  8. Deploy on Klutch.sh

    1. Navigate to klutch.sh/app and log in to your dashboard
    2. Click Create New App
    3. Connect your GitHub repository containing the ChannelTube deployment files (the Dockerfile will be automatically detected)
    4. Configure your application settings:
      • Set your preferred app name
      • Review the detected Dockerfile configuration
      • Select a region for deployment
    5. Click Deploy to start the deployment process
    6. Monitor the deployment progress in the dashboard
    7. Wait for the deployment to complete and your app to become active

  9. Configure Environment Variables

    1. In your app dashboard, navigate to Environment Variables section
    2. Add all required variables from your .env.example file:
      • DATABASE_URL: Your PostgreSQL connection string
      • REDIS_URL: Your Redis connection string
      • JWT_SECRET: Generate a secure secret with openssl rand -base64 32
      • API_BASE_URL: Set to https://your-domain.klutch.sh
      • CORS_ORIGIN: Set to https://your-domain.klutch.sh
      • ADMIN_EMAIL and ADMIN_PASSWORD: Your administrator credentials
    3. Click Save to apply the environment variables
    4. Your application will automatically restart with the new configuration

  10. Configure Traffic Routes

    1. In your app dashboard, navigate to Traffic settings
    2. Select HTTP as the traffic type
    3. Set the internal port to 3000 (ChannelTube Node.js server default)
    4. Configure any custom domain settings if you have a domain
    5. Save your traffic configuration

  11. Attach Persistent Volumes for Media Storage

    ChannelTube requires persistent storage for video uploads and database files.

    1. In your app dashboard, navigate to Volumes settings
    2. Click Add Volume to create storage for video uploads:
      • Enter mount path: /app/uploads
      • Set volume size to 100GB or more (adjust based on expected video content)
      • Click Attach to create and mount the volume
    3. Click Add Volume again for database data persistence:
      • Enter mount path: /app/uploads/thumbnails
      • Set volume size to 10GB (for video thumbnails)
      • Click Attach to create and mount the volume
    4. Click Add Volume for application logs:
      • Enter mount path: /app/logs
      • Set volume size to 5GB
      • Click Attach to create and mount the volume

    Your ChannelTube application will now be accessible at your configured domain or at example-app.klutch.sh.

Initial Setup and Configuration

After deploying ChannelTube on Klutch.sh, complete the initial setup to prepare your video platform.

Access Your ChannelTube Instance

  1. Navigate to https://example-app.klutch.sh in your web browser
  2. You’ll see the ChannelTube welcome page
  3. Click Admin Panel or navigate to /admin
  4. Log in with the admin credentials you set in environment variables
  5. Complete the initial setup wizard

Configure Your ChannelTube Instance

Once logged in as an administrator, configure these essential settings:

Platform Settings:

  • Set your platform name and description
  • Configure your site branding and logo
  • Set the default video player resolution
  • Configure transcoding quality options

User Management:

  • Create additional administrator accounts if needed
  • Set user registration policies (open or invite-only)
  • Configure email verification settings
  • Set up user roles and permissions

Video Processing:

  • Enable or disable automatic video transcoding
  • Set maximum file upload size (default: 5GB)
  • Configure thumbnail generation
  • Set video retention policies

Security:

  • Change default admin password immediately
  • Enable HTTPS (automatic with Klutch.sh)
  • Configure CORS origins for API access
  • Set up JWT secret rotation

Set Up Database Backups

To protect your ChannelTube data:

  1. In your app dashboard, navigate to Database settings
  2. Enable automated daily backups
  3. Set backup retention to at least 7 days
  4. Configure backup notifications to your email

Configure External Services (Optional)

Email Configuration:

  • Set up SMTP for user notifications and password resets
  • Configure sender email and display name
  • Test email delivery

CDN Integration:

  • Consider integrating a CDN for video delivery
  • Configure bandwidth settings
  • Set up analytics tracking

Deployment Best Practices

Performance Optimization

  • Allocate sufficient resources for video transcoding (CPU-intensive)
  • Use persistent volumes on high-performance storage
  • Enable Redis caching for improved response times
  • Configure video player to use adaptive bitrate streaming

Security Measures

  • Keep ChannelTube updated to the latest version
  • Regularly rotate JWT secrets
  • Use strong, unique passwords for admin accounts
  • Enable two-factor authentication for administrators
  • Configure firewall rules to restrict access if needed
  • Use HTTPS for all communications (automatic with Klutch.sh)

Monitoring and Maintenance

  • Monitor disk usage for video storage volumes
  • Set up alerts for deployment failures
  • Review logs regularly for errors or security issues
  • Schedule maintenance windows for updates
  • Test backup restoration procedures monthly

Scaling Considerations

As your ChannelTube instance grows:

  • Increase volume sizes proactively before running out of space
  • Distribute video storage across multiple volumes if needed
  • Consider load balancing for high-traffic scenarios
  • Implement video caching strategies
  • Use a dedicated Redis instance for better performance

Accessing ChannelTube

Once deployment is complete and configured:

  1. Users can access your ChannelTube instance at your configured domain
  2. The main interface allows browsing, searching, and watching videos
  3. Registered users can upload content and create channels
  4. Administrators access the admin panel at /admin for management
  5. API endpoints are available at /api for third-party integrations

Troubleshooting Deployment Issues

Application Won’t Start

Check the following:

  • Verify all required environment variables are set
  • Ensure database connection string is correct
  • Check that Redis is accessible
  • Review application logs in the dashboard

Video Upload Fails

Possible solutions:

  • Verify persistent volumes are properly attached
  • Check available disk space on volumes
  • Ensure /app/uploads directory has write permissions
  • Verify file upload size limit in environment variables

Database Connection Errors

Steps to resolve:

  • Verify DATABASE_URL environment variable
  • Ensure database is running and accessible
  • Check database user credentials
  • Verify network connectivity between services

Performance Issues

Optimization steps:

  • Increase application memory allocation
  • Enable Redis caching
  • Configure video transcoding quality appropriately
  • Review and optimize database queries
  • Consider upgrading to higher performance storage

Advanced Configuration

Environment Variables for Customization

You can customize ChannelTube behavior with these environment variables:

Terminal window
# Video Quality Settings
VIDEO_QUALITY_720P=true
VIDEO_QUALITY_1080P=true
VIDEO_QUALITY_4K=false


# Cache Configuration
CACHE_TTL=3600
SESSION_TIMEOUT=86400


# API Rate Limiting
RATE_LIMIT_WINDOW=900
RATE_LIMIT_MAX_REQUESTS=100


# Database Connection Pool
DB_POOL_MIN=2
DB_POOL_MAX=10
DB_IDLE_TIMEOUT=30000


# Feature Flags
ENABLE_COMMENTS=true
ENABLE_RECOMMENDATIONS=true
ENABLE_PLAYLISTS=true
ENABLE_SUBSCRIPTIONS=true

Custom Domain Setup

To use a custom domain with your ChannelTube instance:

  1. In your Klutch.sh dashboard, navigate to Domains
  2. Add your custom domain
  3. Follow the DNS configuration instructions
  4. Update your environment variables with the new domain:
    • API_BASE_URL=https://your-domain.com
    • CORS_ORIGIN=https://your-domain.com
  5. Save and redeploy your application

Database Migration from Other Platforms

If migrating from another video platform:

  1. Export your video data from the source platform
  2. Create a migration script to transform data to ChannelTube format
  3. Run the migration script against your ChannelTube database
  4. Verify all data is correctly imported
  5. Update video file references if necessary

Additional Resources

Learn more about ChannelTube and Klutch.sh:

Conclusion

You now have a fully functional ChannelTube instance running on Klutch.sh! Your self-hosted video streaming platform is ready to handle video uploads, streaming, and user engagement.

With the robust infrastructure provided by Klutch.sh and the flexibility of ChannelTube, you have complete control over your video content and user data. Remember to:

  • Keep your application updated with the latest ChannelTube releases
  • Monitor system performance and storage usage regularly
  • Maintain regular backups of your database and video content
  • Follow security best practices for user authentication
  • Scale your infrastructure as your user base grows

For additional support or questions about deploying ChannelTube on Klutch.sh, refer to the documentation and community resources linked above.