turbovault-app/k8s/README.md

# TurboVault Kubernetes Deployment

This directory contains Kubernetes manifests for deploying TurboVault to your k3s cluster.

## Prerequisites

- Kubernetes cluster (k3s, k8s, or any other)
- `kubectl` configured to access your cluster
- Docker registry (Docker Hub, GitHub Container Registry, or private registry)
- PostgreSQL database (external or in-cluster)

## Quick Start

### 1. Build and Push Docker Image

**Option A: Use GitHub Actions (Recommended)**

Push a tag and GitHub Actions will build and push automatically:
```bash
git tag v1.0.0
git push origin v1.0.0
```

Image will be at: `ghcr.io/your-username/turbovault:v1.0.0`

**Option B: Build Locally**

```bash
# Build the image
docker build -t ghcr.io/your-username/turbovault:latest .

# Login to GitHub Container Registry
echo $GITHUB_TOKEN | docker login ghcr.io -u your-username --password-stdin

# Push to registry
docker push ghcr.io/your-username/turbovault:latest
```

### 1.5. Create Registry Secret (if using private registry)

**For Public GitHub Container Registry:** No secret needed!

**For Private Registry:**

```bash
kubectl create secret docker-registry registry-secret \
  --docker-server=your-registry.com \
  --docker-username=your-username \
  --docker-password=your-token \
  --docker-email=your-email@example.com \
  --namespace=turbovault
```

Then uncomment `imagePullSecrets` in `deployment.yaml` and `migrate-job.yaml`.

### 2. Configure Secrets

```bash
# Copy the example secrets file
cp k8s/secrets.yaml.example k8s/secrets.yaml

# Edit with your actual values
nano k8s/secrets.yaml

# Generate a SECRET_KEY_BASE
rails secret
# Copy the output to secrets.yaml
```

### 3. Update Configuration

Edit `k8s/deployment.yaml` and update:
- `image: your-registry/turbovault:latest` (line 28)
- Database configuration in `k8s/configmap.yaml`
- Domain in `k8s/ingress.yaml`

### 4. Deploy to Kubernetes

```bash
# Create namespace
kubectl apply -f k8s/namespace.yaml

# Create ConfigMap
kubectl apply -f k8s/configmap.yaml

# Create Secrets
kubectl apply -f k8s/secrets.yaml

# Run database migrations
kubectl apply -f k8s/migrate-job.yaml

# Wait for migration to complete
kubectl wait --for=condition=complete --timeout=300s job/turbovault-migrate -n turbovault

# Deploy application
kubectl apply -f k8s/deployment.yaml

# Create service
kubectl apply -f k8s/service.yaml

# Create ingress (for external access)
kubectl apply -f k8s/ingress.yaml
```

### 5. Verify Deployment

```bash
# Check pods
kubectl get pods -n turbovault

# Check logs
kubectl logs -f deployment/turbovault -n turbovault

# Check service
kubectl get svc -n turbovault

# Check ingress
kubectl get ingress -n turbovault
```

## Database Setup

### Option 1: External PostgreSQL

Update `k8s/configmap.yaml` with your external PostgreSQL details:

```yaml
DATABASE_HOST: "your-postgres-host"
DATABASE_PORT: "5432"
DATABASE_NAME: "turbovault_production"
DATABASE_USERNAME: "turbovault"
```

And add the password to `k8s/secrets.yaml`:

```yaml
DATABASE_PASSWORD: "your-secure-password"
```

### Option 2: In-Cluster PostgreSQL

Deploy PostgreSQL in your cluster:

```bash
# Using Helm
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
```

## Environment Variables

### Required

- `DATABASE_HOST` - PostgreSQL host
- `DATABASE_PASSWORD` - PostgreSQL password
- `SECRET_KEY_BASE` - Rails secret key (generate with `rails secret`)

### Optional

- `IGDB_CLIENT_ID` - IGDB API client ID (for game metadata)
- `IGDB_CLIENT_SECRET` - IGDB API client secret
- `SMTP_ADDRESS` - SMTP server for emails
- `SMTP_PORT` - SMTP port
- `SMTP_USERNAME` - SMTP username
- `SMTP_PASSWORD` - SMTP password

## Scaling

Scale the deployment:

```bash
kubectl scale deployment turbovault --replicas=3 -n turbovault
```

## Updating

### Deploy New Version

```bash
# Option 1: Use GitHub Actions (Recommended)
git tag v2.0.0
git push origin v2.0.0
# Wait for build to complete in Actions tab

# Option 2: Build locally
docker build -t ghcr.io/username/turbovault:v2.0.0 .
docker push ghcr.io/username/turbovault:v2.0.0

# Update deployment image
kubectl set image deployment/turbovault turbovault=ghcr.io/username/turbovault:v2.0.0 -n turbovault

# Run migrations if needed
kubectl delete job turbovault-migrate -n turbovault
kubectl apply -f k8s/migrate-job.yaml
kubectl wait --for=condition=complete --timeout=300s job/turbovault-migrate -n turbovault
```

## Troubleshooting

### Pods Not Starting

```bash
# Check pod status
kubectl describe pod -l app=turbovault -n turbovault

# Check logs
kubectl logs -l app=turbovault -n turbovault
```

### Database Connection Issues

```bash
# Test database connection
kubectl run -it --rm debug --image=postgres:15 --restart=Never -n turbovault -- \
  psql -h postgres-service -U turbovault -d turbovault_production
```

### Migration Failures

```bash
# Check migration job logs
kubectl logs job/turbovault-migrate -n turbovault

# Re-run migrations
kubectl delete job turbovault-migrate -n turbovault
kubectl apply -f k8s/migrate-job.yaml
```

## Monitoring

### Check Application Health

```bash
# Via kubectl
kubectl port-forward svc/turbovault-service 3000:80 -n turbovault

# Visit http://localhost:3000/up in your browser
```

### View Logs

```bash
# All pods
kubectl logs -f -l app=turbovault -n turbovault

# Specific pod
kubectl logs -f turbovault-xxxxx-xxxxx -n turbovault

# Previous logs (if pod crashed)
kubectl logs --previous turbovault-xxxxx-xxxxx -n turbovault
```

## Backup

### Database Backup

```bash
# Backup database
kubectl exec -it postgres-xxxxx -n turbovault -- \
  pg_dump -U turbovault turbovault_production > backup.sql

# Restore database
kubectl exec -i postgres-xxxxx -n turbovault -- \
  psql -U turbovault turbovault_production < backup.sql
```

## Security

### Best Practices

1. **Use secrets management** - Consider using Sealed Secrets or External Secrets Operator
2. **Enable TLS** - Uncomment TLS section in `ingress.yaml`
3. **Network policies** - Restrict pod-to-pod communication
4. **Resource limits** - Already configured in deployment.yaml
5. **Regular updates** - Keep dependencies and images up to date

### Sealed Secrets (Recommended)

```bash
# Install Sealed Secrets controller
kubectl apply -f https://github.com/bitnami-labs/sealed-secrets/releases/download/v0.18.0/controller.yaml

# Create sealed secret
kubeseal --format yaml < k8s/secrets.yaml > k8s/sealed-secrets.yaml

# Apply sealed secret (safe to commit)
kubectl apply -f k8s/sealed-secrets.yaml
```

## Clean Up

Remove TurboVault from cluster:

```bash
kubectl delete namespace turbovault
```

## Support

For issues or questions:
- GitHub Issues: https://github.com/ryankazokas/turbovault-app/issues
- Documentation: https://github.com/ryankazokas/turbovault-app