Deploying Ryot

Introduction

Ryot (Roll Your Own Tracker) is a self-hosted platform for tracking media consumption and fitness activities. It serves as a privacy-focused alternative to services like Letterboxd, Goodreads, and MyAnimeList, allowing you to track movies, TV shows, books, anime, manga, games, podcasts, and even workouts.

Built with Rust and a modern React frontend, Ryot provides a comprehensive tracking experience with reviews, ratings, progress tracking, and detailed statistics. The platform integrates with various metadata providers to automatically fetch information about your media.

Key highlights of Ryot:

Multi-Media Tracking: Movies, TV shows, books, anime, manga, games, podcasts, and audiobooks
Fitness Tracking: Log workouts, exercises, and measurements
Reviews and Ratings: Write reviews and rate media on a customizable scale
Progress Tracking: Track reading/watching progress for ongoing media
Collections: Organize media into custom collections
Statistics: Detailed insights into your consumption habits
Import Support: Import from Goodreads, Trakt, MediaTracker, and more
Metadata Providers: Automatic data from TMDB, IGDB, OpenLibrary, and others
GraphQL API: Comprehensive API for custom integrations
Mobile-Friendly: Responsive design for all devices
Multi-User: Support for multiple users with separate libraries
Open Source: Licensed under GPL-3.0

This guide walks through deploying Ryot on Klutch.sh using Docker, configuring metadata providers, and setting up the platform for production use.

Why Deploy Ryot on Klutch.sh

Deploying Ryot on Klutch.sh provides several advantages for personal media tracking:

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

Persistent Storage: Attach persistent volumes for your database and media images. Your tracking history survives container restarts.

HTTPS by Default: Klutch.sh provides automatic SSL certificates, ensuring secure access to your personal data.

GitHub Integration: Connect your configuration repository directly from GitHub. Updates trigger automatic redeployments.

Scalable Resources: Allocate resources based on your tracking volume and user count.

Environment Variable Management: Securely store API keys for metadata providers through Klutch.sh’s environment variable system.

Custom Domains: Assign a custom domain for convenient access to your tracker.

Always-On Availability: Your media tracker runs 24/7, syncing and accessible from anywhere.

Prerequisites

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

A Klutch.sh account
A GitHub account with a repository for your Ryot configuration
Basic familiarity with Docker and containerization concepts
A PostgreSQL database (can be provisioned through Klutch.sh)
(Optional) API keys for metadata providers (TMDB, IGDB, etc.)
(Optional) A custom domain for your Ryot instance

Understanding Ryot Architecture

Ryot is built on a modern, performant stack:

Rust Backend: The server is written in Rust using the Axum framework, providing fast performance and low resource usage.

React Frontend: A React-based single-page application provides the user interface.

PostgreSQL Database: All data is stored in PostgreSQL, including user information, media entries, and reviews.

Background Workers: Scheduled tasks handle metadata updates and maintenance.

GraphQL API: A comprehensive GraphQL API enables custom integrations and third-party apps.

Preparing Your Repository

To deploy Ryot on Klutch.sh, create a GitHub repository containing your Dockerfile.

Repository Structure

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

Creating the Dockerfile

Create a Dockerfile in the root of your repository:

FROM ghcr.io/ignisda/ryot:latest

# The application is configured via environment variables
# All configuration happens through Klutch.sh env vars

# Expose the web port
EXPOSE 8000

Creating the .dockerignore File

Create a .dockerignore file:

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

Environment Variables Reference

Variable	Required	Description
`DATABASE_URL`	Yes	PostgreSQL connection string
`VIDEO_GAMES_TWITCH_CLIENT_ID`	No	IGDB/Twitch client ID for game metadata
`VIDEO_GAMES_TWITCH_CLIENT_SECRET`	No	IGDB/Twitch client secret
`MOVIES_TMDB_ACCESS_TOKEN`	No	TMDB API access token for movie metadata
`SERVER_INSECURE_COOKIE`	No	Set to true if not using HTTPS
`USERS_ALLOW_REGISTRATION`	No	Allow new user registration (true/false)
`SERVER_ADMIN_ACCESS_TOKEN`	No	Token for admin API access

Deploying Ryot on Klutch.sh

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

Obtain Metadata Provider API Keys

For the best experience, obtain API keys:

For TMDB (movies and TV):

Create account at themoviedb.org
Go to Settings → API
Request an API key

For IGDB (games):

Create account at Twitch Developer Portal
Register an application
Note the Client ID and Client Secret

Push Your Repository to GitHub

Initialize your repository and push to GitHub:

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

Provision PostgreSQL

Before deploying Ryot, ensure you have a PostgreSQL database. This can be provisioned through Klutch.sh or an external provider.

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

Configure HTTP Traffic

In the deployment settings:

Select HTTP as the traffic type
Set the internal port to 8000

Set Environment Variables

In the environment variables section, add:

Variable	Value
`DATABASE_URL`	`postgres://user:password@host:5432/ryot`
`VIDEO_GAMES_TWITCH_CLIENT_ID`	Your Twitch Client ID
`VIDEO_GAMES_TWITCH_CLIENT_SECRET`	Your Twitch Client Secret
`MOVIES_TMDB_ACCESS_TOKEN`	Your TMDB access token
`USERS_ALLOW_REGISTRATION`	`true` (for initial setup)

Attach Persistent Volumes

Add volumes for data persistence:

Mount Path	Recommended Size	Purpose
`/data`	10 GB	Cached images and application data

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

Create Your Account

Access your Ryot instance at https://your-app-name.klutch.sh and create your admin account.

Disable Registration (Optional)

After creating your account, update USERS_ALLOW_REGISTRATION to false if you don’t want others to sign up.

Initial Setup and Configuration

Adding Your First Media

Start tracking media:

Use the search feature to find movies, shows, books, or games
Click to add to your library
Set status (watching, completed, planned, etc.)
Add your rating and review

Importing from Other Services

Ryot supports importing from:

Goodreads (books)
Trakt (movies and TV)
MediaTracker
MyAnimeList
Audiobookshelf

Navigate to Settings → Import to begin.

Configuring Metadata Providers

For best results, configure all available providers:

Provider	Media Type
TMDB	Movies, TV Shows
IGDB	Video Games
OpenLibrary	Books
Listennotes	Podcasts
Google Books	Additional book metadata
Audible	Audiobooks
MangaUpdates	Manga
Anilist	Anime, Manga

Features Overview

Media Tracking

Track across categories:

In Progress: Currently consuming
Completed: Finished
On Hold: Paused
Dropped: Abandoned
Planned: Want to consume

Reviews and Ratings

Write detailed reviews with:

Star ratings (customizable scale)
Text reviews
Spoiler protection
Visibility settings

Collections

Organize media with collections:

Create themed collections (e.g., “Favorites”, “To Watch”)
Add descriptions and visibility settings
Share collections publicly or keep private

Fitness Tracking

Track workouts:

Create exercises
Log sets, reps, and weights
Track measurements
View progress over time

Production Best Practices

Security Recommendations

Disable Registration: After setup, disable public registration
Strong Passwords: Use strong passwords for accounts
API Key Protection: Keep metadata provider keys secure
Regular Updates: Keep Ryot updated for security patches

Performance Optimization

PostgreSQL Tuning: Optimize database for your usage patterns
Image Caching: Ensure adequate storage for cached images
Background Jobs: Monitor job queue for issues

Backup Strategy

Database Backup: Regular PostgreSQL dumps
Image Cache: Back up /data directory
Export Data: Use Ryot’s export features periodically

Troubleshooting Common Issues

Metadata Not Loading

Symptoms: Media entries show without cover images or details.

Solutions:

Verify API keys are correct
Check provider service status
Review logs for API errors
Ensure network connectivity to providers

Database Connection Errors

Symptoms: Application fails to start with database errors.

Solutions:

Verify DATABASE_URL format
Ensure PostgreSQL is running and accessible
Check database user permissions

Slow Performance

Symptoms: Pages load slowly or timeout.

Solutions:

Check database query performance
Ensure adequate memory allocation
Review background job queue

Additional Resources

Conclusion

Deploying Ryot on Klutch.sh gives you a comprehensive, self-hosted media tracker with automatic builds, persistent storage, and secure HTTPS access. The combination of Ryot’s feature-rich platform and Klutch.sh’s deployment simplicity means you can focus on tracking your media consumption rather than managing infrastructure.

With support for movies, TV shows, books, games, anime, manga, and even fitness activities, Ryot consolidates your tracking needs into a single, privacy-respecting platform. The automatic metadata fetching and detailed statistics provide insights into your consumption habits.

Whether you’re an avid reader, movie buff, or gaming enthusiast, Ryot on Klutch.sh provides the reliable foundation for comprehensive media tracking without sacrificing privacy.