Moving to github

2026-04-17 07:52:53 +00:00 · 2026-03-28 19:24:29 -04:00
commit 036fa7ab33
302 changed files with 17838 additions and 0 deletions
--- a/docs/DEPLOYMENT_CHECKLIST.md
+++ b/docs/DEPLOYMENT_CHECKLIST.md
@@ -0,0 +1,244 @@
+# 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! 🚀