Deploying Ganymede

Introduction

Ganymede is a Twitch VOD and Live Stream archiving platform that includes a rendered and real-time chat experience for each archive. This self-hosted solution allows you to preserve Twitch content along with the complete chat replay, ensuring streams are never lost even after they’re removed from Twitch.

Built with Go and React, Ganymede provides a modern web interface for browsing archived content while leveraging powerful backend tools for video downloading and chat rendering. The platform supports automatic archiving of live streams and manual VOD archiving.

Key highlights of Ganymede:

• VOD Archiving: Download and preserve Twitch VODs before they expire or are deleted
• Live Stream Recording: Automatically record live streams as they happen
• Chat Preservation: Archive chat messages and render them alongside video playback
• Real-time Chat Replay: Watch archived streams with synchronized chat replay
• Channel Management: Follow multiple channels and archive their content
• Queue System: Manage multiple archive jobs with priority queuing
• Web Interface: Modern, responsive UI for browsing and watching archives
• API Access: REST API for integration with other tools and automation
• Multi-user Support: User authentication and access control
• Open Source: Licensed under GPL-3.0

This guide walks through deploying Ganymede on Klutch.sh using Docker, configuring persistent storage for your video archives, and setting up the platform for production use.

Why Deploy Ganymede on Klutch.sh

Deploying Ganymede on Klutch.sh provides several advantages for archiving Twitch content:

Simplified Deployment: Klutch.sh automatically detects your Dockerfile and builds Ganymede without complex orchestration or manual server configuration. Push to GitHub, and your archive platform deploys automatically.

Persistent Storage: Attach persistent volumes for your video archives, database, and temporary files. Your archived content survives container restarts and redeployments without data loss.

HTTPS by Default: Klutch.sh provides automatic SSL certificates, ensuring secure access to your archive platform from anywhere without manual certificate management.

GitHub Integration: Connect your configuration repository directly from GitHub. Updates to your Dockerfile trigger automatic redeployments, keeping your deployment in sync with your repository.

Scalable Resources: Allocate CPU and memory based on your archive needs. Video processing requires significant resources, and Klutch.sh allows you to scale accordingly.

Environment Variable Management: Securely store sensitive configuration like Twitch API credentials through Klutch.sh’s environment variable system without exposing credentials in your repository.

Custom Domains: Assign a custom domain to your Ganymede instance for easy access to your personal archive.

Always-On Availability: Your archive platform remains accessible 24/7 for recording live streams without managing your own hardware.

Prerequisites

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

• A Klutch.sh account
• A GitHub account with a repository for your Ganymede configuration
• Basic familiarity with Docker and containerization concepts
• A Twitch Developer Application for API access
• A PostgreSQL database (see PostgreSQL deployment guide)
• At least 50 GB of storage space (more recommended for extensive archives)
• (Optional) A custom domain for your Ganymede instance

Understanding Ganymede Architecture

Ganymede is built on a modern stack optimized for video archiving and playback:

Go Backend: The core application is written in Go, providing efficient handling of video processing tasks and API requests.

React Frontend: The web interface uses React for a responsive, modern user experience when browsing and watching archived content.

PostgreSQL Database: Ganymede uses PostgreSQL for storing metadata about archived videos, channels, and user accounts.

Video Processing: The platform integrates with tools like FFmpeg and TwitchDownloader for video downloading and chat rendering.

Queue System: A job queue manages archive tasks, ensuring efficient processing without overwhelming system resources.

Preparing Your Repository

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

Repository Structure

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

Creating the Dockerfile

Create a Dockerfile in the root of your repository. This example uses the official Ganymede image:

FROM ghcr.io/zibbp/ganymede:latest

# Set environment variables
ENV GIN_MODE=release

# Set user/group IDs for file permissions
ENV PUID=${PUID:-1000}
ENV PGID=${PGID:-1000}

# Create directories for archives
RUN mkdir -p /data/videos /data/temp

# Expose the web interface port
EXPOSE 4000

# The base image includes the default entrypoint

Advanced Dockerfile with Custom Configuration

For more control over your deployment, use this extended Dockerfile:

FROM ghcr.io/zibbp/ganymede:latest

# Set production environment
ENV GIN_MODE=release

# User/Group IDs for proper file permissions
ENV PUID=${PUID:-1000}
ENV PGID=${PGID:-1000}

# Timezone configuration
ENV TZ=${TZ:-UTC}

# Create necessary directories
RUN mkdir -p /data/videos /data/temp /data/logs

# Set proper permissions
RUN chmod -R 755 /data

# Health check to verify application is running
HEALTHCHECK --interval=30s --timeout=10s --start-period=120s --retries=3 \
  CMD wget --no-verbose --tries=1 --spider http://localhost:4000/health || exit 1

# Expose the application port
EXPOSE 4000

Creating the .dockerignore File

Create a .dockerignore file to exclude unnecessary files from the build:

.git
.github
*.md
README.md
LICENSE
.gitignore
*.log
.DS_Store
node_modules/
.env
.env.local

Environment Variables Reference

Ganymede requires several environment variables for proper operation:

Variable	Required	Default	Description
DB_HOST	Yes	-	PostgreSQL database host
DB_PORT	Yes	5432	PostgreSQL database port
DB_USER	Yes	-	PostgreSQL username
DB_PASS	Yes	-	PostgreSQL password
DB_NAME	Yes	ganymede	PostgreSQL database name
DB_SSL	No	disable	SSL mode for database connection
TWITCH_CLIENT_ID	Yes	-	Twitch application client ID
TWITCH_CLIENT_SECRET	Yes	-	Twitch application client secret
VIDEOS_DIR	Yes	/data/videos	Directory for archived videos
TEMP_DIR	Yes	/data/temp	Temporary directory for processing
LOGS_DIR	No	/data/logs	Directory for application logs
PUID	No	1000	User ID for file permissions
PGID	No	1000	Group ID for file permissions
TZ	No	UTC	Container timezone

Deploying Ganymede on Klutch.sh

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

Create a Twitch Developer Application

Before deployment, create a Twitch application for API access:

1. Go to the Twitch Developer Console
2. Click Register Your Application
3. Fill in the application details:
   • Name: Your application name
   • OAuth Redirect URLs: https://your-app-name.klutch.sh/auth/callback
   • Category: Application Integration
4. Save your Client ID and generate a Client Secret

Set Up PostgreSQL Database

Ganymede requires PostgreSQL for data storage. Deploy a PostgreSQL instance on Klutch.sh following the PostgreSQL deployment guide. Note your database credentials.

Push Your Repository to GitHub

Initialize your repository and push to GitHub:

git init
git add Dockerfile .dockerignore README.md
git commit -m "Initial Ganymede deployment configuration"
git remote add origin https://github.com/yourusername/ganymede-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 “ganymede” or “twitch-archive”.

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

Configure HTTP Traffic

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

• Select HTTP as the traffic type
• Set the internal port to 4000 (Ganymede’s default port)

Set Environment Variables

In the environment variables section, add the following:

Variable	Value
DB_HOST	Your PostgreSQL host
DB_PORT	5432
DB_USER	Your database username
DB_PASS	Your database password
DB_NAME	ganymede
DB_SSL	disable
TWITCH_CLIENT_ID	Your Twitch client ID
TWITCH_CLIENT_SECRET	Your Twitch client secret
VIDEOS_DIR	/data/videos
TEMP_DIR	/data/temp
PUID	1000
PGID	1000
TZ	Your timezone (e.g., America/New_York)

Attach Persistent Volumes

Persistent storage is essential for Ganymede. Add the following volumes:

Mount Path	Recommended Size	Purpose
/data/videos	100+ GB	Archived video files (adjust based on needs)
/data/temp	50 GB	Temporary files during video processing
/data/logs	1 GB	Application logs

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

Access Ganymede

Once deployment completes, access your Ganymede instance at https://your-app-name.klutch.sh. Log in with the default credentials (username: admin, password: ganymede) and change them immediately.

Initial Setup and Configuration

First-Time Login

When you first access Ganymede:

1. Log in with default credentials: admin / ganymede
2. Immediately change the admin password in Settings → Account
3. Configure your preferences

Adding Channels

To start archiving Twitch content:

1. Navigate to Channels in the sidebar
2. Click Add Channel
3. Enter the Twitch channel username
4. Configure archive settings:
   • Auto-archive VODs
   • Auto-archive live streams
   • Chat recording preferences
5. Save the channel configuration

Archiving VODs

To manually archive a VOD:

1. Go to Queue → Add to Queue
2. Enter the VOD URL or ID
3. Configure quality settings
4. Add to queue for processing

Live Stream Recording

Enable automatic live stream recording:

1. Go to Channels and select a channel
2. Enable Watch Live
3. Configure quality preferences
4. Ganymede will automatically record when the channel goes live

User Management

Creating Users

Add additional users to your Ganymede instance:

1. Go to Settings → Users
2. Click Create User
3. Set username, password, and role
4. Assign appropriate permissions

User Roles

Role	Permissions
Admin	Full access to all features and settings
Editor	Can add channels and manage archives
User	Can view and watch archived content

Production Best Practices

Storage Planning

Video archives require significant storage:

• VOD Size: Varies by quality and length (1 hour at 1080p = ~2-4 GB)
• Live Recordings: Can be very large for long streams
• Plan Ahead: Allocate storage based on your archiving goals

Resource Allocation

Video processing is resource-intensive:

• CPU: Allocate sufficient CPU for transcoding tasks
• Memory: At least 4 GB recommended for smooth operation
• Concurrent Jobs: Limit concurrent archive jobs based on resources

Security Recommendations

• Change Default Password: Immediately change the admin password
• Strong Passwords: Enforce strong passwords for all users
• API Credentials: Keep Twitch API credentials secure
• Regular Updates: Keep Ganymede updated for security patches

Backup Strategy

Protect your archived content:

1. Database Backups: Regularly back up your PostgreSQL database
2. Video Backups: Consider backing up critical archived videos
3. Configuration: Document your settings for disaster recovery

Troubleshooting Common Issues

Videos Not Downloading

Symptoms: Archive jobs fail or hang.

Solutions:

• Verify Twitch API credentials are correct
• Check available storage space
• Ensure TEMP_DIR has write permissions
• Review job logs for specific errors

Application Won’t Start

Symptoms: Container exits immediately or fails health checks.

Solutions:

• Verify database connection settings
• Check that all required environment variables are set
• Review startup logs for specific error messages
• Ensure PostgreSQL is running and accessible

Chat Not Rendering

Symptoms: Videos play but chat doesn’t appear.

Solutions:

• Check that chat recording is enabled for the channel
• Verify chat rendering completed successfully
• Check TwitchDownloader integration

Storage Running Low

Symptoms: Archive jobs fail with disk space errors.

Solutions:

• Increase persistent volume size
• Delete old or unwanted archives
• Configure automatic cleanup policies

Additional Resources

• Ganymede GitHub Repository
• Ganymede Wiki
• Twitch Developer Portal
• Klutch.sh PostgreSQL Guide
• Klutch.sh Persistent Volumes
• Klutch.sh Deployments

Conclusion

Deploying Ganymede on Klutch.sh gives you a powerful Twitch archiving platform with automatic builds, persistent storage, and secure HTTPS access. The combination of Ganymede’s feature-rich archiving capabilities and Klutch.sh’s deployment simplicity means you can focus on preserving the content you care about rather than managing infrastructure.

With support for VOD archiving, live stream recording, and chat preservation, Ganymede ensures your favorite Twitch moments are never lost. Whether you’re archiving content from a single channel or building a comprehensive library of streams, Ganymede on Klutch.sh provides the foundation for a reliable, always-available archive platform.