Ganymede Deployment and Usage Guide

1. Prerequisites

System Requirements

• Operating System: Linux environment (Docker-based deployment)
• Storage: Minimum 50GB free space (see Storage Requirements)
• Memory: Sufficient RAM for video processing (recommended 8GB+)
• Network: Stable internet connection for Twitch API access

Required Accounts

• Twitch Developer Account: Create a Twitch application at dev.twitch.tv/console/apps/create
  • You'll need Client ID and Client Secret
• Docker: Docker Engine and Docker Compose installed

Software Dependencies

• Docker Engine 20.10+
• Docker Compose v2+
• PostgreSQL 14+ (included in Docker setup)

2. Installation

Docker Compose Installation (Recommended)

1. Download the docker-compose.yml file:

curl -L https://raw.githubusercontent.com/Zibbp/ganymede/main/docker-compose.yml -o docker-compose.yml

2. Edit the docker-compose.yml file:

   • Modify environment variables as needed (see Configuration section)
   • Adjust volume mounts for persistent storage
   • Set appropriate ports

3. Start Ganymede:

docker compose up -d

4. Initial Setup:
   • Access the web interface at http://localhost:3000 (or your configured port)
   • Login with default credentials:
     • Username: admin
     • Password: ganymede
   • IMPORTANT: Change the admin password immediately or create a new admin user and delete the default one

Docker Image Tags

Choose an appropriate image tag based on your needs:

Rootless Operation

To run the API container as non-root user, add these environment variables:

environment:
  - PUID=1000
  - PGID=1000

Ensure your mounted /data/videos directory has proper permissions for the specified user.

3. Configuration

Environment Variables

Configure these in your docker-compose.yml:

Server Configuration

environment:
  - DEBUG=false  # Enable debug logging
  - VIDEOS_DIR=/data/videos  # Video storage path inside container
  - DATABASE_URL=postgresql://ganymede:password@postgres:5432/ganymede?sslmode=disable
  - TWITCH_CLIENT_ID=your_client_id
  - TWITCH_CLIENT_SECRET=your_client_secret
  - JWT_SECRET=your_secure_jwt_secret
  - FRONTEND_URL=http://localhost:3000
  - API_URL=http://localhost:3001

Database Configuration

environment:
  - POSTGRES_USER=ganymede
  - POSTGRES_PASSWORD=secure_password
  - POSTGRES_DB=ganymede

Configuration File

On first run, Ganymede generates /data/config/config.json. Most settings can be configured via the Web UI at Admin > Settings.

Key configurable settings include:

• Video download quality preferences
• Chat rendering parameters
• FFmpeg post-processing options
• Webhook notifications
• Storage retention policies

Twitch Application Setup

1. Create application at Twitch Developer Console
2. Set OAuth Redirect URL to: {YOUR_FRONTEND_URL}/auth/callback
3. Copy Client ID and Client Secret to environment variables

4. Build & Run

Local Development Build

For development or custom builds:

1. Clone the repository:

git clone https://github.com/Zibbp/ganymede.git
cd ganymede

2. Set up Go environment (requires Go 1.20+):

go mod download

3. Build the server:

go build -o ganymede ./cmd/server

4. Build the frontend:

cd frontend
npm install
npm run build

5. Run with Docker Compose for development:

docker compose -f docker-compose.dev.yml up -d

Production Build

For production deployment, use the pre-built Docker images as shown in the Installation section. Custom builds should only be done if you need specific modifications.

5. Deployment

Docker-Based Deployment (Recommended)

The Docker Compose setup is production-ready. For enhanced production deployments:

1. Use a reverse proxy (nginx, Traefik, Caddy) for SSL termination
2. Configure persistent volumes for database and video storage
3. Set up monitoring (Prometheus, Grafana) for resource tracking
4. Implement backups for PostgreSQL database

Example Production docker-compose.yml Enhancements

services:
  ganymede-api:
    image: ghcr.io/zibbp/ganymede:latest
    restart: unless-stopped
    volumes:
      - /mnt/nas/videos:/data/videos  # Network storage mount
      - ./config:/data/config
      - ./logs:/data/logs
    environment:
      - NODE_ENV=production
    deploy:
      resources:
        limits:
          memory: 4G
        reservations:
          memory: 2G

Platform Recommendations

• Home Server/NAS: Ideal for personal use with Docker
• VPS/Cloud VM: DigitalOcean, Linode, AWS EC2, Google Compute Engine
• Kubernetes: For scalable deployments with multiple users
• Proxmox/LXC: Container-based virtualization

Storage Considerations

• Use network-attached storage (NAS) for large video collections
• Implement a storage retention policy via channel settings
• Monitor disk usage with tools like du or monitoring systems

6. Troubleshooting

Common Issues and Solutions

1. Docker Container Fails to Start

Symptoms: Container exits immediately after starting

Solutions:

# Check container logs
docker compose logs ganymede-api

# Verify environment variables
docker compose config

# Ensure PostgreSQL is accessible
docker compose exec postgres psql -U ganymede -d ganymede

2. Twitch Authentication Failures

Symptoms: Cannot archive streams, API errors

Solutions:

• Verify Twitch Client ID and Secret are correct
• Check that OAuth Redirect URL matches your FRONTEND_URL
• Ensure Twitch application has necessary permissions
• Check API rate limits in Twitch Developer Console

3. Video Download/Processing Failures

Symptoms: Queue items stuck in processing state

Solutions:

# Check processing logs
docker compose logs ganymede-api | grep -i "processing\|ffmpeg"

# Verify storage permissions
docker compose exec ganymede-api ls -la /data/videos

# Check available disk space
docker compose exec ganymede-api df -h

4. Database Connection Issues

Symptoms: "Cannot connect to database" errors

Solutions:

# Test database connectivity
docker compose exec ganymede-api ping postgres

# Check PostgreSQL logs
docker compose logs postgres

# Verify database exists
docker compose exec postgres psql -U ganymede -l

5. Chat Rendering Problems

Symptoms: Chat files not generated or corrupted

Solutions:

• Check chat render parameters in Admin > Settings
• Verify FFmpeg is working in the container
• Ensure sufficient memory for chat processing
• Check chat download logs for Twitch API errors

6. Performance Issues

Symptoms: Slow UI, delayed processing

Solutions:

• Increase container memory limits
• Optimize PostgreSQL with appropriate indexes
• Implement Redis cache (if supported)
• Monitor resource usage: docker stats

Logs and Debugging

Enable debug logging by setting DEBUG=true in environment variables:

docker compose logs -f ganymede-api  # Follow logs in real-time
docker compose exec ganymede-api cat /data/logs/ganymede.log  # View application logs

Recovery Procedures

1. Queue Recovery: Use the recoverable queue system via Admin interface
2. Database Backup: Regular PostgreSQL dumps
3. File Structure: Videos are stored in archival-friendly format at /data/videos/{channel}/{vod_id}/

Getting Help

• Check the GitHub Wiki for detailed documentation
• Review API docs in /docs folder
• Search existing GitHub Issues for similar problems
• Create a new issue with logs and configuration details