ryan/turbovault-app
1
0
Fork 0
mirror of https://github.com/ryankazokas/turbovault-app.git synced 2026-04-16 22:12:53 +00:00
Code Issues Packages Projects Releases Wiki Activity

Condenses Documentation

Browse Source
This commit is contained in:
Ryan Kazokas
2026-03-29 02:55:42 -04:00
parent 323484a33a
commit 55fe839882
14 changed files with 363 additions and 2971 deletions
Download Patch File Download Diff File Expand all files Collapse all files

242
README.md
View File

@@ -1,212 +1,82 @@
# 🎮 TurboVault
> Your personal video game collection tracker and manager
> Your personal video game collection tracker
[![Rails 8.1](https://img.shields.io/badge/Rails-8.1-red.svg)](https://rubyonrails.org/)
![CI](https://github.com/YOUR_USERNAME/turbovault/workflows/CI/badge.svg)
[![RuboCop](https://img.shields.io/badge/code_style-rubocop-brightgreen.svg)](https://github.com/rubocop/rubocop)
[![Sorbet](https://img.shields.io/badge/types-sorbet-blue.svg)](https://sorbet.org)
[![Ruby 3.3](https://img.shields.io/badge/Ruby-3.3-red.svg)](https://www.ruby-lang.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
![CI](https://github.com/ryankazokas/turbovault-app/workflows/CI/badge.svg)
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.
Track your physical and digital game collection with automatic metadata from IGDB.
## ✨ Features
## 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
- 📦 Track physical & digital games
- 🎯 Collections & subcollections
- 🔍 Search, filter, sort
- 📊 Statistics dashboard
- 📥 CSV bulk import
- 🎮 IGDB metadata matching
- 🔌 RESTful API
## 🚀 Quick Start
### Prerequisites
- Ruby 3.3+
- PostgreSQL 15+
- Node.js 18+ (for asset compilation)
- Docker (optional, for containerized development)
## Quick Start
### Local Development
1. **Clone the repository**
```bash
git clone https://github.com/yourusername/turbovault.git
cd turbovault
```
2. **Install dependencies**
```bash
bundle install
```
3. **Set up environment variables**
```bash
cp .env.example .env
# Edit .env with your configuration
```
4. **Start Docker services**
```bash
docker-compose up -d
```
5. **Set up the database**
```bash
rails db:prepare
```
6. **Start the development server**
```bash
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](docs/QUICK_START.md) - Deploy in minutes
- [Deployment Guide](docs/DEPLOYMENT.md) - Complete reference
- [Kubernetes README](k8s/README.md) - K8s details
**🚀 Quick Deploy:**
```bash
# 1. Push to GitHub
git push origin main
# Start services
task docker:up
# 2. Tag a release (triggers automatic build)
# Setup database
task db:setup
# Run server
task dev
```
Visit http://localhost:3000
**Demo:** demo@turbovault.com / password123
### Deploy to Kubernetes
```bash
# 1. Build & push image
git tag v1.0.0 && git push origin v1.0.0
# 3. Configure Kubernetes secrets & manifests
# 2. Configure secrets
cp k8s/secrets.yaml.example k8s/secrets.yaml
# Edit secrets.yaml, deployment.yaml, configmap.yaml
# Edit with your values
# 4. Deploy
# 3. Deploy
./scripts/deploy-k8s.sh
```
See [Quick Start Guide](docs/QUICK_START.md) for detailed steps.
See [docs/QUICK_START.md](docs/QUICK_START.md) for details.
### Docker Compose (Development/Testing)
## Tech Stack
- Ruby on Rails 8.1 with Sorbet types
- PostgreSQL with Row Level Security
- Hotwire (Turbo + Stimulus)
- Tailwind CSS
- Solid Queue for background jobs
## Documentation
- [Quick Start](docs/QUICK_START.md) - Getting started guide
- [Development](docs/DEVELOPMENT_GUIDE.md) - Local development
- [API Docs](docs/API_DOCUMENTATION.md) - RESTful API reference
- [Deployment](docs/DEPLOYMENT.md) - Production deployment
## Commands
```bash
docker-compose -f docker-compose.prod.yml up -d
task dev # Start dev server
task test # Run tests
task lint # Check code style
task lint:fix # Auto-fix style issues
task typecheck # Run type checker
```
## 🔧 Configuration
## License
### 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`:
```bash
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/`](docs/) folder.**
**Quick Links:**
- ⭐ [Quick Start](docs/QUICK_START.md) - Deploy in minutes
- 🚀 [Deployment Guide](docs/DEPLOYMENT.md) - Complete reference
- 💻 [Development Guide](docs/DEVELOPMENT_GUIDE.md) - Local development
- 📖 [API Documentation](docs/API_DOCUMENTATION.md) - RESTful API
- 🎮 [IGDB Integration](docs/IGDB_INTEGRATION.md) - Game metadata
- 🎨 [Themes](docs/THEMES.md) - Customization
- 🔷 [Sorbet Types](docs/SORBET.md) - Type checking guide
- 🎯 [Demo Account](docs/DEMO_ACCOUNT.md) - Try it out
[**See all documentation →**](docs/README.md)
## 🛠️ Tech Stack
- **Framework:** Ruby on Rails 8.1 with Sorbet type checking
- **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:
```bash
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](.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](LICENSE) file for details.
## 🙏 Acknowledgments
- Game data provided by [IGDB](https://www.igdb.com/)
- Built with [Ruby on Rails](https://rubyonrails.org/)
- UI powered by [Tailwind CSS](https://tailwindcss.com/)
## 📧 Support
- 📖 [Documentation](docs/)
- 🐛 [Issue Tracker](https://github.com/yourusername/turbovault/issues)
- 💬 [Discussions](https://github.com/yourusername/turbovault/discussions)
---
Made with ❤️ for gamers and collectors
MIT - See [LICENSE](LICENSE)