# TurboVault Deployment Checklist

Complete checklist for deploying TurboVault from scratch.

## Phase 1: GitHub Setup ⬜

- [ ] **Read:** [.github/WHAT_TO_COMMIT.md](../.github/WHAT_TO_COMMIT.md)
- [ ] Create GitHub repository (public)
- [ ] Run `./scripts/setup-github.sh` OR manually push code
- [ ] Verify code is on GitHub
- [ ] **Read:** [.github/SECRETS_SETUP.md](../.github/SECRETS_SETUP.md)

## Phase 2: Gitea Access Token ⬜

- [ ] Login to your Gitea instance
- [ ] Go to Settings → Applications → Access Tokens
- [ ] Generate new token named `github-actions`
- [ ] Enable permissions: `package:read` + `package:write`
- [ ] Copy the token (starts with `gtea_`)
- [ ] Save it somewhere safe (you'll need it for GitHub Secrets)

## Phase 3: GitHub Secrets ⬜

Add these 4 secrets in GitHub → Settings → Secrets → Actions:

- [ ] `GITEA_REGISTRY` = Your Gitea URL (e.g., `gitea.example.com`)
- [ ] `GITEA_USERNAME` = Your Gitea username
- [ ] `GITEA_TOKEN` = The token you just created
- [ ] `GITEA_REPO` = Repository path (e.g., `username/turbovault`)

**Verify:** All 4 secrets show up in GitHub secrets list

## Phase 4: Test GitHub Actions ⬜

- [ ] Go to GitHub → Actions tab
- [ ] Click "Build and Push to Gitea" workflow
- [ ] Click "Run workflow"
- [ ] Enter tag: `test`
- [ ] Click "Run workflow"
- [ ] Watch the build (should take 2-5 minutes)
- [ ] Verify: Build succeeds with ✅
- [ ] Go to Gitea → Your Repo → Packages tab
- [ ] Verify: `turbovault:test` image exists

**If build fails:** Check [GITHUB_ACTIONS_SETUP.md](GITHUB_ACTIONS_SETUP.md) troubleshooting

## Phase 5: Kubernetes Secrets ⬜

- [ ] **Read:** [k8s/GITEA_SETUP.md](../k8s/GITEA_SETUP.md)
- [ ] Copy `k8s/secrets.yaml.example` to `k8s/secrets.yaml`
- [ ] Generate Rails secret: `rails secret`
- [ ] Edit `k8s/secrets.yaml` with your values:
  - [ ] `DATABASE_PASSWORD` - Your PostgreSQL password
  - [ ] `SECRET_KEY_BASE` - From `rails secret` command
  - [ ] `IGDB_CLIENT_ID` - Your IGDB client ID (optional)
  - [ ] `IGDB_CLIENT_SECRET` - Your IGDB secret (optional)
- [ ] **DO NOT commit k8s/secrets.yaml** (it's gitignored ✅)

## Phase 6: Update Kubernetes Manifests ⬜

- [ ] Edit `k8s/deployment.yaml`:
  - [ ] Change `YOUR_REGISTRY/turbovault:latest` to your Gitea path
  - [ ] Example: `gitea.example.com/username/turbovault:latest`

- [ ] Edit `k8s/migrate-job.yaml`:
  - [ ] Change `YOUR_REGISTRY/turbovault:latest` to your Gitea path

- [ ] Edit `k8s/configmap.yaml`:
  - [ ] Set `DATABASE_HOST` (your PostgreSQL hostname)
  - [ ] Set `DATABASE_NAME` (e.g., `turbovault_production`)
  - [ ] Set `DATABASE_USERNAME` (e.g., `turbovault`)

- [ ] Edit `k8s/ingress.yaml`:
  - [ ] Change `turbovault.example.com` to your domain
  - [ ] Or comment out ingress and use port-forward for testing

## Phase 7: Database Setup ⬜

**Option A: External PostgreSQL** (Recommended)
- [ ] Create database: `CREATE DATABASE turbovault_production;`
- [ ] Create user: `CREATE USER turbovault WITH PASSWORD 'secure_password';`
- [ ] Grant privileges: `GRANT ALL PRIVILEGES ON DATABASE turbovault_production TO turbovault;`

**Option B: In-cluster PostgreSQL**
- [ ] Follow [k8s/README.md](../k8s/README.md) Helm instructions

## Phase 8: Kubernetes Registry Secret ⬜

- [ ] Run this command (replace with your values):
  ```bash
  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
  ```

- [ ] Verify: `kubectl get secret gitea-registry -n turbovault`

**Or:** Use the deploy script which will prompt you to create it

## Phase 9: Deploy to Kubernetes ⬜

**Option A: Automated Script**
- [ ] Run `./scripts/deploy-k8s.sh`
- [ ] Enter your Gitea registry URL when prompted
- [ ] Confirm deployment
- [ ] Watch the deployment progress

**Option B: Manual**
- [ ] `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` (optional)

## Phase 10: Verify Deployment ⬜

- [ ] Check pods: `kubectl get pods -n turbovault`
- [ ] Verify 2 pods are Running
- [ ] Check logs: `kubectl logs -f deployment/turbovault -n turbovault`
- [ ] No errors in logs
- [ ] Check service: `kubectl get svc -n turbovault`
- [ ] Check ingress: `kubectl get ingress -n turbovault`

## Phase 11: Access Application ⬜

**Option A: Via Ingress** (if configured)
- [ ] Visit your domain: `https://turbovault.example.com`
- [ ] Verify site loads

**Option B: Via Port Forward** (for testing)
- [ ] Run: `kubectl port-forward svc/turbovault-service 3000:80 -n turbovault`
- [ ] Visit: `http://localhost:3000`
- [ ] Verify site loads

## Phase 12: Initial Setup ⬜

- [ ] Create admin user account
- [ ] Login and test basic functionality
- [ ] Add a test game
- [ ] Create a test collection
- [ ] Enable IGDB sync in settings (if configured)
- [ ] Test API with a token (optional)

## Phase 13: Optional - SSL/TLS ⬜

- [ ] Install cert-manager (see [DEPLOYMENT.md](DEPLOYMENT.md))
- [ ] Create ClusterIssuer for Let's Encrypt
- [ ] Update ingress with TLS config
- [ ] Verify HTTPS works

## Phase 14: Optional - Monitoring ⬜

- [ ] Set up log aggregation
- [ ] Configure health check alerts
- [ ] Set up backup cron job
- [ ] Document backup/restore procedure

## Quick Reference Commands

### Check Deployment Status
```bash
kubectl get all -n turbovault
kubectl describe deployment turbovault -n turbovault
kubectl logs -f deployment/turbovault -n turbovault
```

### Access Application
```bash
# Port forward
kubectl port-forward svc/turbovault-service 3000:80 -n turbovault

# Get ingress URL
kubectl get ingress -n turbovault
```

### Update Image
```bash
# After pushing new tag to GitHub
kubectl set image deployment/turbovault \
  turbovault=gitea.example.com/username/turbovault:v1.1.0 \
  -n turbovault
```

### Restart Deployment
```bash
kubectl rollout restart deployment/turbovault -n turbovault
```

### View Recent Logs
```bash
kubectl logs --tail=100 -l app=turbovault -n turbovault
```

### Database Console
```bash
kubectl exec -it deployment/turbovault -n turbovault -- rails console
```

## Troubleshooting

| Issue | Command | Documentation |
|-------|---------|---------------|
| Pods not starting | `kubectl describe pod -l app=turbovault -n turbovault` | [k8s/README.md](../k8s/README.md) |
| ImagePullBackOff | Check registry secret | [k8s/GITEA_SETUP.md](../k8s/GITEA_SETUP.md) |
| Database connection | Check secrets & configmap | [DEPLOYMENT.md](DEPLOYMENT.md) |
| Build fails | Check GitHub Actions logs | [GITHUB_ACTIONS_SETUP.md](GITHUB_ACTIONS_SETUP.md) |

## Success Criteria ✅

Your deployment is successful when:

- ✅ GitHub Actions builds succeed
- ✅ Images appear in Gitea packages
- ✅ k8s pods are Running (2/2)
- ✅ Application accessible via browser
- ✅ Can login and use features
- ✅ Database persists data
- ✅ IGDB sync works (if enabled)

## Documentation Index

| Document | Purpose |
|----------|---------|
| [README.md](../README.md) | Project overview & quick start |
| [GITHUB_ACTIONS_SETUP.md](GITHUB_ACTIONS_SETUP.md) | GitHub CI/CD setup |
| [.github/SECRETS_SETUP.md](../.github/SECRETS_SETUP.md) | Configure GitHub Secrets |
| [.github/WHAT_TO_COMMIT.md](../.github/WHAT_TO_COMMIT.md) | What's safe for open source |
| [k8s/GITEA_SETUP.md](../k8s/GITEA_SETUP.md) | Gitea registry integration |
| [k8s/README.md](../k8s/README.md) | Kubernetes deployment guide |
| [DEPLOYMENT.md](DEPLOYMENT.md) | Complete deployment guide |
| [API_DOCUMENTATION.md](API_DOCUMENTATION.md) | RESTful API reference |
| [IGDB_INTEGRATION.md](IGDB_INTEGRATION.md) | IGDB feature documentation |

---

**Start Here:** Phase 1 → Phase 12 for basic deployment  
**Need Help?** Check the relevant documentation link for detailed instructions  
**Ready to Deploy?** Check off each item as you complete it! 🚀