# TurboVault Deployment Guide

Complete guide for deploying TurboVault to production.

## Table of Contents

1. [GitHub Setup](#github-setup)
2. [Kubernetes Deployment](#kubernetes-deployment)
3. [Database Setup](#database-setup)
4. [DNS & SSL](#dns--ssl)
5. [Monitoring](#monitoring)

---

## GitHub Setup

### Push to GitHub

```bash
# Run the automated setup script
./scripts/setup-github.sh

# Or manually:
git init
git add .
git commit -m "Initial commit"
git branch -M main
git remote add origin https://github.com/YOUR_USERNAME/turbovault.git
git push -u origin main
```

### Set Up GitHub Actions (Optional)

Create `.github/workflows/ci.yml` for automated testing and building:

```yaml
name: CI

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    services:
      postgres:
        image: postgres:15
        env:
          POSTGRES_PASSWORD: postgres
        options: >-
          --health-cmd pg_isready
          --health-interval 10s
          --health-timeout 5s
          --health-retries 5
    steps:
      - uses: actions/checkout@v3
      - uses: ruby/setup-ruby@v1
        with:
          ruby-version: '3.3'
          bundler-cache: true
      - run: bundle exec rails db:test:prepare
      - run: bundle exec rails test
```

---

## Kubernetes Deployment

### Prerequisites

- k3s/k8s cluster running
- `kubectl` configured
- Docker installed
- PostgreSQL database (in-cluster or external)

### Quick Deploy

```bash
# Automated deployment
./scripts/deploy-k8s.sh
```

### Manual Deployment

```bash
# 1. Login to Gitea registry
docker login gitea.example.com

# 2. Build and push Docker image
docker build -t gitea.example.com/username/turbovault:latest .
docker push gitea.example.com/username/turbovault:latest

# 3. Create Gitea registry secret in k8s
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

# 2. Create secrets
cp k8s/secrets.yaml.example k8s/secrets.yaml
# Edit k8s/secrets.yaml with your values

# 3. Generate Rails secret
rails secret
# Copy output to k8s/secrets.yaml SECRET_KEY_BASE

# 4. Deploy to k8s
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
```

### Update Image Reference

Edit `k8s/deployment.yaml` and `k8s/migrate-job.yaml` with your Gitea registry path:

```yaml
# Add imagePullSecrets for Gitea authentication
imagePullSecrets:
- name: gitea-registry

# Update image path
image: gitea.example.com/username/turbovault:latest
```

**See [k8s/GITEA_SETUP.md](../k8s/GITEA_SETUP.md) for complete Gitea registry setup guide.**

---

## Database Setup

### Option 1: External PostgreSQL

Use an external PostgreSQL instance (recommended for production):

1. Create database and user:
   ```sql
   CREATE DATABASE turbovault_production;
   CREATE USER turbovault WITH PASSWORD 'your-secure-password';
   GRANT ALL PRIVILEGES ON DATABASE turbovault_production TO turbovault;
   ```

2. Update `k8s/configmap.yaml`:
   ```yaml
   DATABASE_HOST: "your-postgres-host.example.com"
   DATABASE_PORT: "5432"
   DATABASE_NAME: "turbovault_production"
   DATABASE_USERNAME: "turbovault"
   ```

3. Update `k8s/secrets.yaml`:
   ```yaml
   DATABASE_PASSWORD: "your-secure-password"
   ```

### Option 2: In-Cluster PostgreSQL

Deploy PostgreSQL in your cluster using Helm:

```bash
# Add Bitnami repo
helm repo add bitnami https://charts.bitnami.com/bitnami
helm repo update

# Install PostgreSQL
helm install postgres bitnami/postgresql \
  --namespace turbovault \
  --set auth.database=turbovault_production \
  --set auth.username=turbovault \
  --set auth.password=changeme \
  --set primary.persistence.size=10Gi

# Connection details
DATABASE_HOST: postgres-postgresql
DATABASE_PORT: 5432
```

---

## DNS & SSL

### Configure DNS

Point your domain to your cluster's ingress:

```bash
# Get ingress IP
kubectl get ingress -n turbovault

# Add A record
turbovault.example.com -> YOUR_INGRESS_IP
```

### Enable SSL with cert-manager

```bash
# Install cert-manager
kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.13.0/cert-manager.yaml

# Create ClusterIssuer
cat <<EOF | kubectl apply -f -
apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
  name: letsencrypt-prod
spec:
  acme:
    server: https://acme-v02.api.letsencrypt.org/directory
    email: your-email@example.com
    privateKeySecretRef:
      name: letsencrypt-prod
    solvers:
    - http01:
        ingress:
          class: nginx
EOF
```

Update `k8s/ingress.yaml`:

```yaml
metadata:
  annotations:
    cert-manager.io/cluster-issuer: "letsencrypt-prod"
spec:
  tls:
  - hosts:
    - turbovault.example.com
    secretName: turbovault-tls
```

---

## Monitoring

### Health Checks

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

# Check application health
kubectl port-forward svc/turbovault-service 3000:80 -n turbovault
# Visit http://localhost:3000/up
```

### 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 crashed)
kubectl logs --previous turbovault-xxxxx-xxxxx -n turbovault
```

### Common Issues

**Pods not starting:**
```bash
kubectl describe pod -l app=turbovault -n turbovault
```

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

**Migration failed:**
```bash
kubectl logs job/turbovault-migrate -n turbovault
```

---

## Scaling

### Horizontal Scaling

```bash
# Scale to 3 replicas
kubectl scale deployment turbovault --replicas=3 -n turbovault

# Auto-scaling (HPA)
kubectl autoscale deployment turbovault \
  --cpu-percent=70 \
  --min=2 \
  --max=10 \
  -n turbovault
```

### Vertical Scaling

Edit `k8s/deployment.yaml`:

```yaml
resources:
  requests:
    memory: "1Gi"
    cpu: "500m"
  limits:
    memory: "2Gi"
    cpu: "2000m"
```

---

## Backup & Restore

### Database Backup

```bash
# Automated backup (cronjob)
kubectl create cronjob pg-backup \
  --image=postgres:15 \
  --schedule="0 2 * * *" \
  --restart=Never \
  -n turbovault \
  -- /bin/sh -c "pg_dump -h postgres-postgresql -U turbovault turbovault_production | gzip > /backup/turbovault-$(date +%Y%m%d).sql.gz"
```

### Full Backup

```bash
# Backup all k8s resources
kubectl get all -n turbovault -o yaml > turbovault-backup.yaml

# Backup secrets (encrypted)
kubectl get secrets -n turbovault -o yaml > secrets-backup.yaml
```

---

## Security Best Practices

1. ✅ Use Kubernetes Secrets (or Sealed Secrets)
2. ✅ Enable HTTPS/TLS
3. ✅ Set resource limits
4. ✅ Use non-root container user
5. ✅ Enable Network Policies
6. ✅ Regular security updates
7. ✅ Database backups
8. ✅ Monitor logs

---

## Additional Resources

- [Kubernetes Documentation](https://kubernetes.io/docs/)
- [k3s Documentation](https://docs.k3s.io/)
- [Rails Deployment Guide](https://guides.rubyonrails.org/configuring.html)
- [TurboVault API Docs](API_DOCUMENTATION.md)

---

## Support

Need help? 
- 📖 [Full Documentation](../README.md)
- 🐛 [Report Issues](https://github.com/yourusername/turbovault/issues)
- 💬 [Discussions](https://github.com/yourusername/turbovault/discussions)