Deploying Gameyfin

Introduction

Gameyfin is a self-hosted video game library manager that transforms your disorganized collection of game files into a beautiful, navigable library accessible from any web browser. Inspired by Jellyfin, Gameyfin automatically scans your game folders, downloads metadata and cover images from various sources, and presents everything through a user-friendly interface.

Built with Kotlin and Spring Boot 3 on the backend, with Vaadin Hilla and React powering the frontend, Gameyfin v2 offers a complete rewrite with modern architecture and an extensible plugin system. The application uses an embedded H2 database for persistence, making it lightweight and easy to deploy without external database dependencies.

Key highlights of Gameyfin:

Automatic Library Scanning: Point Gameyfin at your game folders and watch it automatically index and organize your collection
Metadata Fetching: Automatically downloads game information, cover art, and screenshots from multiple sources
Multi-User Support: Share your library with friends and family, each with their own accounts and permissions
LAN-Friendly: Everything is cached locally (except videos), making it perfect for local network deployments
Plugin Architecture: Extend functionality with plugins using the PF4J framework
SSO Integration: Supports OAuth2 and OpenID Connect for enterprise authentication
Theme Support: Multiple themes including colorblind accessibility options
Direct Downloads: Users can download game files directly from the web interface
100% Open Source: Licensed under AGPL-3.0 with no paywalls or premium features

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

Why Deploy Gameyfin on Klutch.sh

Deploying Gameyfin on Klutch.sh provides several advantages for managing your video game library:

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

Persistent Storage: Attach persistent volumes for your game library, database, and metadata. Your collection and configurations survive container restarts and redeployments without data loss.

HTTPS by Default: Klutch.sh provides automatic SSL certificates, ensuring secure access to your game library 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 library size and expected traffic. Start small and scale up as your collection grows.

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

Custom Domains: Assign a custom domain to your Gameyfin instance for a professional, branded experience when sharing with friends and family.

Always-On Availability: Your game library remains accessible 24/7 without managing your own hardware or dealing with home network configuration.

Prerequisites

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

A Klutch.sh account
A GitHub account with a repository for your Gameyfin configuration
Basic familiarity with Docker and containerization concepts
Your video game library files ready to upload or a plan for syncing them
(Optional) A custom domain for your Gameyfin instance

Understanding Gameyfin Architecture

Gameyfin v2 is built on a modern stack designed for reliability and extensibility:

Spring Boot 3 Backend: The core application runs on Spring Boot 3, providing a robust foundation for the REST API and server-side logic. The JVM-based architecture ensures cross-platform compatibility.

Vaadin Hilla Frontend: The web interface uses Vaadin Hilla with React, delivering a responsive single-page application experience that works seamlessly across devices.

H2 Embedded Database: Gameyfin uses an embedded H2 database for persistence, eliminating the need for external database services. The database file is stored in the /opt/gameyfin/db directory.

PF4J Plugin System: The plugin architecture allows extending Gameyfin with custom metadata providers, download handlers, and other functionality. Plugins are stored in /opt/gameyfin/plugindata.

File-Based Configuration: Most configuration happens through the web interface after initial setup, with the database storing user preferences and library settings.

Preparing Your Repository

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

Repository Structure

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

Creating the Dockerfile

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

FROM ghcr.io/gameyfin/gameyfin:2

# Set environment variables
# APP_KEY is required - generate with: openssl rand -base64 32
ENV APP_KEY=${APP_KEY}

# Optional: Set the external URL for your Gameyfin instance
# Required when using a reverse proxy
ENV APP_URL=${APP_URL}

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

# Create directories for game libraries
RUN mkdir -p /games

# Expose the web interface port
EXPOSE 8080

# 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/gameyfin/gameyfin:2

# Required environment variable for encryption
ENV APP_KEY=${APP_KEY}

# Optional URL configuration for reverse proxy setups
ENV APP_URL=${APP_URL}

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

# Create necessary directories
RUN mkdir -p /games /games/pc /games/console /games/retro

# Set proper permissions
RUN chmod -R 755 /games

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

# Expose the application port
EXPOSE 8080

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

Gameyfin v2 requires minimal environment configuration compared to v1:

Variable	Required	Default	Description
`APP_KEY`	Yes	-	Encryption key for sensitive database data. Generate with `openssl rand -base64 32`. Must be 16, 24, or 32 bytes Base64 encoded.
`APP_URL`	No	-	External URL of your Gameyfin instance (e.g., `https://gameyfin.example.com`). Set this when using a reverse proxy.
`PUID`	No	1000	User ID for running the application and file ownership
`PGID`	No	1000	Group ID for running the application and file ownership

Deploying Gameyfin on Klutch.sh

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

Generate Your APP_KEY

Before deployment, generate a secure encryption key for Gameyfin:

openssl rand -base64 32

Save this key securely—you’ll need it for the environment variables configuration. This key encrypts sensitive data in the database and must remain consistent across deployments.

Push Your Repository to GitHub

Initialize your repository and push to GitHub:

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

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

Configure HTTP Traffic

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

Select HTTP as the traffic type
Set the internal port to 8080 (Gameyfin’s default port)

Set Environment Variables

In the environment variables section, add the following:

Variable	Value
`APP_KEY`	Your generated Base64 key from step 1
`APP_URL`	`https://your-app-name.klutch.sh` (replace with your actual app URL)
`PUID`	`1000` (or your preferred user ID)
`PGID`	`1000` (or your preferred group ID)

Attach Persistent Volumes

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

Mount Path	Recommended Size	Purpose
`/opt/gameyfin/db`	1 GB	SQLite database storing configuration, users, and library metadata
`/opt/gameyfin/data`	10 GB	Application data, thumbnails, and cached images
`/opt/gameyfin/plugindata`	1 GB	Plugin data and configurations
`/opt/gameyfin/logs`	1 GB	Application logs
`/games`	100+ GB	Your game library files (adjust based on collection size)

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

Access Gameyfin

Once deployment completes, access your Gameyfin instance at https://your-app-name.klutch.sh. The first-time setup wizard will guide you through initial configuration.

Initial Setup and Configuration

First-Time Setup Wizard

When you first access your Gameyfin instance, you’ll be greeted with a setup wizard:

Theme Selection: Choose your preferred visual theme, including colorblind-accessible options
Admin Account Creation: Create your administrator account with a secure password
Completion: Click through to finish the initial setup

Configuring Plugins

Gameyfin’s functionality is extended through plugins. After logging in:

Click on your avatar in the top-right corner to access admin settings
Navigate to the Plugins section
Review the available plugins and their documentation
Enable plugins by clicking the On/Off toggle
Configure each plugin by clicking the Configure button
Set plugin priority to determine metadata search order

Available plugin categories include:

Metadata Providers: Fetch game information and cover art from various sources
Download Providers: Configure how users can download game files
Authentication: SSO integrations via OAuth2/OpenID Connect

Adding Your Game Library

To add your game collection:

Navigate to Libraries in the admin interface
Click Add Library at the bottom of the page
Add one or more source folders pointing to your mounted game directories (e.g., /games/pc, /games/console)
Configure library settings by clicking Configure
Let Gameyfin scan and index your games

Recommended Directory Structure

Organize your games for optimal metadata detection:

/games/
├── pc/
│   ├── Action/
│   │   ├── Game Name (Year)/
│   │   │   ├── game.exe
│   │   │   └── cover.jpg
│   │   └── Another Game/
│   └── RPG/
│       └── RPG Title/
├── console/
│   └── Nintendo Switch/
│       └── Game Title/
└── retro/
    └── SNES/
        └── Game.rom

Using a consistent naming convention with the game name and optionally the release year helps Gameyfin match games with their metadata accurately.

User Management

Creating Additional Users

Share your library with friends and family:

Go to Settings → Users
Click Create User
Set username, password, and permissions
Assign library access

User Permissions

Control what each user can do:

Permission	Description
Admin	Full access to all settings and libraries
User	Can browse and download from assigned libraries
Guest	View-only access to library contents

SSO Integration

Gameyfin supports enterprise authentication through OAuth2 and OpenID Connect:

Navigate to Configuration → SSO
Configure your identity provider settings
Set up redirect URIs in your IdP
Test the authentication flow

Compatible identity providers include:

Authentik
Keycloak
Pocket-ID
Any OAuth2/OIDC-compliant provider

Torrent Plugin Configuration

Gameyfin includes an optional torrent plugin for peer-to-peer sharing:

Note: The torrent functionality requires additional TCP ports that may not be available in all deployment scenarios. The default ports are:

Port 6969: BitTorrent tracker
Port 6881: Torrent client

For Klutch.sh deployments, HTTP-based download methods are recommended over the torrent plugin.

Uploading Games to Your Library

Since Gameyfin needs access to your game files, you’ll need to transfer them to your persistent volume. Options include:

Using SFTP/SCP: If you have direct access to your storage volume, use secure file transfer protocols to upload your collection.

Web Upload Tools: Deploy a companion file manager application alongside Gameyfin for web-based uploads.

Pre-populated Volume: Prepare your game library locally and upload the complete volume during initial setup.

Cloud Sync: Use tools like rclone to synchronize your local game library with your Klutch.sh persistent storage.

Production Best Practices

Security Recommendations

Secure APP_KEY: Store your encryption key securely and never commit it to version control. Use Klutch.sh environment variables.
Strong Passwords: Enforce strong passwords for all user accounts, especially administrators.
Regular Updates: Keep your Gameyfin image updated to receive security patches. Pin to major versions (e.g., ghcr.io/gameyfin/gameyfin:2) while allowing minor updates.
SSO Integration: For organizations, use SSO to centralize authentication and leverage existing security policies.
Access Control: Limit admin accounts and use appropriate user permissions.

Performance Optimization

Volume Sizing: Allocate sufficient storage for your game library. Games can range from megabytes to hundreds of gigabytes each.
Metadata Caching: Gameyfin caches metadata locally, so ensure adequate space in /opt/gameyfin/data.
Resource Allocation: For large libraries (1000+ games), allocate additional CPU and memory resources.
Plugin Selection: Enable only the plugins you need to reduce resource usage.

Backup Strategy

Protect your configuration and metadata:

Database Backups: Regularly back up /opt/gameyfin/db containing your H2 database
Configuration Export: Export plugin configurations through the web interface
User Data: Back up user accounts and permissions
Library Metadata: While metadata can be re-fetched, backing up /opt/gameyfin/data saves time

Monitoring and Logging

Accessing Logs

View application logs through multiple methods:

Web Interface: Navigate to Configuration → Logs in the admin panel
Persistent Storage: Logs are stored in /opt/gameyfin/logs
Klutch.sh Dashboard: View build and runtime logs in your app’s dashboard

Log Levels

Configure logging verbosity for troubleshooting:

ERROR: Critical issues requiring attention
WARNING: Potential problems that may need investigation
INFO: General application events and status
DEBUG: Detailed diagnostic information

Troubleshooting Common Issues

Application Won’t Start

Symptoms: Container exits immediately or fails health checks.

Solutions:

Verify APP_KEY is set and is a valid 32-byte Base64 string
Check that all required volumes are mounted with correct permissions
Review startup logs for specific error messages
Ensure port 8080 is not conflicting with other services

Library Not Scanning

Symptoms: Games don’t appear after adding a library.

Solutions:

Verify the mount path matches your library configuration
Check file permissions (PUID/PGID settings)
Ensure game files are in a supported format
Review scanner logs for errors

Metadata Not Loading

Symptoms: Games appear but without cover art or descriptions.

Solutions:

Enable and configure metadata provider plugins
Check plugin priority order
Verify network connectivity to metadata sources
Manually trigger a metadata refresh for affected games

Cannot Access Web Interface

Symptoms: Browser cannot connect to Gameyfin.

Solutions:

Verify the deployment is running in the Klutch.sh dashboard
Confirm HTTP traffic type is selected with port 8080
Check that APP_URL matches your actual deployment URL
Clear browser cache and try incognito mode

Authentication Issues

Symptoms: Cannot log in or SSO not working.

Solutions:

Reset admin password through database if locked out
Verify SSO configuration matches your identity provider
Check redirect URIs are correctly configured
Review authentication plugin logs

Updating Gameyfin

To update to a newer version of Gameyfin:

Back Up Data: Export your database and configuration
Update Dockerfile: Change the image tag if pinning to a specific version
Push Changes: Commit and push to trigger redeployment
Verify: Test the updated instance and check logs for migration messages

The Gameyfin team provides migration guides for major version upgrades in their documentation.

Additional Resources

Conclusion

Deploying Gameyfin on Klutch.sh gives you a powerful, self-hosted game library manager with automatic builds, persistent storage, and secure HTTPS access. The combination of Gameyfin’s feature-rich interface and Klutch.sh’s deployment simplicity means you can focus on organizing and enjoying your game collection rather than managing infrastructure.

With support for multiple users, extensible plugins, and SSO integration, Gameyfin scales from personal use to sharing with friends and family. The automatic metadata fetching and beautiful presentation transform a folder of game files into a browsable, searchable library accessible from any web browser.

Whether you’re cataloging a modest collection of indie titles or managing hundreds of games across multiple platforms, Gameyfin on Klutch.sh provides the foundation for a reliable, always-available game library that you control.