mirror of
https://github.com/ryankazokas/turbovault-app.git
synced 2026-04-16 23:22:53 +00:00
245 lines
8.1 KiB
Markdown
245 lines
8.1 KiB
Markdown
# 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! 🚀
|