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

```bash
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

```bash
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

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

```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! 🎉