turbovault-app/docs/QUICK_START.md

🚀 TurboVault Quick Start Guide

Get TurboVault deployed to Kubernetes in minutes!

Prerequisites

• GitHub account
• Kubernetes cluster (k3s, minikube, EKS, GKE, etc.)
• kubectl configured
• PostgreSQL database (or use in-cluster Helm chart)

Step 1: Push to GitHub

cd turbovault-web

# Initialize git
git init
git add .
git commit -m "Initial commit: TurboVault"

# Add your GitHub remote
git remote add origin https://github.com/YOUR_USERNAME/turbovault.git
git push -u origin main

Step 2: Tag a Release

git tag v1.0.0
git push origin v1.0.0

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

Check progress: GitHub → Actions tab

Step 3: Prepare Kubernetes Secrets

# Copy the template
cp k8s/secrets.yaml.example k8s/secrets.yaml

# Generate Rails secret
rails secret
# Copy output

# 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:

# 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:

DATABASE_HOST: "your-postgres-host"  # e.g., postgres-service or external host
DATABASE_NAME: "turbovault_production"
DATABASE_USERNAME: "turbovault"

Edit k8s/ingress.yaml (optional):

# 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

./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

# 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

# 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)

kubectl port-forward svc/turbovault-service 3000:80 -n turbovault

Visit: http://localhost:3000

Option C: LoadBalancer (cloud)

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:

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:

imagePullSecrets:
- name: ghcr-secret

Add SSL/TLS

Install cert-manager and configure Let's Encrypt:

See DEPLOYMENT.md for full instructions.

Update the App

When you want to deploy a new version:

# 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

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

# 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

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 - Detailed deployment instructions
• Development Guide - Local development setup
• API Documentation - RESTful API reference
• IGDB Integration - Game metadata matching

Support

Need help?

• 📖 Check the docs/ folder
• 🐛 Open an issue
• 💬 Discussions

---

Congratulations! You've successfully deployed TurboVault to Kubernetes! 🎉