🎮 TurboVault

Your personal video game collection tracker and manager

TurboVault is a modern, self-hosted web application for tracking and organizing your video game collection. Built with Rails 8 and Hotwire, it offers a fast, responsive experience for managing physical and digital games across all platforms.

✨ Features

• 📚 Track Physical & Digital Games - Manage both formats with detailed metadata
• 🎮 IGDB Integration - Automatic game matching with cover art and metadata
• 📊 Collection Statistics - Track spending, completion rates, and platform distribution
• 🗂️ Collections - Organize games into custom collections
• 🔍 Smart Search - Find games quickly with advanced filtering
• 📥 CSV Import - Bulk import your existing collection
• 🎨 5 Beautiful Themes - Light, Dark, Midnight, Retro, and Ocean
• 🔐 RESTful API - Programmatic access to your collection
• 📍 Location Tracking - Remember where your physical games are stored
• ⭐ Ratings & Status - Track completion status and personal ratings
• 👥 Public Profiles - Optionally share your collection with others

🚀 Quick Start

Prerequisites

• Ruby 3.3+
• PostgreSQL 15+
• Node.js 18+ (for asset compilation)
• Docker (optional, for containerized development)

Local Development

1. Clone the repository

   git clone https://github.com/yourusername/turbovault.git
   cd turbovault
   

2. Install dependencies

   bundle install
   

3. Set up environment variables

   cp .env.example .env
   # Edit .env with your configuration
   

4. Start Docker services

   docker-compose up -d
   

5. Set up the database

   rails db:prepare
   

6. Start the development server

   task dev
   # or: bin/dev
   

7. Visit the app

   • App: http://localhost:3000
   • Mailpit (email testing): http://localhost:8025

Demo Account

A demo account is automatically created in development:

• Email: demo@turbovault.com
• Password: password123

🐳 Docker Deployment

TurboVault includes Docker and Kubernetes manifests for easy deployment.

Kubernetes (Recommended for Production)

TurboVault is designed for Kubernetes with automated GitHub Actions CI/CD.

📖 Documentation:

• ⭐ Quick Start Guide - Deploy in minutes
• Deployment Guide - Complete reference
• Kubernetes README - K8s details

🚀 Quick Deploy:

# 1. Push to GitHub
git push origin main

# 2. Tag a release (triggers automatic build)
git tag v1.0.0 && git push origin v1.0.0

# 3. Configure Kubernetes secrets & manifests
cp k8s/secrets.yaml.example k8s/secrets.yaml
# Edit secrets.yaml, deployment.yaml, configmap.yaml

# 4. Deploy
./scripts/deploy-k8s.sh

See Quick Start Guide for detailed steps.

Docker Compose (Development/Testing)

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

🔧 Configuration

IGDB Integration (Optional)

To enable automatic game metadata matching:

1. Create a Twitch developer account at https://dev.twitch.tv
2. Register an application to get your Client ID and Secret
3. Add to .env:

   IGDB_CLIENT_ID=your_client_id
   IGDB_CLIENT_SECRET=your_client_secret
   

IGDB sync is enabled by default for all users and runs every 30 minutes.

📚 Documentation

All documentation is in the docs/ folder.

Quick Links:

• ⭐ Quick Start - Deploy in minutes
• 🚀 Deployment Guide - Complete reference
• 💻 Development Guide - Local development
• 📖 API Documentation - RESTful API
• 🎮 IGDB Integration - Game metadata
• 🎨 Themes - Customization
• 🎯 Demo Account - Try it out

See all documentation →

🛠️ Tech Stack

• Framework: Ruby on Rails 8.1
• Frontend: Hotwire (Turbo + Stimulus)
• Styling: Tailwind CSS
• Database: PostgreSQL with Row Level Security
• Background Jobs: Solid Queue
• Deployment: Docker, Kubernetes
• APIs: IGDB (game metadata)

🤖 Continuous Integration

TurboVault includes GitHub Actions workflows:

• CI Pipeline - Runs tests, linting, and security scans on every push
• Build & Push - Automatically builds Docker images and pushes to GitHub Container Registry

Setup GitHub Actions

No setup required! The default workflow uses GitHub Container Registry (ghcr.io), which works out of the box with no secrets needed.

Just push a tag:

git tag v1.0.0
git push origin v1.0.0

Your image will be at: ghcr.io/your-username/turbovault:v1.0.0

Want to use a different registry? See .github/SECRETS_SETUP.md for examples (Docker Hub, private registry, etc.)

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

All PRs will automatically run CI tests.

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Game data provided by IGDB
• Built with Ruby on Rails
• UI powered by Tailwind CSS

📧 Support

• 📖 Documentation
• 🐛 Issue Tracker
• 💬 Discussions

---

Made with ❤️ for gamers and collectors