turbovault-app/k8s

TurboVault Kubernetes Deployment

This directory contains Kubernetes manifests for deploying TurboVault to your k3s cluster.

Prerequisites

• Kubernetes cluster (k3s, k8s, or any other)
• kubectl configured to access your cluster
• Docker registry (Docker Hub, GitHub Container Registry, or private registry)
• PostgreSQL database (external or in-cluster)

Quick Start

1. Build and Push Docker Image

Option A: Use GitHub Actions (Recommended)

Push a tag and GitHub Actions will build and push automatically:

git tag v1.0.0
git push origin v1.0.0

Image will be at: ghcr.io/your-username/turbovault:v1.0.0

Option B: Build Locally

# Build the image
docker build -t ghcr.io/your-username/turbovault:latest .

# Login to GitHub Container Registry
echo $GITHUB_TOKEN | docker login ghcr.io -u your-username --password-stdin

# Push to registry
docker push ghcr.io/your-username/turbovault:latest

1.5. Create Registry Secret (if using private registry)

For Public GitHub Container Registry: No secret needed!

For Private Registry:

kubectl create secret docker-registry registry-secret \
  --docker-server=your-registry.com \
  --docker-username=your-username \
  --docker-password=your-token \
  --docker-email=your-email@example.com \
  --namespace=turbovault

Then uncomment imagePullSecrets in deployment.yaml and migrate-job.yaml.

2. Configure Secrets

# Copy the example secrets file
cp k8s/secrets.yaml.example k8s/secrets.yaml

# Edit with your actual values
nano k8s/secrets.yaml

# Generate a SECRET_KEY_BASE
rails secret
# Copy the output to secrets.yaml

3. Update Configuration

Edit k8s/deployment.yaml and update:

• image: your-registry/turbovault:latest (line 28)
• Database configuration in k8s/configmap.yaml
• Domain in k8s/ingress.yaml

4. Deploy to Kubernetes

# Create namespace
kubectl apply -f k8s/namespace.yaml

# Create ConfigMap
kubectl apply -f k8s/configmap.yaml

# Create Secrets
kubectl apply -f k8s/secrets.yaml

# Run database migrations
kubectl apply -f k8s/migrate-job.yaml

# Wait for migration to complete
kubectl wait --for=condition=complete --timeout=300s job/turbovault-migrate -n turbovault

# Deploy application
kubectl apply -f k8s/deployment.yaml

# Create service
kubectl apply -f k8s/service.yaml

# Create ingress (for external access)
kubectl apply -f k8s/ingress.yaml

5. Verify Deployment

# Check pods
kubectl get pods -n turbovault

# Check logs
kubectl logs -f deployment/turbovault -n turbovault

# Check service
kubectl get svc -n turbovault

# Check ingress
kubectl get ingress -n turbovault

Database Setup

Option 1: External PostgreSQL

Update k8s/configmap.yaml with your external PostgreSQL details:

DATABASE_HOST: "your-postgres-host"
DATABASE_PORT: "5432"
DATABASE_NAME: "turbovault_production"
DATABASE_USERNAME: "turbovault"

And add the password to k8s/secrets.yaml:

DATABASE_PASSWORD: "your-secure-password"

Option 2: In-Cluster PostgreSQL

Deploy PostgreSQL in your cluster:

# Using Helm
helm repo add bitnami https://charts.bitnami.com/bitnami
helm install postgres bitnami/postgresql \
  --namespace turbovault \
  --set auth.database=turbovault_production \
  --set auth.username=turbovault \
  --set auth.password=changeme

Environment Variables

Required

• DATABASE_HOST - PostgreSQL host
• DATABASE_PASSWORD - PostgreSQL password
• SECRET_KEY_BASE - Rails secret key (generate with rails secret)

Optional

• IGDB_CLIENT_ID - IGDB API client ID (for game metadata)
• IGDB_CLIENT_SECRET - IGDB API client secret
• SMTP_ADDRESS - SMTP server for emails
• SMTP_PORT - SMTP port
• SMTP_USERNAME - SMTP username
• SMTP_PASSWORD - SMTP password

Scaling

Scale the deployment:

kubectl scale deployment turbovault --replicas=3 -n turbovault

Updating

Deploy New Version

# Option 1: Use GitHub Actions (Recommended)
git tag v2.0.0
git push origin v2.0.0
# Wait for build to complete in Actions tab

# Option 2: Build locally
docker build -t ghcr.io/username/turbovault:v2.0.0 .
docker push ghcr.io/username/turbovault:v2.0.0

# Update deployment image
kubectl set image deployment/turbovault turbovault=ghcr.io/username/turbovault:v2.0.0 -n turbovault

# Run migrations if needed
kubectl delete job turbovault-migrate -n turbovault
kubectl apply -f k8s/migrate-job.yaml
kubectl wait --for=condition=complete --timeout=300s job/turbovault-migrate -n turbovault

Troubleshooting

Pods Not Starting

# Check pod status
kubectl describe pod -l app=turbovault -n turbovault

# Check logs
kubectl logs -l app=turbovault -n turbovault

Database Connection Issues

# Test database connection
kubectl run -it --rm debug --image=postgres:15 --restart=Never -n turbovault -- \
  psql -h postgres-service -U turbovault -d turbovault_production

Migration Failures

# Check migration job logs
kubectl logs job/turbovault-migrate -n turbovault

# Re-run migrations
kubectl delete job turbovault-migrate -n turbovault
kubectl apply -f k8s/migrate-job.yaml

Monitoring

Check Application Health

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

# Visit http://localhost:3000/up in your browser

View Logs

# All pods
kubectl logs -f -l app=turbovault -n turbovault

# Specific pod
kubectl logs -f turbovault-xxxxx-xxxxx -n turbovault

# Previous logs (if pod crashed)
kubectl logs --previous turbovault-xxxxx-xxxxx -n turbovault

Backup

Database Backup

# Backup database
kubectl exec -it postgres-xxxxx -n turbovault -- \
  pg_dump -U turbovault turbovault_production > backup.sql

# Restore database
kubectl exec -i postgres-xxxxx -n turbovault -- \
  psql -U turbovault turbovault_production < backup.sql

Security

Best Practices

1. Use secrets management - Consider using Sealed Secrets or External Secrets Operator
2. Enable TLS - Uncomment TLS section in ingress.yaml
3. Network policies - Restrict pod-to-pod communication
4. Resource limits - Already configured in deployment.yaml
5. Regular updates - Keep dependencies and images up to date

Sealed Secrets (Recommended)

# Install Sealed Secrets controller
kubectl apply -f https://github.com/bitnami-labs/sealed-secrets/releases/download/v0.18.0/controller.yaml

# Create sealed secret
kubeseal --format yaml < k8s/secrets.yaml > k8s/sealed-secrets.yaml

# Apply sealed secret (safe to commit)
kubectl apply -f k8s/sealed-secrets.yaml

Clean Up

Remove TurboVault from cluster:

kubectl delete namespace turbovault

Support

For issues or questions:

• GitHub Issues: https://github.com/ryankazokas/turbovault-app/issues
• Documentation: https://github.com/ryankazokas/turbovault-app