turbovault-app/docs/DEPLOYMENT_CHECKLIST.md

TurboVault Deployment Checklist

Complete checklist for deploying TurboVault from scratch.

Phase 1: GitHub Setup ⬜

• Read: .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

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 troubleshooting

Phase 5: Kubernetes Secrets ⬜

• Read: 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 Helm instructions

Phase 8: Kubernetes Registry Secret ⬜

• Run this command (replace with your values):

  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)
• 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

kubectl get all -n turbovault
kubectl describe deployment turbovault -n turbovault
kubectl logs -f deployment/turbovault -n turbovault

Access Application

# Port forward
kubectl port-forward svc/turbovault-service 3000:80 -n turbovault

# Get ingress URL
kubectl get ingress -n turbovault

Update Image

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

Restart Deployment

kubectl rollout restart deployment/turbovault -n turbovault

View Recent Logs

kubectl logs --tail=100 -l app=turbovault -n turbovault

Database Console

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
ImagePullBackOff	Check registry secret	k8s/GITEA_SETUP.md
Database connection	Check secrets & configmap	DEPLOYMENT.md
Build fails	Check GitHub Actions logs	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	Project overview & quick start
GITHUB_ACTIONS_SETUP.md	GitHub CI/CD setup
.github/SECRETS_SETUP.md	Configure GitHub Secrets
.github/WHAT_TO_COMMIT.md	What's safe for open source
k8s/GITEA_SETUP.md	Gitea registry integration
k8s/README.md	Kubernetes deployment guide
DEPLOYMENT.md	Complete deployment guide
API_DOCUMENTATION.md	RESTful API reference
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! 🚀