From 63276ef8ca2b61270d398f9f733ff4ba1dcff9c6 Mon Sep 17 00:00:00 2001 From: Ryan Kazokas Date: Sat, 28 Mar 2026 19:30:27 -0400 Subject: [PATCH] Removes verbose docs --- DOCS_REORGANIZED.md | 102 ------ README.md | 44 ++- REGISTRY_SIMPLIFIED.md | 179 ---------- SECURITY_SCAN_RESULTS.md | 102 ------ docs/DEPLOYMENT.md | 18 +- docs/DEPLOYMENT_CHECKLIST.md | 244 ------------- docs/EMAIL_SETUP_SUMMARY.md | 253 -------------- docs/GITHUB_ACTIONS_SETUP.md | 326 ------------------ docs/GITHUB_DEPLOYMENT_SUMMARY.md | 306 ---------------- docs/IMPLEMENTATION_COMPLETE.md | 402 ---------------------- docs/PROJECT_SUMMARY.md | 414 ---------------------- docs/README.md | 128 +------ docs/REQUIREMENTS.md | 555 ------------------------------ docs/TESTING_EMAILS.md | 274 --------------- 14 files changed, 51 insertions(+), 3296 deletions(-) delete mode 100644 DOCS_REORGANIZED.md delete mode 100644 REGISTRY_SIMPLIFIED.md delete mode 100644 SECURITY_SCAN_RESULTS.md delete mode 100644 docs/DEPLOYMENT_CHECKLIST.md delete mode 100644 docs/EMAIL_SETUP_SUMMARY.md delete mode 100644 docs/GITHUB_ACTIONS_SETUP.md delete mode 100644 docs/GITHUB_DEPLOYMENT_SUMMARY.md delete mode 100644 docs/IMPLEMENTATION_COMPLETE.md delete mode 100644 docs/PROJECT_SUMMARY.md delete mode 100644 docs/REQUIREMENTS.md delete mode 100644 docs/TESTING_EMAILS.md diff --git a/DOCS_REORGANIZED.md b/DOCS_REORGANIZED.md deleted file mode 100644 index a8b18d1..0000000 --- a/DOCS_REORGANIZED.md +++ /dev/null @@ -1,102 +0,0 @@ -# 📁 Documentation Reorganized - -All markdown documentation has been moved to the `docs/` folder for better organization! - -## What Changed - -### Before: -``` -turbovault-web/ -├── README.md -├── LICENSE -├── API_DOCUMENTATION.md -├── DEPLOYMENT.md -├── DEPLOYMENT_CHECKLIST.md -├── DEVELOPMENT_GUIDE.md -├── GITHUB_ACTIONS_SETUP.md -├── IGDB_INTEGRATION.md -├── THEMES.md -└── ... (12+ more .md files in root) -``` - -### After: -``` -turbovault-web/ -├── README.md # Main README (updated with new links) -├── LICENSE -│ -├── docs/ # 📁 All documentation here! -│ ├── README.md # Documentation index -│ ├── API_DOCUMENTATION.md -│ ├── DEPLOYMENT.md -│ ├── DEPLOYMENT_CHECKLIST.md -│ ├── DEVELOPMENT_GUIDE.md -│ ├── GITHUB_ACTIONS_SETUP.md -│ ├── IGDB_INTEGRATION.md -│ ├── THEMES.md -│ └── ... (all other docs) -│ -├── .github/ -│ ├── workflows/ -│ ├── SECRETS_SETUP.md -│ └── WHAT_TO_COMMIT.md -│ -└── k8s/ - ├── README.md - ├── GITEA_SETUP.md - └── *.yaml -``` - -## ✅ All Links Updated - -- ✅ Main `README.md` - Points to `docs/` folder -- ✅ All files in `docs/` - Cross-references updated -- ✅ Relative paths fixed: - - Same folder: `[link](FILENAME.md)` - - Root: `[link](../README.md)` - - .github: `[link](../.github/FILENAME.md)` - - k8s: `[link](../k8s/FILENAME.md)` - -## 📖 Quick Access - -**Main Documentation Index:** [docs/README.md](docs/README.md) - -**Most Important Docs:** -- [Deployment Checklist](docs/DEPLOYMENT_CHECKLIST.md) - Start here for deployment -- [GitHub Actions Setup](docs/GITHUB_ACTIONS_SETUP.md) - CI/CD pipeline -- [Development Guide](docs/DEVELOPMENT_GUIDE.md) - Local development -- [API Documentation](docs/API_DOCUMENTATION.md) - API reference - -## 🎯 Why This Change? - -**Benefits:** -- ✅ Cleaner root directory -- ✅ Easier to find documentation -- ✅ Standard project structure -- ✅ Better organization -- ✅ Easier to maintain - -**GitHub Standard:** -Most open-source projects keep documentation in a `docs/` folder, with only `README.md` and `LICENSE` in the root. - -## 🔗 Updated Files - -The following files have been updated with new paths: - -1. **README.md** - Links to docs/ folder -2. **docs/*.md** - All cross-references updated -3. **docs/README.md** - NEW: Documentation index - -No code changes, only documentation organization! - -## ✨ Everything Still Works - -All documentation is accessible and all links work correctly. Just: - -- Visit [docs/README.md](docs/README.md) for the documentation index -- Or access files directly in the `docs/` folder -- Main README still has quick links to key documents - ---- - -**Ready to commit?** All documentation is organized and ready for GitHub! 🚀 diff --git a/README.md b/README.md index fd0cf6d..69399eb 100644 --- a/README.md +++ b/README.md @@ -80,34 +80,33 @@ A demo account is automatically created in development: TurboVault includes Docker and Kubernetes manifests for easy deployment. -### 📋 New to Deployment? - -**Start here:** [DEPLOYMENT_CHECKLIST.md](docs/DEPLOYMENT_CHECKLIST.md) - Complete step-by-step deployment guide - ### Kubernetes (Recommended for Production) -TurboVault is designed for Kubernetes with GitHub Actions CI/CD: +TurboVault is designed for Kubernetes with automated GitHub Actions CI/CD. -**Documentation:** -1. **📋 Deployment Checklist:** [DEPLOYMENT_CHECKLIST.md](docs/DEPLOYMENT_CHECKLIST.md) - Step-by-step guide -2. **🤖 GitHub Actions:** [GITHUB_ACTIONS_SETUP.md](docs/GITHUB_ACTIONS_SETUP.md) - Automated builds -3. **☸️ Kubernetes Guide:** [k8s README](k8s/README.md) - Full k8s documentation +**📖 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:** +**🚀 Quick Deploy:** ```bash # 1. Push to GitHub -./scripts/setup-github.sh +git push origin main -# 2. Build image (automatic on tag push) +# 2. Tag a release (triggers automatic build) git tag v1.0.0 && git push origin v1.0.0 -# 3. Update k8s manifests with your image -# Edit k8s/deployment.yaml: image: ghcr.io/your-username/turbovault: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 to Kubernetes +# 4. Deploy ./scripts/deploy-k8s.sh ``` +See [Quick Start Guide](docs/QUICK_START.md) for detailed steps. + ### Docker Compose (Development/Testing) ```bash @@ -135,14 +134,13 @@ IGDB sync is enabled by default for all users and runs every 30 minutes. **All documentation is in the [`docs/`](docs/) folder.** **Quick Links:** -- 📋 [Deployment Checklist](docs/DEPLOYMENT_CHECKLIST.md) - Step-by-step deployment -- 🤖 [GitHub Actions Setup](docs/GITHUB_ACTIONS_SETUP.md) - CI/CD pipeline -- 🚀 [Deployment Guide](docs/DEPLOYMENT.md) - Complete deployment reference -- 💻 [Development Guide](docs/DEVELOPMENT_GUIDE.md) - Local development setup -- 📖 [API Documentation](docs/API_DOCUMENTATION.md) - RESTful API reference -- 🎮 [IGDB Integration](docs/IGDB_INTEGRATION.md) - Game metadata matching -- 🎨 [Themes](docs/THEMES.md) - Theme customization -- 🎯 [Demo Account](docs/DEMO_ACCOUNT.md) - Try the demo +- ⭐ [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 +- 🎯 [Demo Account](docs/DEMO_ACCOUNT.md) - Try it out [**See all documentation →**](docs/README.md) diff --git a/REGISTRY_SIMPLIFIED.md b/REGISTRY_SIMPLIFIED.md deleted file mode 100644 index edb14a4..0000000 --- a/REGISTRY_SIMPLIFIED.md +++ /dev/null @@ -1,179 +0,0 @@ -# ✅ Container Registry Simplified! - -The deployment has been simplified to be registry-agnostic. You can now use any container registry you prefer! - -## What Changed - -### Before: -- Hardcoded for Gitea registry -- Required 4 GitHub secrets -- Complex setup instructions -- Registry-specific documentation - -### After: -- **Default:** GitHub Container Registry (ghcr.io) - zero setup! -- **Flexible:** Works with any registry (Docker Hub, private registry, etc.) -- **Simple:** No secrets needed for default setup -- **Clean:** Registry-agnostic documentation - -## 🎯 Default Setup: GitHub Container Registry - -**No setup required!** Just push a tag: - -```bash -git tag v1.0.0 -git push origin v1.0.0 -``` - -- ✅ Free -- ✅ Built into GitHub -- ✅ No secrets to configure -- ✅ Automatic authentication -- ✅ Public or private images - -Your image will be at: `ghcr.io/YOUR_USERNAME/turbovault:v1.0.0` - -## 🔧 Using a Different Registry (Optional) - -Want to use Docker Hub, your own registry, or something else? Just modify the workflow: - -### Docker Hub Example: -```yaml -# .github/workflows/build-and-push.yml -env: - REGISTRY: docker.io - IMAGE_NAME: your-username/turbovault -``` - -Add secrets: `DOCKERHUB_USERNAME`, `DOCKERHUB_TOKEN` - -### Private Registry Example: -```yaml -env: - REGISTRY: registry.example.com - IMAGE_NAME: turbovault -``` - -Add secrets for your registry credentials. - -See [.github/SECRETS_SETUP.md](.github/SECRETS_SETUP.md) for examples. - -## 📦 Kubernetes Deployment - -Update the image in `k8s/deployment.yaml`: - -```yaml -# For GitHub Container Registry (default) -image: ghcr.io/your-username/turbovault:latest - -# For Docker Hub -image: docker.io/your-username/turbovault:latest - -# For private registry -image: registry.example.com/turbovault:latest -``` - -### Public Registry (ghcr.io public or Docker Hub public): -No `imagePullSecrets` needed! - -### Private Registry: -```yaml -imagePullSecrets: -- name: registry-secret -``` - -Create secret: -```bash -kubectl create secret docker-registry registry-secret \ - --docker-server=your-registry.com \ - --docker-username=your-username \ - --docker-password=your-token \ - --namespace=turbovault -``` - -## 📁 Files Updated - -### Removed: -- ❌ `k8s/GITEA_SETUP.md` - Gitea-specific guide (no longer needed) -- ❌ `k8s/gitea-registry-secret.yaml.example` - Gitea secret template -- ❌ `docs/.github-gitea-setup.md` - GitHub+Gitea architecture - -### Updated: -- ✅ `.github/workflows/build-and-push.yml` - Uses ghcr.io by default -- ✅ `.github/SECRETS_SETUP.md` - Simplified, no secrets needed for default -- ✅ `k8s/deployment.yaml` - Example with ghcr.io -- ✅ `k8s/migrate-job.yaml` - Example with ghcr.io -- ✅ `k8s/README.md` - Registry-agnostic instructions -- ✅ `README.md` - Updated deployment steps -- ✅ `scripts/deploy-k8s.sh` - Generic registry prompts - -## 🎉 Benefits - -### For Users: -- ✅ Simpler setup (zero config for ghcr.io) -- ✅ Choice of any registry -- ✅ No mandatory external dependencies -- ✅ Standard GitHub workflow - -### For Open Source: -- ✅ Contributors don't need private registries -- ✅ Works out of the box with GitHub -- ✅ Easy to fork and deploy -- ✅ Professional standard setup - -## 📖 Updated Documentation - -All documentation has been updated to: -- Use GitHub Container Registry as the default example -- Provide examples for other registries -- Remove Gitea-specific instructions -- Be registry-agnostic - -**Key docs:** -- [.github/SECRETS_SETUP.md](.github/SECRETS_SETUP.md) - Registry options -- [k8s/README.md](k8s/README.md) - Kubernetes deployment -- [README.md](README.md) - Main project README - -## 🚀 Quick Start (Recommended Path) - -1. **Push code to GitHub:** - ```bash - git push origin main - ``` - -2. **Tag a release:** - ```bash - git tag v1.0.0 - git push origin v1.0.0 - ``` - -3. **Watch GitHub Actions:** - - Go to Actions tab - - See build complete - - Image pushed to ghcr.io/YOUR_USERNAME/turbovault:v1.0.0 - -4. **Update k8s manifests:** - ```bash - # Edit k8s/deployment.yaml and k8s/migrate-job.yaml - image: ghcr.io/YOUR_USERNAME/turbovault:v1.0.0 - ``` - -5. **Deploy:** - ```bash - ./scripts/deploy-k8s.sh - ``` - -Done! 🎉 - -## 💡 You Can Still Use Gitea (or any registry) - -This change doesn't prevent you from using Gitea or any other registry. It just: -- Makes the default simpler (uses GitHub's built-in registry) -- Makes the code registry-agnostic -- Removes hardcoded assumptions - -**To use Gitea:** Just modify the workflow and k8s manifests with your Gitea registry paths. It's all flexible now! - ---- - -**Everything is simpler, cleaner, and more flexible!** 🚀 diff --git a/SECURITY_SCAN_RESULTS.md b/SECURITY_SCAN_RESULTS.md deleted file mode 100644 index 0f7a2cd..0000000 --- a/SECURITY_SCAN_RESULTS.md +++ /dev/null @@ -1,102 +0,0 @@ -# 🔒 Security Scan Results - -**Status:** ✅ **SAFE TO COMMIT** - -Scanned on: 2026-03-28 - -## ✅ Protected Files (Gitignored) - -These sensitive files exist locally but are **NOT** being committed: - -- ✅ `.env` - Environment variables (gitignored) -- ✅ `config/master.key` - Rails master key (gitignored) -- ✅ `k8s/secrets.yaml` - Does not exist (only .example exists) - -## ✅ Configuration Files (Safe) - -These files use environment variables or placeholders: - -- ✅ `config/database.yml` - Uses `ENV["DATABASE_PASSWORD"]` -- ✅ `.env.example` - Contains only placeholders -- ✅ `k8s/secrets.yaml.example` - Contains only placeholders -- ✅ `k8s/configmap.yaml` - Contains example values only - -## ✅ Development Passwords (Safe) - -These are intentional demo/dev passwords and are safe to commit: - -- ✅ `db/seeds.rb` - Demo account password: "password123" (documented) -- ✅ `config/database.yml` - Default dev password: "postgres" (standard) -- ✅ `docker-compose.yml` - Dev postgres password: "postgres" (standard) - -## 🔍 What Was Scanned - -1. **Secret files:** .env, master.key, secrets.yaml -2. **Hardcoded credentials:** Searched for API keys, tokens, passwords -3. **Configuration files:** database.yml, secrets examples -4. **Git status:** Verified sensitive files are not staged -5. **Gitignore:** Verified all sensitive patterns are covered - -## 📝 Gitignore Coverage - -Your `.gitignore` properly excludes: - -``` -/.env -/.env.local -/config/master.key -/config/credentials/*.key -k8s/secrets.yaml -k8s/sealed-secrets.yaml -``` - -## ⚠️ What to Remember - -**Before committing:** -- ✅ `.env` stays local (already gitignored) -- ✅ `config/master.key` stays local (already gitignored) -- ✅ Never create `k8s/secrets.yaml` (create it only on your k8s cluster) - -**Safe to commit:** -- ✅ `.env.example` - Has placeholders -- ✅ `k8s/secrets.yaml.example` - Template only -- ✅ All source code files -- ✅ All documentation -- ✅ All Kubernetes manifests (except secrets.yaml) - -## 🚀 Ready to Commit - -You can safely run: - -```bash -git add . -git commit -m "Initial commit: TurboVault" -git push origin main -``` - -## 🔐 Post-Deployment Security - -After deploying, remember to: - -1. **Change default passwords** in production -2. **Use strong SECRET_KEY_BASE** (from `rails secret`) -3. **Store real secrets in k8s secrets** (not in git) -4. **Rotate IGDB credentials** periodically -5. **Use HTTPS** in production (cert-manager) - -## 📋 Files That Will Be Committed - -Total files to commit: ~200 files including: -- All Ruby/Rails source code -- All documentation (docs/) -- All Kubernetes manifests (k8s/) -- All GitHub Actions workflows (.github/) -- Configuration templates (.example files) -- Dockerfile and docker-compose.yml -- README, LICENSE, etc. - -**None of these contain sensitive information.** ✅ - ---- - -**Scan Complete!** You're safe to push to GitHub. 🎉 diff --git a/docs/DEPLOYMENT.md b/docs/DEPLOYMENT.md index ecb6f97..d46b5ee 100644 --- a/docs/DEPLOYMENT.md +++ b/docs/DEPLOYMENT.md @@ -118,18 +118,22 @@ kubectl apply -f k8s/ingress.yaml ### Update Image Reference -Edit `k8s/deployment.yaml` and `k8s/migrate-job.yaml` with your Gitea registry path: +Edit `k8s/deployment.yaml` and `k8s/migrate-job.yaml` with your registry path: ```yaml -# Add imagePullSecrets for Gitea authentication -imagePullSecrets: -- name: gitea-registry +# For public registries (GitHub Container Registry, Docker Hub public) +# No imagePullSecrets needed! +image: ghcr.io/your-username/turbovault:latest -# Update image path -image: gitea.example.com/username/turbovault:latest +# For private registries, add imagePullSecrets: +imagePullSecrets: +- name: registry-secret + +image: your-registry.com/turbovault:latest ``` -**See [k8s/GITEA_SETUP.md](../k8s/GITEA_SETUP.md) for complete Gitea registry setup guide.** +**Default:** Use GitHub Container Registry (ghcr.io) - free and built-in. +**See:** [k8s/README.md](../k8s/README.md) for registry setup details. --- diff --git a/docs/DEPLOYMENT_CHECKLIST.md b/docs/DEPLOYMENT_CHECKLIST.md deleted file mode 100644 index 08a0619..0000000 --- a/docs/DEPLOYMENT_CHECKLIST.md +++ /dev/null @@ -1,244 +0,0 @@ -# TurboVault Deployment Checklist - -Complete checklist for deploying TurboVault from scratch. - -## Phase 1: GitHub Setup ⬜ - -- [ ] **Read:** [.github/WHAT_TO_COMMIT.md](../.github/WHAT_TO_COMMIT.md) -- [ ] Create GitHub repository (public) -- [ ] Run `./scripts/setup-github.sh` OR manually push code -- [ ] Verify code is on GitHub -- [ ] **Read:** [.github/SECRETS_SETUP.md](../.github/SECRETS_SETUP.md) - -## Phase 2: Gitea Access Token ⬜ - -- [ ] Login to your Gitea instance -- [ ] Go to Settings → Applications → Access Tokens -- [ ] Generate new token named `github-actions` -- [ ] Enable permissions: `package:read` + `package:write` -- [ ] Copy the token (starts with `gtea_`) -- [ ] Save it somewhere safe (you'll need it for GitHub Secrets) - -## Phase 3: GitHub Secrets ⬜ - -Add these 4 secrets in GitHub → Settings → Secrets → Actions: - -- [ ] `GITEA_REGISTRY` = Your Gitea URL (e.g., `gitea.example.com`) -- [ ] `GITEA_USERNAME` = Your Gitea username -- [ ] `GITEA_TOKEN` = The token you just created -- [ ] `GITEA_REPO` = Repository path (e.g., `username/turbovault`) - -**Verify:** All 4 secrets show up in GitHub secrets list - -## Phase 4: Test GitHub Actions ⬜ - -- [ ] Go to GitHub → Actions tab -- [ ] Click "Build and Push to Gitea" workflow -- [ ] Click "Run workflow" -- [ ] Enter tag: `test` -- [ ] Click "Run workflow" -- [ ] Watch the build (should take 2-5 minutes) -- [ ] Verify: Build succeeds with ✅ -- [ ] Go to Gitea → Your Repo → Packages tab -- [ ] Verify: `turbovault:test` image exists - -**If build fails:** Check [GITHUB_ACTIONS_SETUP.md](GITHUB_ACTIONS_SETUP.md) troubleshooting - -## Phase 5: Kubernetes Secrets ⬜ - -- [ ] **Read:** [k8s/GITEA_SETUP.md](../k8s/GITEA_SETUP.md) -- [ ] Copy `k8s/secrets.yaml.example` to `k8s/secrets.yaml` -- [ ] Generate Rails secret: `rails secret` -- [ ] Edit `k8s/secrets.yaml` with your values: - - [ ] `DATABASE_PASSWORD` - Your PostgreSQL password - - [ ] `SECRET_KEY_BASE` - From `rails secret` command - - [ ] `IGDB_CLIENT_ID` - Your IGDB client ID (optional) - - [ ] `IGDB_CLIENT_SECRET` - Your IGDB secret (optional) -- [ ] **DO NOT commit k8s/secrets.yaml** (it's gitignored ✅) - -## Phase 6: Update Kubernetes Manifests ⬜ - -- [ ] Edit `k8s/deployment.yaml`: - - [ ] Change `YOUR_REGISTRY/turbovault:latest` to your Gitea path - - [ ] Example: `gitea.example.com/username/turbovault:latest` - -- [ ] Edit `k8s/migrate-job.yaml`: - - [ ] Change `YOUR_REGISTRY/turbovault:latest` to your Gitea path - -- [ ] Edit `k8s/configmap.yaml`: - - [ ] Set `DATABASE_HOST` (your PostgreSQL hostname) - - [ ] Set `DATABASE_NAME` (e.g., `turbovault_production`) - - [ ] Set `DATABASE_USERNAME` (e.g., `turbovault`) - -- [ ] Edit `k8s/ingress.yaml`: - - [ ] Change `turbovault.example.com` to your domain - - [ ] Or comment out ingress and use port-forward for testing - -## Phase 7: Database Setup ⬜ - -**Option A: External PostgreSQL** (Recommended) -- [ ] Create database: `CREATE DATABASE turbovault_production;` -- [ ] Create user: `CREATE USER turbovault WITH PASSWORD 'secure_password';` -- [ ] Grant privileges: `GRANT ALL PRIVILEGES ON DATABASE turbovault_production TO turbovault;` - -**Option B: In-cluster PostgreSQL** -- [ ] Follow [k8s/README.md](../k8s/README.md) Helm instructions - -## Phase 8: Kubernetes Registry Secret ⬜ - -- [ ] Run this command (replace with your values): - ```bash - kubectl create secret docker-registry gitea-registry \ - --docker-server=gitea.example.com \ - --docker-username=your-username \ - --docker-password=your-gitea-token \ - --docker-email=your-email@example.com \ - --namespace=turbovault - ``` - -- [ ] Verify: `kubectl get secret gitea-registry -n turbovault` - -**Or:** Use the deploy script which will prompt you to create it - -## Phase 9: Deploy to Kubernetes ⬜ - -**Option A: Automated Script** -- [ ] Run `./scripts/deploy-k8s.sh` -- [ ] Enter your Gitea registry URL when prompted -- [ ] Confirm deployment -- [ ] Watch the deployment progress - -**Option B: Manual** -- [ ] `kubectl apply -f k8s/namespace.yaml` -- [ ] `kubectl apply -f k8s/configmap.yaml` -- [ ] `kubectl apply -f k8s/secrets.yaml` -- [ ] `kubectl apply -f k8s/migrate-job.yaml` -- [ ] `kubectl wait --for=condition=complete --timeout=300s job/turbovault-migrate -n turbovault` -- [ ] `kubectl apply -f k8s/deployment.yaml` -- [ ] `kubectl apply -f k8s/service.yaml` -- [ ] `kubectl apply -f k8s/ingress.yaml` (optional) - -## Phase 10: Verify Deployment ⬜ - -- [ ] Check pods: `kubectl get pods -n turbovault` -- [ ] Verify 2 pods are Running -- [ ] Check logs: `kubectl logs -f deployment/turbovault -n turbovault` -- [ ] No errors in logs -- [ ] Check service: `kubectl get svc -n turbovault` -- [ ] Check ingress: `kubectl get ingress -n turbovault` - -## Phase 11: Access Application ⬜ - -**Option A: Via Ingress** (if configured) -- [ ] Visit your domain: `https://turbovault.example.com` -- [ ] Verify site loads - -**Option B: Via Port Forward** (for testing) -- [ ] Run: `kubectl port-forward svc/turbovault-service 3000:80 -n turbovault` -- [ ] Visit: `http://localhost:3000` -- [ ] Verify site loads - -## Phase 12: Initial Setup ⬜ - -- [ ] Create admin user account -- [ ] Login and test basic functionality -- [ ] Add a test game -- [ ] Create a test collection -- [ ] Enable IGDB sync in settings (if configured) -- [ ] Test API with a token (optional) - -## Phase 13: Optional - SSL/TLS ⬜ - -- [ ] Install cert-manager (see [DEPLOYMENT.md](DEPLOYMENT.md)) -- [ ] Create ClusterIssuer for Let's Encrypt -- [ ] Update ingress with TLS config -- [ ] Verify HTTPS works - -## Phase 14: Optional - Monitoring ⬜ - -- [ ] Set up log aggregation -- [ ] Configure health check alerts -- [ ] Set up backup cron job -- [ ] Document backup/restore procedure - -## Quick Reference Commands - -### Check Deployment Status -```bash -kubectl get all -n turbovault -kubectl describe deployment turbovault -n turbovault -kubectl logs -f deployment/turbovault -n turbovault -``` - -### Access Application -```bash -# Port forward -kubectl port-forward svc/turbovault-service 3000:80 -n turbovault - -# Get ingress URL -kubectl get ingress -n turbovault -``` - -### Update Image -```bash -# After pushing new tag to GitHub -kubectl set image deployment/turbovault \ - turbovault=gitea.example.com/username/turbovault:v1.1.0 \ - -n turbovault -``` - -### Restart Deployment -```bash -kubectl rollout restart deployment/turbovault -n turbovault -``` - -### View Recent Logs -```bash -kubectl logs --tail=100 -l app=turbovault -n turbovault -``` - -### Database Console -```bash -kubectl exec -it deployment/turbovault -n turbovault -- rails console -``` - -## Troubleshooting - -| Issue | Command | Documentation | -|-------|---------|---------------| -| Pods not starting | `kubectl describe pod -l app=turbovault -n turbovault` | [k8s/README.md](../k8s/README.md) | -| ImagePullBackOff | Check registry secret | [k8s/GITEA_SETUP.md](../k8s/GITEA_SETUP.md) | -| Database connection | Check secrets & configmap | [DEPLOYMENT.md](DEPLOYMENT.md) | -| Build fails | Check GitHub Actions logs | [GITHUB_ACTIONS_SETUP.md](GITHUB_ACTIONS_SETUP.md) | - -## Success Criteria ✅ - -Your deployment is successful when: - -- ✅ GitHub Actions builds succeed -- ✅ Images appear in Gitea packages -- ✅ k8s pods are Running (2/2) -- ✅ Application accessible via browser -- ✅ Can login and use features -- ✅ Database persists data -- ✅ IGDB sync works (if enabled) - -## Documentation Index - -| Document | Purpose | -|----------|---------| -| [README.md](../README.md) | Project overview & quick start | -| [GITHUB_ACTIONS_SETUP.md](GITHUB_ACTIONS_SETUP.md) | GitHub CI/CD setup | -| [.github/SECRETS_SETUP.md](../.github/SECRETS_SETUP.md) | Configure GitHub Secrets | -| [.github/WHAT_TO_COMMIT.md](../.github/WHAT_TO_COMMIT.md) | What's safe for open source | -| [k8s/GITEA_SETUP.md](../k8s/GITEA_SETUP.md) | Gitea registry integration | -| [k8s/README.md](../k8s/README.md) | Kubernetes deployment guide | -| [DEPLOYMENT.md](DEPLOYMENT.md) | Complete deployment guide | -| [API_DOCUMENTATION.md](API_DOCUMENTATION.md) | RESTful API reference | -| [IGDB_INTEGRATION.md](IGDB_INTEGRATION.md) | IGDB feature documentation | - ---- - -**Start Here:** Phase 1 → Phase 12 for basic deployment -**Need Help?** Check the relevant documentation link for detailed instructions -**Ready to Deploy?** Check off each item as you complete it! 🚀 diff --git a/docs/EMAIL_SETUP_SUMMARY.md b/docs/EMAIL_SETUP_SUMMARY.md deleted file mode 100644 index 97ecf6a..0000000 --- a/docs/EMAIL_SETUP_SUMMARY.md +++ /dev/null @@ -1,253 +0,0 @@ -# Email System - Setup Summary ✅ - -## What's Been Added - -I've successfully integrated **Mailpit** for local email testing! Here's what you now have: - -### 1. Docker Compose Configuration -- Added Mailpit service to `docker-compose.yml` -- SMTP server on port 1025 -- Web UI on port 8025 - -### 2. Rails Configuration -- Configured Action Mailer to use Mailpit in development -- Updated `config/environments/development.rb` - -### 3. Password Reset Mailer -- Created `PasswordResetMailer` with professional templates -- HTML email template with styling -- Plain text email template for compatibility -- Integrated with password reset controller - -### 4. Development Tools -- Added `task mailpit` command to open email viewer -- Added separate log viewing for Mailpit -- Updated all documentation - -### 5. User Interface -- Updated password reset form with Mailpit link (in dev mode) -- Professional email templates with TurboVault branding -- Security warnings in emails - -## Quick Test (5 Steps) - -### Step 1: Start Services -```bash -task docker:up -``` - -You'll see: -``` -PostgreSQL: localhost:5432 -Mailpit UI: http://localhost:8025 -``` - -### Step 2: Start Rails -```bash -task server -``` - -### Step 3: Create a User -1. Visit http://localhost:3000 -2. Click "Sign Up" -3. Create an account with your email - -### Step 4: Request Password Reset -1. Click "Login" -2. Click "Forgot your password?" -3. Enter your email -4. Click "Send Reset Instructions" - -### Step 5: Check Mailpit -1. Open http://localhost:8025 in another tab -2. You'll see the password reset email! -3. Click on it to view the beautiful HTML template -4. Click the "Reset My Password" button in the email -5. Set a new password - -## What You'll See - -### Mailpit Web Interface -- Clean, modern email viewer -- List of all captured emails -- HTML preview of emails -- Text version available -- Full email headers -- Search and filter -- Delete emails - -### Password Reset Email -- Professional HTML design with TurboVault branding -- "Reset My Password" button -- Security warning about expiration (2 hours) -- Plain text alternative for email clients -- Responsive design - -## How It Works - -``` -User requests password reset - ↓ -Controller generates reset token - ↓ -PasswordResetMailer.reset_password(user).deliver_later - ↓ -Rails sends email to localhost:1025 (Mailpit) - ↓ -Mailpit captures email - ↓ -Email appears at http://localhost:8025 - ↓ -User clicks link, resets password -``` - -## Files Created/Modified - -### New Files -- `app/mailers/password_reset_mailer.rb` - Mailer class -- `app/views/password_reset_mailer/reset_password.html.erb` - HTML email -- `app/views/password_reset_mailer/reset_password.text.erb` - Text email -- `TESTING_EMAILS.md` - Complete email testing guide -- `EMAIL_SETUP_SUMMARY.md` - This file - -### Modified Files -- `docker-compose.yml` - Added Mailpit service -- `config/environments/development.rb` - SMTP configuration -- `app/controllers/password_resets_controller.rb` - Send email -- `app/views/password_resets/new.html.erb` - Added Mailpit link -- `app/views/password_resets/edit.html.erb` - Improved UI -- `Taskfile.yml` - Added Mailpit commands -- `README.md` - Added email testing section -- `PROJECT_SUMMARY.md` - Updated status -- `IMPLEMENTATION_COMPLETE.md` - Updated status - -## Production Setup (When Ready) - -When deploying to production, add these environment variables: - -```bash -SMTP_ADDRESS=smtp.sendgrid.net -SMTP_PORT=587 -SMTP_USERNAME=your_username -SMTP_PASSWORD=your_password -MAILER_FROM_ADDRESS=noreply@yourdomain.com -``` - -Common SMTP providers: -- **SendGrid** - Free tier: 100 emails/day -- **Mailgun** - Free tier: 5,000 emails/month -- **Postmark** - Free tier: 100 emails/month -- **AWS SES** - $0.10 per 1,000 emails - -Then update `config/environments/production.rb`: -```ruby -config.action_mailer.smtp_settings = { - address: ENV['SMTP_ADDRESS'], - port: ENV['SMTP_PORT'], - user_name: ENV['SMTP_USERNAME'], - password: ENV['SMTP_PASSWORD'], - authentication: 'plain', - enable_starttls_auto: true -} -``` - -## Available Commands - -```bash -task docker:up # Start PostgreSQL + Mailpit -task mailpit # Open Mailpit in browser -task docker:logs:mailpit # View Mailpit logs -docker compose restart mailpit # Restart Mailpit -``` - -## Testing Tips - -1. **Keep Mailpit open** while developing - emails appear instantly -2. **Test different email clients** - Mailpit shows HTML and text versions -3. **Test email expiration** - Reset tokens expire after 2 hours -4. **Test invalid emails** - Try resetting with non-existent email -5. **Test email formatting** - Check responsive design in Mailpit - -## Troubleshooting - -### Emails not appearing? - -**Check Mailpit is running:** -```bash -docker compose ps -``` - -**Check Rails logs:** -```bash -tail -f log/development.log -``` - -Look for: -``` -Sent mail to user@example.com (1.2ms) -``` - -**Restart services:** -```bash -task docker:down -task docker:up -``` - -### Can't access Mailpit web UI? - -**Check the URL:** -``` -http://localhost:8025 -``` - -**Check port isn't in use:** -```bash -lsof -i :8025 -``` - -**Check Docker logs:** -```bash -task docker:logs:mailpit -``` - -## Security Notes - -### Development (Current) -- Emails are captured locally -- Never sent to real addresses -- Perfect for testing -- No email quota concerns - -### Production (Future) -- Use real SMTP provider -- Secure credentials with environment variables -- Enable TLS/SSL -- Monitor email delivery -- Set up SPF/DKIM records - -## Next Steps - -1. ✅ Email system is complete and working -2. Test the password reset flow thoroughly -3. When deploying, configure production SMTP -4. Consider adding: - - Welcome email for new users - - Email verification for signups - - Notification emails for important events - -## Documentation - -For more details: -- **[TESTING_EMAILS.md](TESTING_EMAILS.md)** - Complete testing guide -- **[README.md](../README.md)** - Updated with email info -- **Mailpit GitHub:** https://github.com/axllent/mailpit - -## Summary - -✅ **Mailpit configured and working** -✅ **Password reset emails send successfully** -✅ **Professional email templates** -✅ **Easy to test at http://localhost:8025** -✅ **Production-ready (just needs SMTP config)** - -You can now test password resets locally without sending real emails! 🎉📧 diff --git a/docs/GITHUB_ACTIONS_SETUP.md b/docs/GITHUB_ACTIONS_SETUP.md deleted file mode 100644 index efc94fb..0000000 --- a/docs/GITHUB_ACTIONS_SETUP.md +++ /dev/null @@ -1,326 +0,0 @@ -# GitHub Actions Setup Complete! 🎉 - -Your repository is now configured with GitHub Actions for automated building and deployment. - -## What's Been Added - -### GitHub Actions Workflows - -#### 1. `.github/workflows/build-and-push.yml` -**Purpose:** Build Docker image and push to your Gitea registry - -**Triggers:** -- ✅ When you push a version tag (e.g., `v1.0.0`, `v2.1.0`) -- ✅ Manual trigger from GitHub Actions tab - -**What it does:** -1. Checks out your code -2. Builds Docker image -3. Logs into your Gitea registry -4. Pushes image with version tag + `latest` tag -5. Shows deploy command in output - -#### 2. `.github/workflows/ci.yml` -**Purpose:** Run tests and quality checks - -**Triggers:** -- ✅ On push to `main` or `develop` branches -- ✅ On pull requests - -**What it does:** -1. **Lint:** Runs RuboCop (code style) -2. **Security:** Runs Brakeman (security scan) -3. **Test:** Runs your test suite with PostgreSQL -4. **Build Test:** Verifies Dockerfile builds successfully - -### Documentation - -- ✅ `.github/SECRETS_SETUP.md` - How to configure GitHub Secrets -- ✅ `.github/WHAT_TO_COMMIT.md` - What's safe to commit publicly -- ✅ `GITHUB_ACTIONS_SETUP.md` - This file! - -### Updated Files - -- ✅ `README.md` - Added CI/CD section -- ✅ `k8s/deployment.yaml` - Placeholder image paths -- ✅ `k8s/migrate-job.yaml` - Placeholder image paths -- ✅ `.gitignore` - Already excludes secrets ✅ - -## Your Next Steps - -### Step 1: Add GitHub Secrets - -Go to your GitHub repository → **Settings** → **Secrets and variables** → **Actions** - -Add these 4 secrets: - -| Secret Name | Value | Example | -|-------------|-------|---------| -| `GITEA_REGISTRY` | Your Gitea URL (no https://) | `gitea.example.com` | -| `GITEA_USERNAME` | Your Gitea username | `johndoe` | -| `GITEA_TOKEN` | Gitea access token | `gtea_abc123...` | -| `GITEA_REPO` | Repo path | `johndoe/turbovault` | - -**Detailed instructions:** [.github/SECRETS_SETUP.md](../.github/SECRETS_SETUP.md) - -### Step 2: Get Gitea Access Token - -1. Login to your Gitea instance -2. **Settings** → **Applications** → **Manage Access Tokens** -3. Click **Generate New Token** -4. Name: `github-actions` -5. Permissions: - - ✅ `package:read` - - ✅ `package:write` -6. Click **Generate Token** -7. Copy the token (starts with `gtea_`) -8. Add to GitHub as `GITEA_TOKEN` secret - -### Step 3: Push to GitHub - -```bash -# Make sure you're in the project directory -cd turbovault-web - -# Run the setup script -./scripts/setup-github.sh - -# Or manually: -git add . -git commit -m "Add GitHub Actions for CI/CD" -git push origin main -``` - -### Step 4: Test the Workflow - -**Option A: Manually trigger a build** - -1. Go to your GitHub repository -2. Click **Actions** tab -3. Click **Build and Push to Gitea** -4. Click **Run workflow** button -5. Enter tag: `test` or `v0.1.0` -6. Click **Run workflow** -7. Watch it build! - -**Option B: Create a version tag** - -```bash -# Create and push a tag -git tag v1.0.0 -git push origin v1.0.0 - -# This will automatically trigger the build workflow -``` - -### Step 5: Verify Image in Gitea - -1. Login to your Gitea instance -2. Go to your repository -3. Click **Packages** tab -4. You should see `turbovault` package with your tag - -### Step 6: Deploy to Kubernetes - -```bash -# Update deployment with new image -kubectl set image deployment/turbovault \ - turbovault=gitea.example.com/username/turbovault:v1.0.0 \ - -n turbovault - -# Or use the deployment script -./scripts/deploy-k8s.sh -``` - -## Workflow Explained - -### Build Flow - -``` -┌─────────────────────────────────────────────────────┐ -│ Developer pushes tag: git push origin v1.0.0 │ -└─────────────────────┬───────────────────────────────┘ - ↓ -┌─────────────────────────────────────────────────────┐ -│ GitHub Actions detects tag │ -│ Workflow: build-and-push.yml │ -└─────────────────────┬───────────────────────────────┘ - ↓ -┌─────────────────────────────────────────────────────┐ -│ 1. Checkout code from GitHub │ -│ 2. Build Docker image │ -│ 3. Login to Gitea registry (using secrets) │ -│ 4. Tag image: v1.0.0 + latest │ -│ 5. Push to Gitea │ -└─────────────────────┬───────────────────────────────┘ - ↓ -┌─────────────────────────────────────────────────────┐ -│ Image available in Gitea package registry │ -│ gitea.example.com/username/turbovault:v1.0.0 │ -└─────────────────────┬───────────────────────────────┘ - ↓ -┌─────────────────────────────────────────────────────┐ -│ Deploy to Kubernetes (manual or automated) │ -│ kubectl set image deployment/turbovault ... │ -└─────────────────────────────────────────────────────┘ -``` - -### CI Flow - -``` -┌─────────────────────────────────────────────────────┐ -│ Developer pushes code or opens PR │ -└─────────────────────┬───────────────────────────────┘ - ↓ -┌─────────────────────────────────────────────────────┐ -│ GitHub Actions runs ci.yml workflow │ -└─────────────────────┬───────────────────────────────┘ - ↓ -┌─────────────────────────────────────────────────────┐ -│ Parallel jobs: │ -│ ├─ Lint (RuboCop) │ -│ ├─ Security (Brakeman) │ -│ ├─ Test (RSpec/Minitest with PostgreSQL) │ -│ └─ Build Test (Docker build verification) │ -└─────────────────────┬───────────────────────────────┘ - ↓ -┌─────────────────────────────────────────────────────┐ -│ ✅ All checks pass → Merge safe │ -│ ❌ Checks fail → Fix issues before merge │ -└─────────────────────────────────────────────────────┘ -``` - -## Common Tasks - -### Release a New Version - -```bash -# 1. Make changes and commit -git add . -git commit -m "Add new feature" -git push origin main - -# 2. Wait for CI to pass (check Actions tab) - -# 3. Create release tag -git tag v1.1.0 -git push origin v1.1.0 - -# 4. GitHub Actions builds and pushes to Gitea automatically - -# 5. Deploy to k8s -kubectl set image deployment/turbovault \ - turbovault=gitea.example.com/username/turbovault:v1.1.0 \ - -n turbovault -``` - -### Rollback to Previous Version - -```bash -# Deploy previous tag -kubectl set image deployment/turbovault \ - turbovault=gitea.example.com/username/turbovault:v1.0.0 \ - -n turbovault - -# Watch rollout -kubectl rollout status deployment/turbovault -n turbovault -``` - -### View Build Logs - -1. Go to GitHub repository -2. Click **Actions** tab -3. Click on a workflow run -4. Click on job name to see logs - -### Rebuild Latest - -```bash -# Delete and recreate tag (forces rebuild) -git tag -d latest -git push origin :refs/tags/latest -git tag latest -git push origin latest -``` - -## Troubleshooting - -### Build fails with "unauthorized" - -**Problem:** Can't login to Gitea registry - -**Solution:** -1. Verify `GITEA_TOKEN` in GitHub secrets is correct -2. Check token has `package:write` permission -3. Test locally: `docker login gitea.example.com` - -### Image pushes but k8s can't pull - -**Problem:** ImagePullBackOff in Kubernetes - -**Solution:** -1. Verify k8s secret exists: `kubectl get secret gitea-registry -n turbovault` -2. Check `imagePullSecrets` in deployment.yaml -3. See [k8s/GITEA_SETUP.md](../k8s/GITEA_SETUP.md) - -### CI tests fail - -**Problem:** Tests don't pass in GitHub Actions - -**Solution:** -1. Run tests locally: `rails test` -2. Check PostgreSQL connection -3. Review test logs in Actions tab -4. Tests are set to `continue-on-error: true` for now (won't block builds) - -### Workflow doesn't trigger - -**Problem:** Pushing tag doesn't start build - -**Solution:** -1. Check tag format: must be `v*.*.*` (e.g., `v1.0.0`) -2. Verify workflow file exists: `.github/workflows/build-and-push.yml` -3. Check Actions tab for errors - -## Benefits - -### ✅ What You Get - -1. **Automated Builds** - No manual Docker commands -2. **Version Control** - Each tag creates a versioned image -3. **CI/CD Pipeline** - Auto-test every change -4. **Quality Checks** - Linting and security scans -5. **Rollback Safety** - Keep all versions in Gitea -6. **Collaboration** - Contributors get CI feedback on PRs - -### 🎯 Workflow Benefits - -- **For You:** Push tag → image automatically builds → deploy -- **For Contributors:** Submit PR → auto-tested → you review -- **For Production:** Tagged releases → immutable versions → safe rollbacks - -## Next Steps - -1. ✅ Add GitHub Secrets ([.github/SECRETS_SETUP.md](../.github/SECRETS_SETUP.md)) -2. ✅ Push code to GitHub -3. ✅ Test workflow (manual trigger or push tag) -4. ✅ Verify image in Gitea -5. ✅ Deploy to Kubernetes -6. ✅ Celebrate! 🎉 - -## Questions? - -- **"Do I need to push to Gitea too?"** → No! GitHub Actions does it for you -- **"What about the source code?"** → Push to GitHub, images go to Gitea automatically -- **"Can I still build locally?"** → Yes! Docker build commands still work -- **"Do contributors need Gitea access?"** → No! Only you need it (for GitHub Secrets) -- **"How do I disable a workflow?"** → GitHub → Actions → Select workflow → Disable - ---- - -**You're all set!** Add your GitHub Secrets and push a tag to see it in action! 🚀 - -For detailed instructions, see: -- [.github/SECRETS_SETUP.md](../.github/SECRETS_SETUP.md) - Configure secrets -- [k8s/GITEA_SETUP.md](../k8s/GITEA_SETUP.md) - Gitea registry setup -- [DEPLOYMENT.md](DEPLOYMENT.md) - Full deployment guide diff --git a/docs/GITHUB_DEPLOYMENT_SUMMARY.md b/docs/GITHUB_DEPLOYMENT_SUMMARY.md deleted file mode 100644 index e0e26f9..0000000 --- a/docs/GITHUB_DEPLOYMENT_SUMMARY.md +++ /dev/null @@ -1,306 +0,0 @@ -# 🎉 GitHub + Kubernetes Deployment Ready! - -All files have been created for deploying TurboVault as an open-source project on GitHub with Kubernetes deployment using your Gitea registry. - -## ✅ What's Been Created - -### GitHub Actions (CI/CD) -- ✅ `.github/workflows/build-and-push.yml` - Builds Docker images, pushes to Gitea -- ✅ `.github/workflows/ci.yml` - Runs tests, linting, security scans -- ✅ `.github/SECRETS_SETUP.md` - Guide for configuring GitHub Secrets -- ✅ `.github/WHAT_TO_COMMIT.md` - What's safe for open source - -### Kubernetes Manifests (with placeholders) -- ✅ `k8s/deployment.yaml` - App deployment (2 replicas, health checks) -- ✅ `k8s/service.yaml` - ClusterIP service -- ✅ `k8s/ingress.yaml` - External access -- ✅ `k8s/configmap.yaml` - Non-sensitive config -- ✅ `k8s/secrets.yaml.example` - Template for secrets (never commit actual secrets.yaml) -- ✅ `k8s/namespace.yaml` - Namespace isolation -- ✅ `k8s/migrate-job.yaml` - Database migrations -- ✅ `k8s/gitea-registry-secret.yaml.example` - Gitea authentication template -- ✅ `k8s/README.md` - Kubernetes deployment guide -- ✅ `k8s/GITEA_SETUP.md` - Gitea-specific setup instructions - -### Scripts -- ✅ `scripts/setup-github.sh` - Automated GitHub repository setup -- ✅ `scripts/deploy-k8s.sh` - Automated Kubernetes deployment - -### Documentation (in `docs/` folder) -- ✅ `README.md` - Main project README with deployment links -- ✅ `docs/DEPLOYMENT.md` - Complete deployment guide -- ✅ `docs/DEPLOYMENT_CHECKLIST.md` - Step-by-step deployment checklist -- ✅ `docs/GITHUB_ACTIONS_SETUP.md` - GitHub Actions setup guide -- ✅ `docs/.github-gitea-setup.md` - Explains GitHub + Gitea architecture -- ✅ `docs/API_DOCUMENTATION.md` - RESTful API reference -- ✅ `docs/DEVELOPMENT_GUIDE.md` - Local development guide -- ✅ `LICENSE` - MIT License -- ✅ `.gitignore` - Excludes secrets and sensitive files - -## 🎯 Your Next Steps - -### 1. Add GitHub Secrets (REQUIRED) - -You need to add these 4 secrets in your GitHub repository: - -**How:** -1. Push your code to GitHub first (step 2 below) -2. Go to GitHub repo → **Settings** → **Secrets and variables** → **Actions** -3. Click **New repository secret** for each: - -| Secret Name | Value | Where to Get It | -|-------------|-------|-----------------| -| `GITEA_REGISTRY` | `gitea.example.com` | Your Gitea instance URL (no https://) | -| `GITEA_USERNAME` | `your-username` | Your Gitea login username | -| `GITEA_TOKEN` | `gtea_abc123...` | Gitea → Settings → Applications → Generate Token | -| `GITEA_REPO` | `username/turbovault` | Your Gitea repository path | - -**Detailed instructions:** [.github/SECRETS_SETUP.md](../.github/SECRETS_SETUP.md) - -### 2. Push to GitHub - -```bash -cd /home/rkazokas/turbovault-web - -# Option A: Use the automated script -./scripts/setup-github.sh - -# Option B: Manual -git init -git add . -git commit -m "Initial commit: TurboVault - Video Game Collection Tracker" -git branch -M main -git remote add origin https://github.com/YOUR_USERNAME/turbovault.git -git push -u origin main -``` - -### 3. Get Gitea Access Token - -1. Login to your Gitea instance -2. **Settings** → **Applications** → **Manage Access Tokens** -3. Click **Generate New Token** -4. Name: `github-actions` -5. Select permissions: - - ✅ `package:read` - - ✅ `package:write` -6. Click **Generate Token** -7. **Copy the token** (starts with `gtea_`) -8. Save it for the GitHub Secrets step - -### 4. Test GitHub Actions - -After adding secrets: - -```bash -# Create and push a tag -git tag v1.0.0 -git push origin v1.0.0 - -# Or manually trigger in GitHub: -# Actions → Build and Push to Gitea → Run workflow -``` - -This will: -- ✅ Build Docker image -- ✅ Push to your Gitea registry -- ✅ Tag as `v1.0.0` and `latest` - -### 5. Verify Image in Gitea - -1. Login to your Gitea instance -2. Go to your repository -3. Click **Packages** tab -4. You should see `turbovault` package - -### 6. Deploy to Kubernetes - -```bash -# Use the automated script -./scripts/deploy-k8s.sh - -# Follow the prompts: -# - Enter your Gitea registry URL -# - Script will check/create registry secret -# - Deploys all manifests -# - Runs database migration -# - Starts the application -``` - -## 📖 Documentation Guide - -Read these in order if deploying from scratch: - -1. **START:** [DEPLOYMENT_CHECKLIST.md](DEPLOYMENT_CHECKLIST.md) -2. [.github/SECRETS_SETUP.md](../.github/SECRETS_SETUP.md) - Configure GitHub -3. [k8s/GITEA_SETUP.md](../k8s/GITEA_SETUP.md) - Gitea registry setup -4. [GITHUB_ACTIONS_SETUP.md](GITHUB_ACTIONS_SETUP.md) - CI/CD workflow details -5. [k8s/README.md](../k8s/README.md) - Full Kubernetes guide -6. [DEPLOYMENT.md](DEPLOYMENT.md) - Complete deployment reference - -## 🏗️ Architecture - -``` -┌─────────────────────────────────────────────────────────┐ -│ GitHub (Public) │ -│ - Source code │ -│ - Issues / PRs │ -│ - Documentation │ -│ - GitHub Actions CI/CD │ -└────────────────┬────────────────────────────────────────┘ - │ - │ (On tag push: v1.0.0) - ↓ -┌─────────────────────────────────────────────────────────┐ -│ GitHub Actions Workflow │ -│ 1. Checkout code │ -│ 2. Build Docker image │ -│ 3. Login to Gitea (using GitHub Secrets) │ -│ 4. Push image to Gitea registry │ -└────────────────┬────────────────────────────────────────┘ - │ - ↓ -┌─────────────────────────────────────────────────────────┐ -│ Gitea Registry (Private) │ -│ - Docker images │ -│ - gitea.example.com/username/turbovault:v1.0.0 │ -│ - gitea.example.com/username/turbovault:latest │ -└────────────────┬────────────────────────────────────────┘ - │ - │ (kubectl pull image) - ↓ -┌─────────────────────────────────────────────────────────┐ -│ Kubernetes (k3s) │ -│ - Pulls images from Gitea │ -│ - Runs TurboVault application │ -│ - PostgreSQL database │ -│ - Ingress / Load Balancer │ -└─────────────────────────────────────────────────────────┘ -``` - -## 🔐 Security Notes - -### ✅ Safe to Commit to GitHub -- All source code -- Kubernetes manifests (with placeholders) -- `.env.example`, `k8s/secrets.yaml.example` -- Documentation -- Dockerfile -- GitHub Actions workflows - -### ❌ Never Commit to GitHub -- `.env` (actual secrets) - ✅ gitignored -- `k8s/secrets.yaml` (actual secrets) - ✅ gitignored -- `config/master.key` - ✅ gitignored -- Any files with passwords/tokens - -**Your `.gitignore` already protects you!** ✅ - -## 🎯 Workflow Example - -### Typical Development Cycle - -```bash -# 1. Make changes -vim app/controllers/games_controller.rb - -# 2. Commit and push to GitHub -git add . -git commit -m "Add new feature" -git push origin main - -# 3. CI runs automatically (tests, linting) -# Check: GitHub → Actions tab - -# 4. Create release tag -git tag v1.1.0 -git push origin v1.1.0 - -# 5. GitHub Actions builds and pushes to Gitea automatically -# Check: GitHub → Actions → Build and Push to Gitea - -# 6. Deploy to Kubernetes -kubectl set image deployment/turbovault \ - turbovault=gitea.example.com/username/turbovault:v1.1.0 \ - -n turbovault - -# 7. Verify deployment -kubectl get pods -n turbovault -kubectl logs -f deployment/turbovault -n turbovault -``` - -## 💡 Benefits of This Setup - -✅ **Open Source** - Code on GitHub for collaboration -✅ **Private Images** - Docker images stay on your Gitea -✅ **Automated Builds** - Push tag → image builds automatically -✅ **CI/CD Pipeline** - Tests run on every PR -✅ **Version Control** - Each tag creates immutable image -✅ **Easy Rollback** - All versions kept in Gitea -✅ **Collaboration** - Contributors don't need Gitea access -✅ **Security** - Secrets managed properly (GitHub Secrets + k8s Secrets) - -## ❓ FAQ - -**Q: Do I push Docker images to GitHub?** -A: No! GitHub Actions builds them and pushes to Gitea automatically. - -**Q: Can others see my Gitea credentials?** -A: No! They're stored as GitHub Secrets (encrypted). - -**Q: What if someone forks my repo?** -A: They can fork the code, but they'll need their own Gitea/registry for images. - -**Q: Do contributors need Gitea access?** -A: No! Only you need it (for the GitHub Secrets). Contributors just push code. - -**Q: How do I update the deployed app?** -A: Push a new tag → GitHub Actions builds → deploy with kubectl or script. - -**Q: Can I still build locally?** -A: Yes! `docker build -t ...` still works. GitHub Actions is just automation. - -**Q: Is the k8s manifest safe to share publicly?** -A: Yes! It uses placeholders and references secrets (which are gitignored). - -## 🚨 Before You Deploy - -**Checklist:** -- [ ] `.env` file exists locally (don't commit!) -- [ ] GitHub Secrets added (all 4) -- [ ] Gitea access token created -- [ ] `k8s/secrets.yaml` created (don't commit!) -- [ ] Database ready (PostgreSQL) -- [ ] Kubernetes cluster accessible -- [ ] Read [DEPLOYMENT_CHECKLIST.md](DEPLOYMENT_CHECKLIST.md) - -## 📚 All Your Documentation - -| File | Purpose | -|------|---------| -| [DEPLOYMENT_CHECKLIST.md](DEPLOYMENT_CHECKLIST.md) | **START HERE** - Complete deployment steps | -| [GITHUB_ACTIONS_SETUP.md](GITHUB_ACTIONS_SETUP.md) | GitHub CI/CD setup | -| [.github/SECRETS_SETUP.md](../.github/SECRETS_SETUP.md) | Configure GitHub Secrets | -| [.github/WHAT_TO_COMMIT.md](../.github/WHAT_TO_COMMIT.md) | What's safe for open source | -| [k8s/GITEA_SETUP.md](../k8s/GITEA_SETUP.md) | Gitea registry setup | -| [k8s/README.md](../k8s/README.md) | Kubernetes deployment | -| [DEPLOYMENT.md](DEPLOYMENT.md) | Complete deployment guide | -| [.github-gitea-setup.md](.github-gitea-setup.md) | Architecture explanation | -| [README.md](../README.md) | Project overview | -| [API_DOCUMENTATION.md](API_DOCUMENTATION.md) | API reference | -| [IGDB_INTEGRATION.md](IGDB_INTEGRATION.md) | IGDB features | - -## 🎉 You're Ready! - -Everything is configured and ready to go. Follow these steps: - -1. ✅ Push code to GitHub -2. ✅ Add GitHub Secrets -3. ✅ Push a tag to trigger build -4. ✅ Deploy to Kubernetes -5. ✅ Celebrate! 🚀 - -**Need Help?** Read [DEPLOYMENT_CHECKLIST.md](DEPLOYMENT_CHECKLIST.md) for step-by-step instructions! - ---- - -**Pro Tip:** Start with the DEPLOYMENT_CHECKLIST.md - it walks you through everything in order. diff --git a/docs/IMPLEMENTATION_COMPLETE.md b/docs/IMPLEMENTATION_COMPLETE.md deleted file mode 100644 index 4b4564c..0000000 --- a/docs/IMPLEMENTATION_COMPLETE.md +++ /dev/null @@ -1,402 +0,0 @@ -# TurboVault Implementation - Complete! 🎉 - -## What's Been Built - -I've successfully implemented the **complete Phase 1 MVP** of TurboVault as specified in REQUIREMENTS.md. Here's what's ready to use: - -### ✅ Fully Functional Features - -1. **User Authentication System** - - Email/password signup and login - - Password reset flow (needs SMTP configuration for email sending) - - Secure session management - - Public/private profile toggle - -2. **Game Management (Complete CRUD)** - - Add games with full details - - Edit and delete games - - Physical game fields: condition, price, location - - Digital game fields: store/platform, price - - Multiple genre assignment - - Completion status tracking - - 5-star rating system - - Freeform notes field - -3. **Bulk Import via CSV** - - Upload CSV files with multiple games - - Comprehensive validation - - Detailed error reporting - - Example format included in UI - -4. **Collections System** - - Create custom collections - - One-level subcollections supported - - Games can belong to multiple collections - - Full CRUD operations - -5. **Search, Filter & Sort** - - Search by game title - - Filter by platform, genre, format, completion status - - Sort alphabetically, by date added, by rating - - Pagination (25 games per page) - -6. **Statistics Dashboard** - - Total games, physical/digital breakdown - - Completion statistics - - Total money spent - - Top 5 platforms and genres - - Recently added games - - Currently playing games - -7. **Items Management** - - Track consoles, controllers, accessories - - Link to platforms - - Track condition, price, location - -8. **RESTful API (Complete)** - - Full CRUD for games and collections - - Bulk game creation endpoint - - Read-only platforms and genres - - Token-based authentication - - API token management UI - - Comprehensive API documentation - -9. **Row Level Security (RLS)** - - Enabled on all user-scoped tables - - Database-level data isolation - - Defense-in-depth security model - -10. **Professional UI** - - Tailwind CSS styling - - Responsive design - - Clean, modern interface - - Flash messages for feedback - - Dynamic forms - -## Files Created/Modified - -### Models (9 models) -- `app/models/user.rb` - User authentication with RLS integration -- `app/models/game.rb` - Game tracking with enums and scopes -- `app/models/platform.rb` - Gaming platforms -- `app/models/genre.rb` - Game genres -- `app/models/collection.rb` - Collections with subcollections -- `app/models/item.rb` - Non-game items -- `app/models/api_token.rb` - API authentication -- `app/models/game_genre.rb` - Join table -- `app/models/collection_game.rb` - Join table - -### Controllers (15+ controllers) -- `app/controllers/concerns/authentication.rb` - Authentication with RLS -- `app/controllers/sessions_controller.rb` - Login/logout -- `app/controllers/users_controller.rb` - Registration and profile -- `app/controllers/password_resets_controller.rb` - Password reset -- `app/controllers/dashboard_controller.rb` - Statistics dashboard -- `app/controllers/games_controller.rb` - Game CRUD + CSV import -- `app/controllers/collections_controller.rb` - Collection CRUD -- `app/controllers/items_controller.rb` - Item CRUD -- `app/controllers/api_tokens_controller.rb` - API token management -- `app/controllers/profiles_controller.rb` - Public profiles -- `app/controllers/pages_controller.rb` - Homepage -- API controllers in `app/controllers/api/v1/`: - - `base_controller.rb` - API authentication - - `games_controller.rb` - Game API endpoints - - `collections_controller.rb` - Collection API endpoints - - `platforms_controller.rb` - Platform API endpoints - - `genres_controller.rb` - Genre API endpoints - -### Views (30+ view files) -- Layouts: `application.html.erb`, `_navigation.html.erb`, `_flash.html.erb` -- Pages: `home.html.erb` -- Sessions: `new.html.erb` (login) -- Users: `new.html.erb` (signup), `settings.html.erb` -- Dashboard: `index.html.erb` (full statistics) -- Games: `index.html.erb`, `show.html.erb`, `new.html.erb`, `edit.html.erb`, `_form.html.erb`, `import.html.erb` -- Collections: `index.html.erb`, `show.html.erb`, `new.html.erb`, `edit.html.erb`, `_form.html.erb` -- API Tokens: `index.html.erb` - -### Database (10 migrations with RLS) -- `create_users` - User accounts with RLS -- `create_platforms` - Gaming platforms -- `create_genres` - Game genres -- `create_api_tokens` - API authentication with RLS -- `create_games` - Game entries with RLS -- `create_game_genres` - Many-to-many join -- `create_collections` - Collections with RLS -- `create_collection_games` - Many-to-many join -- `create_items` - Non-game items with RLS -- `add_password_reset_to_users` - Password reset tokens - -### Configuration -- `config/routes.rb` - Complete routing (web + API) -- `config/database.yml` - PostgreSQL configuration -- `docker-compose.yml` - PostgreSQL service -- `Taskfile.yml` - Development tasks -- Tailwind CSS configured and running - -### Documentation (5 comprehensive docs) -- `README.md` - Main project documentation -- `REQUIREMENTS.md` - Original requirements (already existed) -- `PROJECT_SUMMARY.md` - What's built, what's next -- `API_DOCUMENTATION.md` - Complete API reference -- `DEVELOPMENT_GUIDE.md` - Development workflows -- `IMPLEMENTATION_COMPLETE.md` - This file - -### Seed Data -- `db/seeds.rb` - 31 gaming platforms, 30 genres - -## How to Use It - -### 1. Start the Application - -```bash -# Start PostgreSQL -task docker:up - -# Start Rails (first time) -task setup - -# Start Rails (subsequent times) -task server -``` - -### 2. Create Your Account -- Visit http://localhost:3000 -- Click "Sign Up" -- Enter username, email, and password -- You'll be redirected to your dashboard - -### 3. Add Games - -**Option A: Add Individual Games** -- Click "Add Game" from dashboard or games page -- Fill in the form -- Select physical or digital format -- Add genres, rating, notes, etc. - -**Option B: Bulk Import via CSV** -- Click "Import CSV" from games page -- Download the example CSV or create your own -- Upload and import multiple games at once - -**Example CSV:** -```csv -title,platform,format,genres,completion_status,user_rating,condition,price_paid,location,digital_store,date_added,notes -The Legend of Zelda: Ocarina of Time,N64,physical,Action|Adventure,completed,5,cib,45.00,Shelf A,,2024-01-15,Best game ever -Elden Ring,PS5,digital,Action|RPG,currently_playing,5,,,,PlayStation Store,2024-03-01,Amazing open world -``` - -### 4. Create Collections -- Navigate to Collections -- Click "New Collection" -- Create a root collection or subcollection -- Add games to collections from the game edit page - -### 5. Use the API - -**Get an API Token:** -- Go to Settings → API Tokens -- Click "Create New Token" -- Copy the token (you won't see it again!) - -**Make API Requests:** -```bash -# List your games -curl -H "Authorization: Bearer YOUR_TOKEN" \ - http://localhost:3000/api/v1/games - -# Create a game -curl -X POST \ - -H "Authorization: Bearer YOUR_TOKEN" \ - -H "Content-Type: application/json" \ - -d '{"game":{"title":"Halo","platform_id":20,"format":"physical"}}' \ - http://localhost:3000/api/v1/games -``` - -See `API_DOCUMENTATION.md` for complete API reference. - -## What's NOT Yet Implemented - -As discussed, **tests will be built in the next phase**. Everything else from Phase 1 MVP is complete. - -### Still Needed: -- Comprehensive test suite (models, controllers, system tests) -- Pagination UI (backend works, just need view links) - -### ✅ Email System - COMPLETE! -- Password reset emails fully functional -- Mailpit integration for local testing -- Professional HTML and text email templates -- View emails at http://localhost:8025 -- Production-ready (just needs SMTP config) - -### Phase 2 Features (Not in Current Scope): -- Image uploads (cover art, avatars) -- Wishlist functionality -- IGDB API integration -- Digital library auto-import (Steam, etc.) -- SSO/OAuth -- Market value tracking -- Social features - -## Testing the Application - -Since tests aren't written yet, here's how to manually verify everything works: - -1. **User Registration & Login** - - Sign up with a new account ✓ - - Log in ✓ - - Log out ✓ - - Try accessing dashboard without login (should redirect) ✓ - -2. **Game Management** - - Add a physical game with all details ✓ - - Add a digital game ✓ - - Edit a game ✓ - - Delete a game ✓ - - Search for a game ✓ - - Filter by platform, genre, format ✓ - - Sort alphabetically, by date, by rating ✓ - -3. **Bulk Import** - - Create a CSV file with 3-5 games ✓ - - Import via CSV upload ✓ - - Verify all games were created ✓ - - Try importing with invalid data (should show errors) ✓ - -4. **Collections** - - Create a root collection ✓ - - Create a subcollection ✓ - - Add games to collections ✓ - - View collection with games ✓ - - Edit collection ✓ - - Delete collection ✓ - -5. **Dashboard Statistics** - - Verify total games count ✓ - - Check physical/digital breakdown ✓ - - View recently added games ✓ - - View currently playing games ✓ - - Check top platforms and genres ✓ - -6. **API** - - Generate an API token ✓ - - List games via API ✓ - - Create game via API ✓ - - Update game via API ✓ - - Delete game via API ✓ - - Bulk create games via API ✓ - - Verify token authentication works ✓ - - Try accessing API without token (should fail) ✓ - -7. **RLS Security** - - Create two user accounts ✓ - - Add games to each account ✓ - - Verify users can only see their own games ✓ - - Verify API tokens only access own data ✓ - -## Database Schema Verified - -All tables created with proper: -- Foreign keys and indexes -- NOT NULL constraints where needed -- Default values -- Unique constraints -- RLS policies on user-scoped tables -- Proper data types (decimals for prices, dates, enums) - -## Known Issues - -None! The application is fully functional. However: - -1. **Email sending** needs SMTP configuration (controller code is ready) -2. **Pagination links** in views need to be added (backend works) -3. **Tests** need to be written (next phase) - -## Performance Notes - -- All foreign keys are indexed ✓ -- Common query fields are indexed (title, platform_id, user_id, etc.) ✓ -- Eager loading used to avoid N+1 queries ✓ -- Pagination implemented (25 per page) ✓ -- RLS adds minimal overhead (~1-2ms per query) ✓ - -## Security Verified - -- Row Level Security enabled on all user-scoped tables ✓ -- Controllers filter by current_user (defense in depth) ✓ -- Password hashing with bcrypt ✓ -- API token authentication ✓ -- CSRF protection enabled ✓ -- Session security configured ✓ - -## Next Steps - -### Immediate (If Needed) -1. Configure SMTP for password reset emails -2. Add pagination UI links -3. Deploy to production (Kamal config ready) - -### Phase 2 (As Discussed) -1. Write comprehensive test suite -2. Add missing views for items (if needed) -3. Implement Phase 2 features per requirements - -## Files You Should Read - -1. **README.md** - Main documentation, quick start guide -2. **API_DOCUMENTATION.md** - Complete API reference with examples -3. **DEVELOPMENT_GUIDE.md** - How to develop, add features, troubleshoot -4. **PROJECT_SUMMARY.md** - Detailed feature breakdown and architecture -5. **REQUIREMENTS.md** - Original requirements (your spec) - -## Available Commands - -```bash -# Development -task setup # One-time setup -task server # Start server -bin/dev # Server + Tailwind watcher - -# Database -task db:setup # Create, migrate, seed -task db:migrate # Run migrations -task db:reset # Reset database -task console # Rails console - -# Quality -task lint # Run RuboCop -task security # Security checks -task test # Run tests (when written) - -# Docker -task docker:up # Start PostgreSQL -task docker:down # Stop PostgreSQL -task docker:logs # View logs -``` - -## Summary - -✅ **Phase 1 MVP: COMPLETE** -- All features from REQUIREMENTS.md implemented -- Full web interface with Tailwind CSS -- Complete RESTful API with documentation -- Row Level Security at database level -- Comprehensive documentation -- Ready for testing and deployment - -❌ **Not Yet Done:** -- Tests (next phase, as agreed) -- Email configuration (trivial, just needs SMTP settings) - -The application is **production-ready** pending tests and any deployment-specific configuration! - -## Questions? - -Everything should be documented, but if you have questions: -- Check the relevant documentation file -- Look at the code (it's well-commented) -- Check DEVELOPMENT_GUIDE.md for common workflows -- Rails console is your friend: `task console` - -Enjoy building with TurboVault! 🚀🎮 diff --git a/docs/PROJECT_SUMMARY.md b/docs/PROJECT_SUMMARY.md deleted file mode 100644 index dcc89e0..0000000 --- a/docs/PROJECT_SUMMARY.md +++ /dev/null @@ -1,414 +0,0 @@ -# TurboVault - Project Summary - -## Overview - -TurboVault is a comprehensive video game collection tracker built with Rails 8.1.2. It allows users to manage both physical and digital game collections, organize them into collections, track gameplay progress, and view detailed statistics. - -## What's Been Built - -### ✅ Phase 1 - MVP Features (COMPLETED) - -#### 1. Database & Models -- **9 models** with complete associations and validations: - - User (with has_secure_password) - - Platform (31 platforms seeded) - - Genre (30 genres seeded) - - Game (with physical/digital fields) - - GameGenre (join table) - - Collection (with subcollections) - - CollectionGame (join table) - - Item (consoles, controllers, accessories) - - ApiToken - -- **Row Level Security (RLS)** implemented on all user-scoped tables -- Proper indexes on all foreign keys and commonly queried fields -- Enums for format, completion_status, condition, and item_type -- Seed data with 31 platforms and 30 genres - -#### 2. Authentication System -- Email/password authentication with bcrypt -- Session-based authentication for web users -- API token authentication for API access -- Password reset functionality (controllers ready, email sending needs configuration) -- User profile management -- Public/private profile toggle -- RLS integration with authentication - -#### 3. Game Management -- Full CRUD operations for games -- Physical game fields: condition, price_paid, location -- Digital game fields: digital_store -- Multiple genre assignment -- Completion status tracking (backlog, currently_playing, completed, on_hold, not_playing) -- 5-star rating system -- Notes field for personal observations -- Date tracking (auto-set, editable) - -#### 4. Collections & Organization -- Create multiple collections -- Subcollections (one level deep) -- Games can belong to multiple collections -- Collection statistics (game count) -- Root collections view - -#### 5. Search, Filter & Sort -- Search by game title -- Filter by: platform, genre, format, completion status -- Sort by: alphabetical, recently added, highest rated -- Pagination with Kaminari (25 games per page) - -#### 6. Bulk Import -- CSV upload for multiple games -- Validation and error reporting -- Example CSV format provided -- Genre assignment via pipe-separated values -- Platform lookup by name or abbreviation - -#### 7. Dashboard & Statistics -- Total games count -- Physical vs Digital breakdown -- Completion statistics -- Total spent calculation -- Top 5 platforms by game count -- Top 5 genres by game count -- Recently added games (last 5) -- Currently playing games (last 5) - -#### 8. RESTful API (v1) -- Complete CRUD for Games -- Complete CRUD for Collections -- Read-only for Platforms and Genres -- Bulk game creation endpoint -- API Token management -- Token-based authentication -- Per-user data isolation -- JSON responses with error handling - -#### 9. User Interface -- Tailwind CSS styling -- Responsive design (mobile-first) -- Clean, modern interface -- Navigation with authentication state -- Flash messages for user feedback -- Form validations with error display -- Dynamic form fields (physical vs digital) - -#### 10. Views Created -- Homepage/Landing page -- Login/Signup forms -- Dashboard with statistics -- Games index (with filters) -- Game show/detail page -- Game new/edit forms -- CSV import page -- Collections index -- User settings page -- Navigation partial -- Flash messages partial - -## Technical Stack - -- **Framework:** Rails 8.1.2 -- **Database:** PostgreSQL with Row Level Security -- **Frontend:** Hotwire (Turbo + Stimulus) -- **Styling:** Tailwind CSS 4.2 -- **Authentication:** has_secure_password (bcrypt) -- **Pagination:** Kaminari -- **Development:** Docker Compose for PostgreSQL -- **Task Runner:** Taskfile for common operations - -## File Structure - -``` -turbovault-web/ -├── app/ -│ ├── controllers/ -│ │ ├── concerns/ -│ │ │ └── authentication.rb (RLS + session management) -│ │ ├── api/ -│ │ │ └── v1/ -│ │ │ ├── base_controller.rb -│ │ │ ├── games_controller.rb -│ │ │ ├── collections_controller.rb -│ │ │ ├── platforms_controller.rb -│ │ │ └── genres_controller.rb -│ │ ├── dashboard_controller.rb -│ │ ├── games_controller.rb -│ │ ├── collections_controller.rb -│ │ ├── items_controller.rb -│ │ ├── api_tokens_controller.rb -│ │ ├── sessions_controller.rb -│ │ ├── users_controller.rb -│ │ ├── password_resets_controller.rb -│ │ ├── profiles_controller.rb -│ │ └── pages_controller.rb -│ ├── models/ -│ │ ├── user.rb -│ │ ├── game.rb -│ │ ├── platform.rb -│ │ ├── genre.rb -│ │ ├── collection.rb -│ │ ├── item.rb -│ │ ├── api_token.rb -│ │ └── (join models) -│ └── views/ -│ ├── layouts/ -│ ├── pages/ -│ ├── dashboard/ -│ ├── games/ -│ ├── collections/ -│ ├── sessions/ -│ └── users/ -├── db/ -│ ├── migrate/ (10 migrations with RLS) -│ └── seeds.rb (platforms & genres) -├── config/ -│ ├── routes.rb (comprehensive routing) -│ └── database.yml (PostgreSQL config) -├── docker-compose.yml -├── Taskfile.yml -├── REQUIREMENTS.md -├── API_DOCUMENTATION.md -└── PROJECT_SUMMARY.md (this file) -``` - -## What's NOT Yet Implemented - -### Testing -- ❌ Unit tests for models -- ❌ Controller tests -- ❌ System tests -- ❌ API endpoint tests -- ❌ RLS policy tests - -**Status:** Tests will be implemented in the next phase per your request. - -### Additional Views Needed -- ❌ Collection show page (games within collection) -- ❌ Collection new/edit forms -- ❌ Items CRUD views -- ❌ API tokens management page -- ❌ Public profile view -- ❌ Password reset email templates - -### Features Not in Phase 1 MVP -- ❌ Images/cover art -- ❌ Wishlist functionality -- ❌ Digital library auto-import (Steam, PlayStation, etc.) -- ❌ SSO/OAuth -- ❌ IGDB API integration -- ❌ Market value tracking -- ❌ Social features - -## Database Schema - -### Users Table -- email, username, encrypted_password -- bio, profile_public -- password_reset_token, password_reset_sent_at -- **RLS enabled** - -### Games Table -- user_id, platform_id, title, format -- date_added, completion_status, user_rating, notes -- Physical: condition, price_paid, location -- Digital: digital_store -- custom_entry, igdb_id -- **RLS enabled** - -### Collections Table -- user_id, parent_collection_id -- name, description -- **RLS enabled** - -### Items Table -- user_id, platform_id (optional) -- name, item_type, condition -- price_paid, location, date_added, notes -- **RLS enabled** - -### API Tokens Table -- user_id, token, name -- last_used_at, expires_at -- **RLS enabled** - -### Platforms & Genres Tables -- Read-only reference data -- No RLS (public data) - -## How to Get Started - -### 1. Start PostgreSQL -```bash -task docker:up -``` - -### 2. Setup Database -```bash -task db:setup -# or individually: -task db:create -task db:migrate -task db:seed -``` - -### 3. Start Server -```bash -task server -# or -rails server -``` - -### 4. Create Your First User -- Visit http://localhost:3000 -- Click "Sign Up" -- Fill in username, email, password -- You'll be redirected to your dashboard - -### 5. Add Games -- Click "Add Game" from dashboard -- Or use "Import CSV" to bulk add games -- Check `games/import.html.erb` for CSV format - -### 6. Create API Token -- Go to Settings → API Tokens -- Click "Create New Token" -- Copy the token (you won't see it again!) -- Use in API requests - -## API Usage Example - -```bash -# Get your games -curl -H "Authorization: Bearer YOUR_TOKEN" \ - http://localhost:3000/api/v1/games - -# Add a game via API -curl -X POST \ - -H "Authorization: Bearer YOUR_TOKEN" \ - -H "Content-Type: application/json" \ - -d '{"game":{"title":"Elden Ring","platform_id":17,"format":"digital"}}' \ - http://localhost:3000/api/v1/games -``` - -See `API_DOCUMENTATION.md` for complete API reference. - -## CSV Import Format - -```csv -title,platform,format,genres,completion_status,user_rating,condition,price_paid,location,digital_store,date_added,notes -The Legend of Zelda: Ocarina of Time,N64,physical,Action|Adventure,completed,5,cib,45.00,Shelf A,,2024-01-15,Best game ever -Elden Ring,PS5,digital,Action|RPG,currently_playing,5,,,,PlayStation Store,2024-03-01,Amazing -``` - -## Security Features - -1. **Row Level Security (RLS)** - - Enabled on all user-scoped tables - - Database-level isolation - - Protection even if application logic fails - -2. **Defense in Depth** - - Controllers filter by `current_user` - - RLS as additional security layer - - API tokens scoped to user - -3. **Password Security** - - Bcrypt hashing - - Minimum 8 character requirement - - Password confirmation on signup - -4. **CSRF Protection** - - Rails default CSRF tokens - - API uses token authentication - -## Known Issues & Limitations - -1. **Email Sending - FULLY FUNCTIONAL in Development!** ✅ - - Password reset emails work perfectly with Mailpit - - View all emails at http://localhost:8025 - - Production will need real SMTP configuration - -2. **No Pagination UI** - - Kaminari gem installed - - Backend pagination works - - Need to add pagination links to views - -3. **No Image Support** - - No cover art for games - - No user avatars - - Planned for Phase 2 - -4. **Basic Error Handling** - - Works but could be more user-friendly - - Could add better validation messages - - Could add client-side validation - -5. **No Tests Yet** - - Will be added in next phase - - All models and controllers ready for testing - -## Next Steps - -### Immediate (Required for MVP) -1. ✅ Create remaining views (collection forms, items CRUD) -2. ✅ Write comprehensive tests -3. ✅ Add pagination UI -4. ✅ Configure email sending (optional but recommended) - -### Short Term Enhancements -- Add client-side validation -- Improve error messages -- Add loading states -- Implement soft deletes -- Add export functionality (CSV, JSON) -- Add activity feed/history - -### Future Features (Phase 2) -- Image uploads (ActiveStorage) -- IGDB API integration -- Wishlist management -- Digital library auto-import -- SSO/OAuth -- Social features -- Market value tracking -- Mobile native apps - -## Performance Considerations - -- Database indexes on all foreign keys -- Eager loading with `includes()` to avoid N+1 queries -- Pagination limits query size -- RLS adds minimal overhead -- Consider caching for stats/public profiles - -## Deployment Notes - -- Use Kamal for deployment (already configured) -- Or deploy to Railway/Render/Heroku -- PostgreSQL required (RLS support) -- Set environment variables for: - - DATABASE_URL - - SECRET_KEY_BASE - - SMTP settings (if using email) -- Run migrations: `rails db:migrate` -- Run seeds: `rails db:seed` - -## Credits - -Built following the requirements in `REQUIREMENTS.md`. - -Key Technologies: -- Ruby 3.3.10 -- Rails 8.1.2 -- PostgreSQL 16 -- Tailwind CSS 4.2 -- Hotwire (Turbo + Stimulus) - -## Questions? - -Refer to: -- `REQUIREMENTS.md` - Original project requirements -- `API_DOCUMENTATION.md` - Complete API reference -- `Taskfile.yml` - Available development tasks -- Rails guides at https://guides.rubyonrails.org/ diff --git a/docs/README.md b/docs/README.md index 286fbc7..aefd501 100644 --- a/docs/README.md +++ b/docs/README.md @@ -2,132 +2,42 @@ Complete documentation for TurboVault - Video Game Collection Tracker -## 📖 Quick Links +## 📖 Documentation ### Getting Started - [Main README](../README.md) - Project overview - ⭐ [Quick Start Guide](QUICK_START.md) - **Deploy in minutes!** -- [Development Guide](DEVELOPMENT_GUIDE.md) - Local development setup - [Demo Account](DEMO_ACCOUNT.md) - Try the demo -### Deployment -- [Deployment Checklist](DEPLOYMENT_CHECKLIST.md) - Complete deployment steps -- [GitHub Actions Setup](GITHUB_ACTIONS_SETUP.md) - CI/CD pipeline -- [Deployment Guide](DEPLOYMENT.md) - Full deployment reference - -### Kubernetes -- [Kubernetes README](../k8s/README.md) - K8s deployment guide -- [Container Registry Setup](../REGISTRY_SIMPLIFIED.md) - Registry options - -### GitHub Configuration -- [GitHub Secrets Setup](../.github/SECRETS_SETUP.md) - Optional registry configuration -- [What to Commit](../.github/WHAT_TO_COMMIT.md) - Safe for open source +### Deployment & Development +- [Deployment Guide](DEPLOYMENT.md) - Complete deployment reference +- [Development Guide](DEVELOPMENT_GUIDE.md) - Local development & contributing +- [Kubernetes README](../k8s/README.md) - Kubernetes deployment ### Features - [API Documentation](API_DOCUMENTATION.md) - RESTful API reference - [IGDB Integration](IGDB_INTEGRATION.md) - Game metadata matching - [Themes](THEMES.md) - Theme customization -### Reference -- [Project Summary](PROJECT_SUMMARY.md) - Feature overview -- [Requirements](REQUIREMENTS.md) - Original requirements -- [Implementation Complete](IMPLEMENTATION_COMPLETE.md) - Development progress -- [Email Setup](EMAIL_SETUP_SUMMARY.md) - Email configuration -- [Testing Emails](TESTING_EMAILS.md) - Email testing guide +### Configuration +- [GitHub Secrets Setup](../.github/SECRETS_SETUP.md) - Optional custom registry +- [What to Commit](../.github/WHAT_TO_COMMIT.md) - Safe for open source --- -## 📂 Documentation Structure - -``` -turbovault-web/ -├── README.md # Main project README -├── LICENSE # MIT License -│ -├── docs/ # All documentation (you are here!) -│ ├── README.md # This file -│ ├── DEPLOYMENT_CHECKLIST.md # Step-by-step deployment -│ ├── GITHUB_ACTIONS_SETUP.md # CI/CD setup -│ ├── DEPLOYMENT.md # Complete deployment guide -│ ├── DEVELOPMENT_GUIDE.md # Local development -│ ├── API_DOCUMENTATION.md # API reference -│ ├── IGDB_INTEGRATION.md # IGDB features -│ └── ... # Other docs -│ -├── .github/ -│ ├── workflows/ # GitHub Actions -│ ├── SECRETS_SETUP.md # GitHub Secrets guide -│ └── WHAT_TO_COMMIT.md # Open source safety -│ -└── k8s/ - ├── README.md # Kubernetes deployment - ├── GITEA_SETUP.md # Gitea registry setup - └── *.yaml # K8s manifests -``` - ---- - -## 🚀 Deployment Path - -**New to TurboVault deployment?** Follow this path: +## 🚀 Quick Navigation +**New to TurboVault?** 1. Read [Main README](../README.md) -2. **Follow [Quick Start Guide](QUICK_START.md)** ⭐ Start here! -3. Or use [Deployment Checklist](DEPLOYMENT_CHECKLIST.md) for detailed steps -4. Optional: [GitHub Secrets Setup](../.github/SECRETS_SETUP.md) for custom registries +2. Deploy with [Quick Start Guide](QUICK_START.md) ⭐ +3. Or develop locally with [Development Guide](DEVELOPMENT_GUIDE.md) + +**Looking for something specific?** +- Deploying to production → [DEPLOYMENT.md](DEPLOYMENT.md) +- Using the API → [API_DOCUMENTATION.md](API_DOCUMENTATION.md) +- Game metadata features → [IGDB_INTEGRATION.md](IGDB_INTEGRATION.md) +- Customizing themes → [THEMES.md](THEMES.md) --- -## 🛠️ Development Path - -**Want to contribute or run locally?** - -1. Read [Main README](../README.md) -2. Follow [Development Guide](DEVELOPMENT_GUIDE.md) -3. Review [API Documentation](API_DOCUMENTATION.md) -4. Understand [IGDB Integration](IGDB_INTEGRATION.md) - ---- - -## 💡 Common Questions - -**Where do I start?** -- Deploying: [QUICK_START.md](QUICK_START.md) ⭐ -- Developing: [DEVELOPMENT_GUIDE.md](DEVELOPMENT_GUIDE.md) - -**How do I set up GitHub Actions?** -- No setup needed! GitHub Container Registry works automatically -- See [QUICK_START.md](QUICK_START.md) -- For custom registries: [../.github/SECRETS_SETUP.md](../.github/SECRETS_SETUP.md) - -**What container registry should I use?** -- Default: GitHub Container Registry (ghcr.io) - free, built-in -- See [../REGISTRY_SIMPLIFIED.md](../REGISTRY_SIMPLIFIED.md) for other options - -**What's safe to commit publicly?** -- [../.github/WHAT_TO_COMMIT.md](../.github/WHAT_TO_COMMIT.md) - -**How do I use the API?** -- [API_DOCUMENTATION.md](API_DOCUMENTATION.md) - -**What is IGDB?** -- [IGDB_INTEGRATION.md](IGDB_INTEGRATION.md) - ---- - -## 📝 Documentation Updates - -When adding new documentation: - -1. Create `.md` file in this `docs/` folder -2. Add entry to this README -3. Update cross-references in other docs -4. Use relative paths: - - Other docs: `[link](FILENAME.md)` - - Root files: `[link](../FILENAME.md)` - - .github: `[link](../.github/FILENAME.md)` - - k8s: `[link](../k8s/FILENAME.md)` - ---- - -**Need help?** Check the [Main README](../README.md) or open an issue on GitHub. +**Need help?** Check the [Main README](../README.md) or [open an issue](https://github.com/yourusername/turbovault/issues). diff --git a/docs/REQUIREMENTS.md b/docs/REQUIREMENTS.md deleted file mode 100644 index b2379c3..0000000 --- a/docs/REQUIREMENTS.md +++ /dev/null @@ -1,555 +0,0 @@ -# TurboVault Web - Requirements Document - -## Project Overview - -**TurboVault** is a video game collection tracker for managing both physical and digital game collections. Users can organize their games into collections and subcollections, track what they're playing, rate games, and view their collection statistics. - -**Target Users:** Video game collectors who want to catalog and track their physical and digital game libraries. - ---- - -## Technical Stack - -- **Framework:** Rails 8.1.2 -- **Database:** PostgreSQL (all environments) with Row Level Security (RLS) -- **Frontend:** Hotwire (Turbo + Stimulus), Importmap -- **Development:** Nix + direnv for environment management, Taskfile for task automation, Docker Compose for services -- **Authentication:** Built-in (email/password) → SSO in Phase 2 -- **API:** RESTful JSON API for all CRUD operations -- **Future Integrations:** IGDB API for game metadata - ---- - -## User Roles & Authentication - -### Phase 1: Built-in Authentication -- Email/password authentication -- Password reset flow -- Email verification (optional but recommended) -- Session management - -### Users -- Each user has their own collections -- Collections are **private by default** -- Users can opt-in to make collections public on their profile -- User profiles: Keep simple (username, optional bio, collection visibility settings) - ---- - -## Phase 1: Core Features (MVP) - -### 1. Game Management - -**Game Attributes:** -- Title (required) -- Platform/System (required) - e.g., Nintendo 64, PlayStation 5, PC -- Genres (multiple) - e.g., RPG, Action, Puzzle -- Format: Physical or Digital (required) -- Date Added to Collection (auto-set, editable) -- Completion Status: Backlog, Currently Playing, Completed, On Hold, Not Playing -- User Rating (optional, 1-5 stars) -- Notes (freeform text field) - -**Physical Game Specific:** -- Condition: CIB (Complete in Box), Loose, Sealed, etc. -- Price Paid (optional, decimal) -- Location (optional, freeform text) - e.g., "Shelf A", "Storage Box 3" - -**Digital Game Specific:** -- Digital Store/Platform - e.g., Steam, PlayStation Store, eShop - -**Game Entry:** -- Pick from existing game list (seeded database) -- If not found, allow user to create custom game entry -- All fields manually editable - -### 2. Collections & Organization - -**Collections:** -- Users can create multiple collections -- Collections can have subcollections (nested one level) - - Example: "Nintendo 64 Games" → "Mario Games" subcollection -- Collections have: Name, Description (optional), Game count -- Games can belong to multiple collections - -**Default Views:** -- All Games (full library) -- By Platform (all games for a specific system) -- By Genre (all games of a specific genre) -- By Collection (user-created collections) -- Currently Playing -- Completed Games -- Backlog - -### 3. Search, Filter & Sort - -**Search:** -- Search by game title -- Search across all user's games - -**Filter:** -- By Platform -- By Genre -- By Format (Physical/Digital) -- By Completion Status -- By Collection - -**Sort:** -- Alphabetically (A-Z, Z-A) -- Date Added (newest/oldest) -- Rating (highest/lowest) -- Platform - -### 4. Statistics & Dashboard - -**Collection Stats:** -- Total games in collection -- Games by platform (count) -- Games by genre (count) -- Physical vs Digital breakdown -- Completion statistics (backlog count, completed count, etc.) -- Total spent (sum of price paid fields) - -**Dashboard:** -- Recently added games -- Currently playing games -- Collection overview stats -- Quick actions (Add game, View collection, etc.) - -### 5. Non-Game Items (Nice to Have - Phase 1 if time permits) - -**Item Types:** -- Consoles -- Controllers -- Accessories/Peripherals -- Other (freeform) - -**Attributes:** -- Name -- Type -- Platform/Compatibility -- Condition -- Price Paid (optional) -- Location (optional) -- Date Added -- Notes - -### 6. User Profiles & Privacy - -**Profile Settings:** -- Username (required, unique) -- Email (required) -- Bio (optional) -- Privacy: Make collection public/private toggle - -**Public Profile (when opted-in):** -- Show username and bio -- Show public collections -- Show basic stats (total games, platforms collected, etc.) -- Hide personal data (email, prices paid, locations) - -### 7. Bulk Game Insert - -**Critical for user onboarding** - Allow users to quickly add multiple games at once: -- Upload CSV file with game data -- Or use a multi-row form interface -- Validate entries before saving -- Show summary of successful/failed imports -- Support bulk adding to specific collection - -**CSV Format (minimum required fields):** -- Title, Platform, Format (Physical/Digital) -- Optional fields: Genres, Condition, Price Paid, Date Added, Location, Notes, Rating, Completion Status - -### 8. RESTful API - -All features must be accessible via API endpoints for future integrations: -- `GET /api/v1/games` - List user's games (with filters) -- `POST /api/v1/games` - Create new game -- `POST /api/v1/games/bulk` - Bulk create games -- `GET /api/v1/games/:id` - Show game details -- `PUT/PATCH /api/v1/games/:id` - Update game -- `DELETE /api/v1/games/:id` - Delete game -- Similar endpoints for collections, items, etc. - -**Authentication:** -- **Web users:** Session-based authentication (standard Rails sessions) -- **API users:** Token-based authentication (API keys) for external integrations -- Support both authentication methods simultaneously - -**API Token Permissions:** -- API tokens have the same permissions as the user who created them -- Tokens are scoped to the user's own data only (can't access other users' collections) -- Users can only create/read/update/delete their own games, collections, and items - ---- - -## Data Models - -### User -- email (string, required, unique, indexed) -- encrypted_password (string, required) -- username (string, required, unique, indexed) -- bio (text, optional) -- profile_public (boolean, default: false) -- timestamps - -### ApiToken -- user_id (foreign key, required, indexed) -- token (string, required, unique, indexed) -- name (string, optional) - e.g., "Mobile App", "Third Party Integration" -- last_used_at (datetime, optional) -- expires_at (datetime, optional) -- timestamps - -### Game -- user_id (foreign key, required, indexed) -- title (string, required, indexed) -- platform_id (foreign key, required, indexed) -- format (enum: physical/digital, required) -- date_added (date, required, default: today) -- completion_status (enum: backlog/currently_playing/completed/on_hold/not_playing, optional) -- user_rating (integer 1-5, optional) - 5-star system -- notes (text, optional) -- **Physical fields:** - - condition (enum: cib/loose/sealed/good/fair, optional) - - price_paid (decimal, optional) - - location (string, optional) -- **Digital fields:** - - digital_store (string, optional) - e.g., "Steam", "PlayStation Store" -- custom_entry (boolean, default: false) - true if user-created -- igdb_id (integer, optional, indexed) - for future IGDB integration -- timestamps - -### Platform -- name (string, required, unique) - e.g., "Nintendo 64", "PlayStation 5" -- abbreviation (string, optional) - e.g., "N64", "PS5" -- manufacturer (string, optional) - e.g., "Nintendo", "Sony" -- timestamps - -### Genre -- name (string, required, unique) - e.g., "RPG", "Action", "Puzzle" -- timestamps - -### GameGenre (Join Table) -- game_id (foreign key, required, indexed) -- genre_id (foreign key, required, indexed) - -### Collection -- user_id (foreign key, required, indexed) -- parent_collection_id (foreign key, optional, indexed) - for subcollections -- name (string, required) -- description (text, optional) -- timestamps - -### CollectionGame (Join Table) -- collection_id (foreign key, required, indexed) -- game_id (foreign key, required, indexed) -- position (integer, optional) - for manual ordering - -### Item (Nice to Have - Phase 1) -- user_id (foreign key, required, indexed) -- name (string, required) -- item_type (enum: console/controller/accessory/other, required) -- platform_id (foreign key, optional) -- condition (string, optional) -- price_paid (decimal, optional) -- location (string, optional) -- date_added (date, required, default: today) -- notes (text, optional) -- igdb_id (integer, optional, indexed) - for future integration -- timestamps - -**Relationships:** -- User has_many :games -- User has_many :collections -- User has_many :items -- User has_many :api_tokens -- ApiToken belongs_to :user -- Game belongs_to :user -- Game belongs_to :platform -- Game has_many :genres, through: :game_genres -- Game has_many :collections, through: :collection_games -- Collection belongs_to :user -- Collection belongs_to :parent_collection (optional, self-referential) -- Collection has_many :subcollections (self-referential) -- Collection has_many :games, through: :collection_games -- Platform has_many :games -- Genre has_many :games, through: :game_genres - ---- - -## Phase 2: Future Features - -### Images -- Game cover art -- Item photos -- User avatars - -### Wishlist -- Games user wants to buy -- Price tracking for wishlisted games -- Notifications when price drops - -### Digital Library Integration -- Auto-import from Steam, PlayStation, Xbox, Nintendo -- Auto-update when new games purchased -- Sync digital library periodically - -### SSO (Single Sign-On) -- OAuth with Google, GitHub, etc. -- Keep email/password as fallback - -### IGDB Integration -- Search IGDB when adding games -- Auto-populate game metadata (title, genres, release date, cover art) -- Sync game data periodically - -### Market Value Tracking -- Integration with PriceCharting API or similar -- Show estimated current market value -- Track value over time - -### Enhanced Features -- Game history/timeline -- Play session tracking -- Achievement/trophy tracking -- Social features (friends, sharing collections) -- Collection import/export (CSV, JSON) - ---- - -## UI/UX Guidelines - -### Design Style -- Clean, modern interface -- Focus on readability and quick data entry -- Mobile-responsive (mobile-first approach) - -### Styling Framework -- **Recommendation:** Tailwind CSS (modern, utility-first, great with Hotwire) -- Alternative: Bootstrap or custom CSS - -### Key Pages/Views - -1. **Homepage/Landing** - Public landing page with login/signup -2. **Dashboard** - Main view after login, shows stats and recent activity -3. **Game Library** - Full game list with filters, search, sort -4. **Game Detail** - Individual game view/edit page -5. **Add Game** - Form to add new game (with search/create flow) -6. **Bulk Import** - Upload CSV or multi-row form to add multiple games -7. **Collections** - List of user's collections -8. **Collection Detail** - Games within a specific collection -9. **Platform View** - All games for a specific platform -10. **Genre View** - All games of a specific genre -11. **Settings** - User profile, privacy settings, and API token management -12. **Public Profile** - View-only profile page (when public) - -### UX Considerations -- Quick add game flow (minimal clicks) -- Bulk actions (add multiple games to collection, etc.) -- Keyboard shortcuts for power users -- Auto-save forms where possible -- Clear visual distinction between physical and digital games -- Empty states with helpful CTAs - ---- - -## Security & Performance - -### Security -- CSRF protection (Rails default) -- XSS prevention (Rails default) -- SQL injection prevention (use parameterized queries) -- Secure password storage (bcrypt) -- HTTPS only in production -- Rate limiting on API endpoints -- User data isolation (users can only access their own data) -- **PostgreSQL Row Level Security (RLS):** - - Enable RLS on all user-scoped tables (games, collections, items, api_tokens) - - Create policies to ensure users can only access their own data - - Defense in depth - even if application logic fails, database enforces isolation - - Example: `CREATE POLICY user_games ON games FOR ALL TO app_user USING (user_id = current_setting('app.current_user_id')::bigint);` - -### Performance -- Database indexing on foreign keys and commonly queried fields -- Pagination for large game lists (25-50 per page) -- Eager loading to avoid N+1 queries -- Consider caching for stats and public profiles - ---- - -## Testing Strategy - -- **Unit tests:** Models and business logic -- **Integration tests:** Controllers and API endpoints -- **System tests:** Key user flows (add game, create collection, etc.) -- **Target coverage:** 80%+ -- **Framework:** Minitest (Rails default) - -**Critical flows to test:** -1. User registration and authentication -2. Add game to collection -3. Bulk import games (CSV) -4. Create and manage collections -5. Search and filter games -6. Update game details -7. API endpoints -8. RLS policies (ensure users can't access other users' data) - ---- - -## Deployment - -### Recommended Setup -- **Hosting:** Kamal (already configured) or Railway/Render for simplicity -- **Database:** PostgreSQL (all environments - dev, test, production) -- **Storage:** Local filesystem initially, S3 for Phase 2 (images) -- **Email:** Postmark or Sendgrid -- **Monitoring:** Sentry or Honeybadger for errors - -**Database Setup Notes:** -- Use Docker Compose for PostgreSQL (see `docker-compose.yml` in project root) -- Run `docker compose up -d` to start PostgreSQL container -- Enable and configure Row Level Security (RLS) policies during initial migration -- Set up database user with appropriate permissions for RLS - -### CI/CD -- Gitea Actions (run tests on push, deploy on merge to main) - ---- - -## Seed Data - -### Initial Platforms (Examples) -- Nintendo: NES, SNES, N64, GameCube, Wii, Wii U, Switch -- Sony: PlayStation, PS2, PS3, PS4, PS5, PSP, PS Vita -- Microsoft: Xbox, Xbox 360, Xbox One, Xbox Series X/S -- Sega: Genesis, Saturn, Dreamcast, Game Gear -- PC, Mobile (iOS/Android), Arcade - -### Initial Genres (Examples) -- Action, Adventure, RPG, JRPG, Strategy, Simulation -- Platformer, Fighting, Racing, Sports, Puzzle -- Horror, Stealth, Shooter (FPS/TPS), Rhythm, Visual Novel - -### Sample Games (for testing) -- Seed 20-30 popular games across different platforms for testing - ---- - -## Success Metrics - -- User can add their first game in < 2 minutes -- Search returns results in < 500ms -- Mobile-responsive on all major screen sizes -- API response time < 200ms for standard queries -- Zero data leaks between users - ---- - -## Decisions Made - -1. **Completion status values:** Backlog, Currently Playing, Completed, On Hold, Not Playing ✅ -2. **Rating scale:** 5-star system (1-5 integer) ✅ -3. **Subcollections:** One level deep only ✅ -4. **API authentication:** Session-based for web users, API token-based for external integrations ✅ -5. **Game list source:** Manually seeded for now, IGDB integration in Phase 2. Add `igdb_id` field for future linking ✅ -6. **API token permissions:** Same permissions as the user who created them (scoped to own collection) ✅ -7. **Database:** PostgreSQL with Row Level Security (RLS) for all environments ✅ - ---- - -## Out of Scope (Phase 1) - -- Images/cover art -- Wishlist functionality -- Digital library auto-import -- SSO/OAuth -- IGDB API integration (will be manual entry only) -- Market value tracking/price alerts -- Social features (following, sharing) -- Mobile native apps -- Game recommendations - ---- - -## Timeline Suggestion - -**Week 1-2:** Setup (Docker, PostgreSQL, models, migrations, authentication) -**Week 3-4:** Core game CRUD, bulk import, collections, API -**Week 5-6:** Search/filter, stats, UI polish -**Week 7-8:** Testing, RLS policies, bug fixes, deployment - -## Getting Started - -### Prerequisites -- [Nix](https://nixos.org/download.html) with direnv -- All dependencies (Ruby, Task, Docker, PostgreSQL client) are automatically available via Nix shell environment - -### Environment Setup - -When you `cd` into the project directory, direnv will automatically load the Nix environment: -```bash -cd turbovault-web -# direnv loads automatically, making Ruby, Task, Docker, etc. available -``` - -If this is your first time, allow direnv: -```bash -direnv allow -``` - -### Quick Setup - -**Option 1: One Command Setup** -```bash -task setup -``` - -This runs: PostgreSQL startup, dependency installation, and database setup. - -**Option 2: Step by Step** -```bash -# 1. Start PostgreSQL container -task docker:up - -# 2. Install dependencies -task install - -# 3. Setup database (create, migrate, seed) -task db:setup - -# 4. Start Rails server -task server -``` - -### Common Development Tasks - -```bash -task # List all available tasks -task server # Start Rails server -task console # Rails console -task test # Run tests -task lint # Run RuboCop -task security # Run security checks -task db:migrate # Run migrations -task db:reset # Reset database -task docker:logs # View PostgreSQL logs -task docker:down # Stop PostgreSQL -``` - -See `Taskfile.yml` for complete list of tasks. - ---- - -## Notes - -- Keep API-first approach in mind - all web features should be available via API -- Design database with future IGDB integration in mind (`igdb_id` fields added) -- Consider adding soft deletes for games/collections (paranoia gem) -- Make sure to handle timezones properly for date_added fields -- **Nix + direnv** manages all development dependencies (Ruby, Task, Docker, PostgreSQL) -- **Docker Compose** is used for PostgreSQL - makes setup consistent across environments -- **Taskfile** is used for development tasks - run `task` to see all available commands (provided via Nix) -- Default dev credentials: `postgres/postgres` (configure via ENV vars for production) diff --git a/docs/TESTING_EMAILS.md b/docs/TESTING_EMAILS.md deleted file mode 100644 index 4de6f80..0000000 --- a/docs/TESTING_EMAILS.md +++ /dev/null @@ -1,274 +0,0 @@ -# Testing Emails Locally with Mailpit - -TurboVault is configured to use **Mailpit** for local email testing. Mailpit captures all emails sent by the application so you can view them in a web interface without actually sending real emails. - -## Quick Start - -### 1. Start the Services - -```bash -task docker:up -``` - -This starts both PostgreSQL and Mailpit. You'll see: -``` -PostgreSQL: localhost:5432 -Mailpit UI: http://localhost:8025 -``` - -### 2. Access Mailpit Web UI - -Open your browser and visit: -``` -http://localhost:8025 -``` - -You'll see the Mailpit interface where all emails will appear. - -### 3. Test Password Reset Email - -1. Start your Rails server: - ```bash - task server - ``` - -2. Visit http://localhost:3000 - -3. Click "Login" then "Forgot your password?" - -4. Enter any email address from a user account you created - -5. Check Mailpit at http://localhost:8025 - you'll see the password reset email! - -6. Click on the email to view it (both HTML and text versions) - -7. Click the "Reset My Password" link in the email to test the flow - -## Features - -### Web Interface (http://localhost:8025) - -- **View all emails** sent by your Rails app -- **Search emails** by recipient, subject, or content -- **View both HTML and text versions** of emails -- **Test responsive design** - resize the preview -- **Download emails** as .eml files -- **View email headers** and technical details -- **Clear all emails** when you want to start fresh - -### API Access - -Mailpit also has an API if you want to automate testing: - -```bash -# Get all emails -curl http://localhost:8025/api/v1/messages - -# Get specific email -curl http://localhost:8025/api/v1/message/MESSAGE_ID - -# Delete all emails -curl -X DELETE http://localhost:8025/api/v1/messages -``` - -## Configuration - -The configuration is already set up in: - -### Docker Compose (`docker-compose.yml`) -```yaml -mailpit: - image: axllent/mailpit:latest - ports: - - "1025:1025" # SMTP server - - "8025:8025" # Web UI -``` - -### Rails Development Config (`config/environments/development.rb`) -```ruby -config.action_mailer.delivery_method = :smtp -config.action_mailer.smtp_settings = { - address: "localhost", - port: 1025, - enable_starttls_auto: false -} -``` - -## Testing Other Emails - -### Create a New Mailer - -```bash -rails generate mailer UserMailer welcome -``` - -### Send Test Email from Rails Console - -```bash -rails console - -# Send password reset -user = User.first -PasswordResetMailer.reset_password(user).deliver_now - -# Check Mailpit - email should appear! -``` - -### Send Email from Your Code - -```ruby -# In a controller or model -PasswordResetMailer.reset_password(user).deliver_later -``` - -## Common Tasks - -### View Mailpit Web UI -```bash -task mailpit -# or just open http://localhost:8025 -``` - -### Check Mailpit Logs -```bash -task docker:logs:mailpit -``` - -### Restart Mailpit -```bash -docker compose restart mailpit -``` - -### Stop All Services -```bash -task docker:down -``` - -## Tips - -1. **Keep Mailpit open** in a browser tab during development -2. **Emails appear instantly** - no delay like real SMTP -3. **No email quota limits** - send as many test emails as you want -4. **All emails are captured** - can't accidentally send to real addresses -5. **Automatic cleanup** - emails are cleared when you restart Mailpit -6. **Mobile testing** - Mailpit UI is responsive, test on different screen sizes - -## Troubleshooting - -### Emails Not Appearing? - -**Check Mailpit is running:** -```bash -docker compose ps -``` - -You should see `turbovault_mailpit` running. - -**Check Rails is configured correctly:** -```bash -rails console -> Rails.application.config.action_mailer.delivery_method -=> :smtp -> Rails.application.config.action_mailer.smtp_settings -=> {:address=>"localhost", :port=>1025, :enable_starttls_auto=>false} -``` - -**Check Rails logs:** -```bash -tail -f log/development.log -``` - -Look for lines like: -``` -Sent mail to user@example.com -``` - -**Restart everything:** -```bash -task docker:down -task docker:up -# Then restart Rails server -``` - -### Can't Access Web UI? - -Make sure port 8025 is not in use: -```bash -lsof -i :8025 -``` - -If something else is using it, stop that service or change Mailpit's port in `docker-compose.yml`. - -### Emails Sent But Not in Mailpit? - -Check that Rails is actually sending to localhost:1025: -```bash -rails console -> ActionMailer::Base.delivery_method -=> :smtp -> ActionMailer::Base.smtp_settings -=> {:address=>"localhost", :port=>1025, ...} -``` - -## Production Configuration - -When you deploy to production, you'll need real SMTP settings. Update `config/environments/production.rb`: - -```ruby -config.action_mailer.delivery_method = :smtp -config.action_mailer.smtp_settings = { - address: ENV['SMTP_ADDRESS'], - port: ENV['SMTP_PORT'], - user_name: ENV['SMTP_USERNAME'], - password: ENV['SMTP_PASSWORD'], - authentication: 'plain', - enable_starttls_auto: true -} -``` - -Common SMTP providers: -- **SendGrid** - Free tier: 100 emails/day -- **Mailgun** - Free tier: 5,000 emails/month -- **Postmark** - Free tier: 100 emails/month -- **AWS SES** - $0.10 per 1,000 emails -- **Gmail SMTP** - Free but limited - -## Mailpit vs Other Tools - -### Mailpit (Current) -✅ Modern, actively maintained -✅ Fast and lightweight -✅ Great UI -✅ Built-in API - -### MailHog (Alternative) -⚠️ No longer actively maintained -⚠️ Older UI -✅ Still works fine - -### MailCatcher (Alternative) -⚠️ Requires Ruby installation -⚠️ Less modern - -We chose Mailpit because it's actively maintained and has the best developer experience. - -## Resources - -- [Mailpit GitHub](https://github.com/axllent/mailpit) -- [Mailpit Documentation](https://mailpit.axllent.org/) -- [Rails Action Mailer Guide](https://guides.rubyonrails.org/action_mailer_basics.html) - -## Summary - -**For Local Development:** -- Mailpit captures all emails at http://localhost:8025 -- No real emails sent -- Perfect for testing email templates and flows -- Already configured, just `task docker:up` and go! - -**For Production:** -- Configure real SMTP provider in environment variables -- Set SMTP_ADDRESS, SMTP_USERNAME, SMTP_PASSWORD -- Emails will be sent for real - -Happy testing! 📧