mirror of
https://github.com/ryankazokas/turbovault-app.git
synced 2026-04-16 22:12:53 +00:00
Condenses Documentation
This commit is contained in:
@@ -1,111 +1,68 @@
|
||||
# TurboVault Deployment Guide
|
||||
# Deployment Guide
|
||||
|
||||
Complete guide for deploying TurboVault to production.
|
||||
Deploy TurboVault to Kubernetes.
|
||||
|
||||
## Table of Contents
|
||||
## Prerequisites
|
||||
|
||||
1. [GitHub Setup](#github-setup)
|
||||
2. [Kubernetes Deployment](#kubernetes-deployment)
|
||||
3. [Database Setup](#database-setup)
|
||||
4. [DNS & SSL](#dns--ssl)
|
||||
5. [Monitoring](#monitoring)
|
||||
- Kubernetes cluster
|
||||
- kubectl configured
|
||||
- PostgreSQL database (already set up)
|
||||
|
||||
---
|
||||
|
||||
## GitHub Setup
|
||||
|
||||
### Push to GitHub
|
||||
## Quick Deploy
|
||||
|
||||
```bash
|
||||
# Run the automated setup script
|
||||
./scripts/setup-github.sh
|
||||
# 1. Build image (auto-builds via GitHub Actions)
|
||||
git tag v1.0.0
|
||||
git push origin v1.0.0
|
||||
|
||||
# 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
|
||||
```
|
||||
# 2. Configure secrets
|
||||
cp k8s/secrets.yaml.example k8s/secrets.yaml
|
||||
nano k8s/secrets.yaml
|
||||
|
||||
### 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
|
||||
# 3. Deploy
|
||||
./scripts/deploy-k8s.sh
|
||||
```
|
||||
|
||||
### Manual Deployment
|
||||
## Configuration
|
||||
|
||||
### 1. Update Image
|
||||
|
||||
Edit `k8s/deployment.yaml` and `k8s/migrate-job.yaml`:
|
||||
|
||||
```yaml
|
||||
image: ghcr.io/ryankazokas/turbovault-app:v1.0.0
|
||||
```
|
||||
|
||||
### 2. Database Connection
|
||||
|
||||
Edit `k8s/configmap.yaml`:
|
||||
|
||||
```yaml
|
||||
DATABASE_HOST: "your-postgres-host"
|
||||
DATABASE_NAME: "turbovault_production"
|
||||
DATABASE_USERNAME: "turbovault"
|
||||
```
|
||||
|
||||
### 3. Secrets
|
||||
|
||||
Edit `k8s/secrets.yaml`:
|
||||
|
||||
```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
|
||||
# Generate Rails secret
|
||||
rails secret
|
||||
# Copy output to k8s/secrets.yaml SECRET_KEY_BASE
|
||||
|
||||
# 4. Deploy to k8s
|
||||
# Add to secrets.yaml:
|
||||
SECRET_KEY_BASE: "output_from_rails_secret"
|
||||
DATABASE_PASSWORD: "your_postgres_password"
|
||||
|
||||
# Optional (for IGDB):
|
||||
IGDB_CLIENT_ID: "your_igdb_client_id"
|
||||
IGDB_CLIENT_SECRET: "your_igdb_client_secret"
|
||||
```
|
||||
|
||||
## Manual Deployment
|
||||
|
||||
```bash
|
||||
kubectl apply -f k8s/namespace.yaml
|
||||
kubectl apply -f k8s/configmap.yaml
|
||||
kubectl apply -f k8s/secrets.yaml
|
||||
@@ -116,117 +73,27 @@ 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 registry path:
|
||||
|
||||
```yaml
|
||||
# For public registries (GitHub Container Registry, Docker Hub public)
|
||||
# No imagePullSecrets needed!
|
||||
image: ghcr.io/your-username/turbovault:latest
|
||||
|
||||
# For private registries, add imagePullSecrets:
|
||||
imagePullSecrets:
|
||||
- name: registry-secret
|
||||
|
||||
image: your-registry.com/turbovault:latest
|
||||
```
|
||||
|
||||
**Default:** Use GitHub Container Registry (ghcr.io) - free and built-in.
|
||||
**See:** [k8s/README.md](../k8s/README.md) for registry setup details.
|
||||
|
||||
---
|
||||
|
||||
## 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:
|
||||
## Update Deployment
|
||||
|
||||
```bash
|
||||
# Add Bitnami repo
|
||||
helm repo add bitnami https://charts.bitnami.com/bitnami
|
||||
helm repo update
|
||||
# Build new version
|
||||
git tag v1.1.0
|
||||
git push origin v1.1.0
|
||||
|
||||
# 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
|
||||
# Update deployment
|
||||
kubectl set image deployment/turbovault \
|
||||
turbovault=ghcr.io/ryankazokas/turbovault-app:v1.1.0 \
|
||||
-n turbovault
|
||||
|
||||
# Connection details
|
||||
DATABASE_HOST: postgres-postgresql
|
||||
DATABASE_PORT: 5432
|
||||
# Watch rollout
|
||||
kubectl rollout status deployment/turbovault -n turbovault
|
||||
```
|
||||
|
||||
---
|
||||
## SSL/TLS
|
||||
|
||||
## DNS & SSL
|
||||
Update `k8s/ingress.yaml` with your domain and TLS configuration.
|
||||
|
||||
### 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`:
|
||||
For Let's Encrypt with cert-manager:
|
||||
|
||||
```yaml
|
||||
metadata:
|
||||
@@ -235,68 +102,17 @@ metadata:
|
||||
spec:
|
||||
tls:
|
||||
- hosts:
|
||||
- turbovault.example.com
|
||||
- turbovault.yourdomain.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
|
||||
# Scale replicas
|
||||
kubectl scale deployment turbovault --replicas=3 -n turbovault
|
||||
|
||||
# Auto-scaling (HPA)
|
||||
# Auto-scaling
|
||||
kubectl autoscale deployment turbovault \
|
||||
--cpu-percent=70 \
|
||||
--min=2 \
|
||||
@@ -304,73 +120,33 @@ kubectl autoscale deployment turbovault \
|
||||
-n turbovault
|
||||
```
|
||||
|
||||
### Vertical Scaling
|
||||
|
||||
Edit `k8s/deployment.yaml`:
|
||||
|
||||
```yaml
|
||||
resources:
|
||||
requests:
|
||||
memory: "1Gi"
|
||||
cpu: "500m"
|
||||
limits:
|
||||
memory: "2Gi"
|
||||
cpu: "2000m"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Backup & Restore
|
||||
|
||||
### Database Backup
|
||||
## Monitoring
|
||||
|
||||
```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"
|
||||
# Check status
|
||||
kubectl get pods -n turbovault
|
||||
|
||||
# View logs
|
||||
kubectl logs -f -l app=turbovault -n turbovault
|
||||
|
||||
# Check resources
|
||||
kubectl top pods -n turbovault
|
||||
```
|
||||
|
||||
### Full Backup
|
||||
## Troubleshooting
|
||||
|
||||
### View pod details
|
||||
```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
|
||||
kubectl describe pod -l app=turbovault -n turbovault
|
||||
```
|
||||
|
||||
---
|
||||
### Test database connection
|
||||
```bash
|
||||
kubectl exec -it deployment/turbovault -n turbovault -- \
|
||||
rails runner "puts ActiveRecord::Base.connection.execute('SELECT 1').first"
|
||||
```
|
||||
|
||||
## 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)
|
||||
### View environment
|
||||
```bash
|
||||
kubectl exec -it deployment/turbovault -n turbovault -- env | grep DATABASE
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user