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

Condenses Documentation

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

321
docs/QUICK_START.md
View File

@@ -1,305 +1,50 @@
# 🚀 TurboVault Quick Start Guide
# Quick Start Guide
Get TurboVault deployed to Kubernetes in minutes!
Get TurboVault running locally in minutes.
## Prerequisites
## Local Development
- GitHub account
- Kubernetes cluster (k3s, minikube, EKS, GKE, etc.)
- kubectl configured
- PostgreSQL database (or use in-cluster Helm chart)
### Prerequisites
## Step 1: Push to GitHub
- Ruby 3.3+
- Docker (for services)
### Setup
```bash
cd turbovault-web
# Clone
git clone https://github.com/ryankazokas/turbovault-app.git
cd turbovault
# Initialize git
git init
git add .
git commit -m "Initial commit: TurboVault"
# Start services (PostgreSQL + Mailpit)
task docker:up
# Add your GitHub remote
git remote add origin https://github.com/YOUR_USERNAME/turbovault.git
git push -u origin main
# Setup database
task db:setup
# Start server
task dev
```
## Step 2: Tag a Release
Visit **http://localhost:3000**
```bash
git tag v1.0.0
git push origin v1.0.0
```
### Demo Account
**What happens:**
- GitHub Actions automatically triggers
- Builds Docker image
- Pushes to GitHub Container Registry (ghcr.io)
- Image: `ghcr.io/YOUR_USERNAME/turbovault:v1.0.0`
- Email: `demo@turbovault.com`
- Password: `password123`
**Check progress:** GitHub → Actions tab
## Optional: IGDB Integration
## Step 3: Prepare Kubernetes Secrets
For automatic game metadata:
```bash
# Copy the template
cp k8s/secrets.yaml.example k8s/secrets.yaml
1. Create app at https://dev.twitch.tv
2. Add to `.env`:
```bash
IGDB_CLIENT_ID=your_id
IGDB_CLIENT_SECRET=your_secret
```
3. Restart server
# Generate Rails secret
rails secret
# Copy output
## Deployment
# Edit secrets.yaml
nano k8s/secrets.yaml
```
Add your values:
- `SECRET_KEY_BASE` - from `rails secret` command
- `DATABASE_PASSWORD` - your PostgreSQL password
- `IGDB_CLIENT_ID` (optional) - from https://dev.twitch.tv
- `IGDB_CLIENT_SECRET` (optional) - from Twitch developer portal
**Important:** Do NOT commit `k8s/secrets.yaml` (it's gitignored)
## Step 4: Update Kubernetes Manifests
Edit `k8s/deployment.yaml` and `k8s/migrate-job.yaml`:
```yaml
# Change this line:
image: ghcr.io/username/turbovault:latest
# To your actual GitHub username:
image: ghcr.io/YOUR_USERNAME/turbovault:v1.0.0
```
Edit `k8s/configmap.yaml`:
```yaml
DATABASE_HOST: "your-postgres-host" # e.g., postgres-service or external host
DATABASE_NAME: "turbovault_production"
DATABASE_USERNAME: "turbovault"
```
Edit `k8s/ingress.yaml` (optional):
```yaml
# Change to your domain
host: turbovault.yourdomain.com
```
Or skip ingress and use port-forwarding for testing.
## Step 5: Deploy to Kubernetes
### Option A: Automated Script
```bash
./scripts/deploy-k8s.sh
```
Follow the prompts:
- Enter registry: `ghcr.io/YOUR_USERNAME`
- Is it private? `n` (if image is public) or `y` (if private)
- Deployment starts!
### Option B: Manual
```bash
# Apply manifests
kubectl apply -f k8s/namespace.yaml
kubectl apply -f k8s/configmap.yaml
kubectl apply -f k8s/secrets.yaml
# Run database migration
kubectl apply -f k8s/migrate-job.yaml
kubectl wait --for=condition=complete --timeout=300s job/turbovault-migrate -n turbovault
# Deploy application
kubectl apply -f k8s/deployment.yaml
kubectl apply -f k8s/service.yaml
kubectl apply -f k8s/ingress.yaml # optional
```
## Step 6: Verify Deployment
```bash
# Check pods
kubectl get pods -n turbovault
# Should show:
# NAME READY STATUS RESTARTS AGE
# turbovault-xxxxxxxxxx-xxxxx 1/1 Running 0 30s
# turbovault-xxxxxxxxxx-xxxxx 1/1 Running 0 30s
# Check logs
kubectl logs -f deployment/turbovault -n turbovault
```
## Step 7: Access the Application
### Option A: Via Ingress (if configured)
Visit: `https://turbovault.yourdomain.com`
### Option B: Port Forward (for testing)
```bash
kubectl port-forward svc/turbovault-service 3000:80 -n turbovault
```
Visit: `http://localhost:3000`
### Option C: LoadBalancer (cloud)
```bash
kubectl get svc turbovault-service -n turbovault
# Get EXTERNAL-IP and visit that IP
```
## Step 8: Create Admin Account
1. Visit the application
2. Click **Sign Up**
3. Create your account
4. Start adding games!
## 🎉 You're Done!
TurboVault is now running on Kubernetes!
## Next Steps
### Make it Public
Want others to access your package?
1. Go to GitHub → Your Profile → Packages
2. Find `turbovault` package
3. Package Settings → Change Visibility → Public
### Keep it Private
By default, GitHub Container Registry packages are private. Only you can pull the image. Perfect for personal deployments!
For Kubernetes to pull private images:
```bash
kubectl create secret docker-registry ghcr-secret \
--docker-server=ghcr.io \
--docker-username=YOUR_USERNAME \
--docker-password=YOUR_GITHUB_TOKEN \
--namespace=turbovault
```
Then uncomment in `k8s/deployment.yaml`:
```yaml
imagePullSecrets:
- name: ghcr-secret
```
### Add SSL/TLS
Install cert-manager and configure Let's Encrypt:
See [DEPLOYMENT.md](DEPLOYMENT.md) for full instructions.
### Update the App
When you want to deploy a new version:
```bash
# Make changes
git add .
git commit -m "Add new feature"
git push origin main
# Create new tag
git tag v1.1.0
git push origin v1.1.0
# Wait for GitHub Actions to build
# Update deployment
kubectl set image deployment/turbovault \
turbovault=ghcr.io/YOUR_USERNAME/turbovault:v1.1.0 \
-n turbovault
# Watch rollout
kubectl rollout status deployment/turbovault -n turbovault
```
## Troubleshooting
### Pods not starting
```bash
kubectl describe pod -l app=turbovault -n turbovault
```
Common issues:
- Image pull error → Check image path in deployment.yaml
- Database connection → Check secrets.yaml and configmap.yaml
- Crash loop → Check logs: `kubectl logs -l app=turbovault -n turbovault`
### Can't access application
```bash
# Check service
kubectl get svc -n turbovault
# Check ingress (if using)
kubectl get ingress -n turbovault
# Try port-forward to test
kubectl port-forward svc/turbovault-service 3000:80 -n turbovault
```
### Build failed
Go to GitHub → Actions → Click on failed workflow
Common issues:
- Dockerfile error → Fix and push again
- Permission denied → Check workflow has `packages: write` permission
## Database Setup
### Option 1: External PostgreSQL (Recommended)
Use a managed database (RDS, Cloud SQL, etc.) or existing PostgreSQL server.
Update `k8s/configmap.yaml` with connection details.
### Option 2: In-Cluster PostgreSQL
```bash
helm repo add bitnami https://charts.bitnami.com/bitnami
helm install postgres bitnami/postgresql \
--namespace turbovault \
--set auth.database=turbovault_production \
--set auth.username=turbovault \
--set auth.password=changeme
# Update k8s/configmap.yaml:
# DATABASE_HOST: postgres-postgresql
```
## Complete Documentation
- [Full Deployment Guide](DEPLOYMENT.md) - Detailed deployment instructions
- [Development Guide](DEVELOPMENT_GUIDE.md) - Local development setup
- [API Documentation](API_DOCUMENTATION.md) - RESTful API reference
- [IGDB Integration](IGDB_INTEGRATION.md) - Game metadata matching
## Support
Need help?
- 📖 Check the [docs/](.) folder
- 🐛 [Open an issue](https://github.com/yourusername/turbovault/issues)
- 💬 [Discussions](https://github.com/yourusername/turbovault/discussions)
---
**Congratulations!** You've successfully deployed TurboVault to Kubernetes! 🎉
For production deployment to Kubernetes, see [Deployment Guide](DEPLOYMENT.md).