mirror of
https://github.com/ryankazokas/turbovault-app.git
synced 2026-04-16 22:12:53 +00:00
Moving to github
This commit is contained in:
305
docs/QUICK_START.md
Normal file
305
docs/QUICK_START.md
Normal file
@@ -0,0 +1,305 @@
|
||||
# 🚀 TurboVault Quick Start Guide
|
||||
|
||||
Get TurboVault deployed to Kubernetes in minutes!
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- GitHub account
|
||||
- Kubernetes cluster (k3s, minikube, EKS, GKE, etc.)
|
||||
- kubectl configured
|
||||
- PostgreSQL database (or use in-cluster Helm chart)
|
||||
|
||||
## Step 1: Push to GitHub
|
||||
|
||||
```bash
|
||||
cd turbovault-web
|
||||
|
||||
# Initialize git
|
||||
git init
|
||||
git add .
|
||||
git commit -m "Initial commit: TurboVault"
|
||||
|
||||
# Add your GitHub remote
|
||||
git remote add origin https://github.com/YOUR_USERNAME/turbovault.git
|
||||
git push -u origin main
|
||||
```
|
||||
|
||||
## Step 2: Tag a Release
|
||||
|
||||
```bash
|
||||
git tag v1.0.0
|
||||
git push origin v1.0.0
|
||||
```
|
||||
|
||||
**What happens:**
|
||||
- GitHub Actions automatically triggers
|
||||
- Builds Docker image
|
||||
- Pushes to GitHub Container Registry (ghcr.io)
|
||||
- Image: `ghcr.io/YOUR_USERNAME/turbovault:v1.0.0`
|
||||
|
||||
**Check progress:** GitHub → Actions tab
|
||||
|
||||
## Step 3: Prepare Kubernetes Secrets
|
||||
|
||||
```bash
|
||||
# Copy the template
|
||||
cp k8s/secrets.yaml.example k8s/secrets.yaml
|
||||
|
||||
# Generate Rails secret
|
||||
rails secret
|
||||
# Copy output
|
||||
|
||||
# Edit secrets.yaml
|
||||
nano k8s/secrets.yaml
|
||||
```
|
||||
|
||||
Add your values:
|
||||
- `SECRET_KEY_BASE` - from `rails secret` command
|
||||
- `DATABASE_PASSWORD` - your PostgreSQL password
|
||||
- `IGDB_CLIENT_ID` (optional) - from https://dev.twitch.tv
|
||||
- `IGDB_CLIENT_SECRET` (optional) - from Twitch developer portal
|
||||
|
||||
**Important:** Do NOT commit `k8s/secrets.yaml` (it's gitignored)
|
||||
|
||||
## Step 4: Update Kubernetes Manifests
|
||||
|
||||
Edit `k8s/deployment.yaml` and `k8s/migrate-job.yaml`:
|
||||
|
||||
```yaml
|
||||
# Change this line:
|
||||
image: ghcr.io/username/turbovault:latest
|
||||
|
||||
# To your actual GitHub username:
|
||||
image: ghcr.io/YOUR_USERNAME/turbovault:v1.0.0
|
||||
```
|
||||
|
||||
Edit `k8s/configmap.yaml`:
|
||||
|
||||
```yaml
|
||||
DATABASE_HOST: "your-postgres-host" # e.g., postgres-service or external host
|
||||
DATABASE_NAME: "turbovault_production"
|
||||
DATABASE_USERNAME: "turbovault"
|
||||
```
|
||||
|
||||
Edit `k8s/ingress.yaml` (optional):
|
||||
|
||||
```yaml
|
||||
# Change to your domain
|
||||
host: turbovault.yourdomain.com
|
||||
```
|
||||
|
||||
Or skip ingress and use port-forwarding for testing.
|
||||
|
||||
## Step 5: Deploy to Kubernetes
|
||||
|
||||
### Option A: Automated Script
|
||||
|
||||
```bash
|
||||
./scripts/deploy-k8s.sh
|
||||
```
|
||||
|
||||
Follow the prompts:
|
||||
- Enter registry: `ghcr.io/YOUR_USERNAME`
|
||||
- Is it private? `n` (if image is public) or `y` (if private)
|
||||
- Deployment starts!
|
||||
|
||||
### Option B: Manual
|
||||
|
||||
```bash
|
||||
# Apply manifests
|
||||
kubectl apply -f k8s/namespace.yaml
|
||||
kubectl apply -f k8s/configmap.yaml
|
||||
kubectl apply -f k8s/secrets.yaml
|
||||
|
||||
# Run database migration
|
||||
kubectl apply -f k8s/migrate-job.yaml
|
||||
kubectl wait --for=condition=complete --timeout=300s job/turbovault-migrate -n turbovault
|
||||
|
||||
# Deploy application
|
||||
kubectl apply -f k8s/deployment.yaml
|
||||
kubectl apply -f k8s/service.yaml
|
||||
kubectl apply -f k8s/ingress.yaml # optional
|
||||
```
|
||||
|
||||
## Step 6: Verify Deployment
|
||||
|
||||
```bash
|
||||
# Check pods
|
||||
kubectl get pods -n turbovault
|
||||
|
||||
# Should show:
|
||||
# NAME READY STATUS RESTARTS AGE
|
||||
# turbovault-xxxxxxxxxx-xxxxx 1/1 Running 0 30s
|
||||
# turbovault-xxxxxxxxxx-xxxxx 1/1 Running 0 30s
|
||||
|
||||
# Check logs
|
||||
kubectl logs -f deployment/turbovault -n turbovault
|
||||
```
|
||||
|
||||
## Step 7: Access the Application
|
||||
|
||||
### Option A: Via Ingress (if configured)
|
||||
|
||||
Visit: `https://turbovault.yourdomain.com`
|
||||
|
||||
### Option B: Port Forward (for testing)
|
||||
|
||||
```bash
|
||||
kubectl port-forward svc/turbovault-service 3000:80 -n turbovault
|
||||
```
|
||||
|
||||
Visit: `http://localhost:3000`
|
||||
|
||||
### Option C: LoadBalancer (cloud)
|
||||
|
||||
```bash
|
||||
kubectl get svc turbovault-service -n turbovault
|
||||
|
||||
# Get EXTERNAL-IP and visit that IP
|
||||
```
|
||||
|
||||
## Step 8: Create Admin Account
|
||||
|
||||
1. Visit the application
|
||||
2. Click **Sign Up**
|
||||
3. Create your account
|
||||
4. Start adding games!
|
||||
|
||||
## 🎉 You're Done!
|
||||
|
||||
TurboVault is now running on Kubernetes!
|
||||
|
||||
## Next Steps
|
||||
|
||||
### Make it Public
|
||||
|
||||
Want others to access your package?
|
||||
|
||||
1. Go to GitHub → Your Profile → Packages
|
||||
2. Find `turbovault` package
|
||||
3. Package Settings → Change Visibility → Public
|
||||
|
||||
### Keep it Private
|
||||
|
||||
By default, GitHub Container Registry packages are private. Only you can pull the image. Perfect for personal deployments!
|
||||
|
||||
For Kubernetes to pull private images:
|
||||
|
||||
```bash
|
||||
kubectl create secret docker-registry ghcr-secret \
|
||||
--docker-server=ghcr.io \
|
||||
--docker-username=YOUR_USERNAME \
|
||||
--docker-password=YOUR_GITHUB_TOKEN \
|
||||
--namespace=turbovault
|
||||
```
|
||||
|
||||
Then uncomment in `k8s/deployment.yaml`:
|
||||
```yaml
|
||||
imagePullSecrets:
|
||||
- name: ghcr-secret
|
||||
```
|
||||
|
||||
### Add SSL/TLS
|
||||
|
||||
Install cert-manager and configure Let's Encrypt:
|
||||
|
||||
See [DEPLOYMENT.md](DEPLOYMENT.md) for full instructions.
|
||||
|
||||
### Update the App
|
||||
|
||||
When you want to deploy a new version:
|
||||
|
||||
```bash
|
||||
# Make changes
|
||||
git add .
|
||||
git commit -m "Add new feature"
|
||||
git push origin main
|
||||
|
||||
# Create new tag
|
||||
git tag v1.1.0
|
||||
git push origin v1.1.0
|
||||
|
||||
# Wait for GitHub Actions to build
|
||||
|
||||
# Update deployment
|
||||
kubectl set image deployment/turbovault \
|
||||
turbovault=ghcr.io/YOUR_USERNAME/turbovault:v1.1.0 \
|
||||
-n turbovault
|
||||
|
||||
# Watch rollout
|
||||
kubectl rollout status deployment/turbovault -n turbovault
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Pods not starting
|
||||
|
||||
```bash
|
||||
kubectl describe pod -l app=turbovault -n turbovault
|
||||
```
|
||||
|
||||
Common issues:
|
||||
- Image pull error → Check image path in deployment.yaml
|
||||
- Database connection → Check secrets.yaml and configmap.yaml
|
||||
- Crash loop → Check logs: `kubectl logs -l app=turbovault -n turbovault`
|
||||
|
||||
### Can't access application
|
||||
|
||||
```bash
|
||||
# Check service
|
||||
kubectl get svc -n turbovault
|
||||
|
||||
# Check ingress (if using)
|
||||
kubectl get ingress -n turbovault
|
||||
|
||||
# Try port-forward to test
|
||||
kubectl port-forward svc/turbovault-service 3000:80 -n turbovault
|
||||
```
|
||||
|
||||
### Build failed
|
||||
|
||||
Go to GitHub → Actions → Click on failed workflow
|
||||
|
||||
Common issues:
|
||||
- Dockerfile error → Fix and push again
|
||||
- Permission denied → Check workflow has `packages: write` permission
|
||||
|
||||
## Database Setup
|
||||
|
||||
### Option 1: External PostgreSQL (Recommended)
|
||||
|
||||
Use a managed database (RDS, Cloud SQL, etc.) or existing PostgreSQL server.
|
||||
|
||||
Update `k8s/configmap.yaml` with connection details.
|
||||
|
||||
### Option 2: In-Cluster PostgreSQL
|
||||
|
||||
```bash
|
||||
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
|
||||
|
||||
# Update k8s/configmap.yaml:
|
||||
# DATABASE_HOST: postgres-postgresql
|
||||
```
|
||||
|
||||
## Complete Documentation
|
||||
|
||||
- [Full Deployment Guide](DEPLOYMENT.md) - Detailed deployment instructions
|
||||
- [Development Guide](DEVELOPMENT_GUIDE.md) - Local development setup
|
||||
- [API Documentation](API_DOCUMENTATION.md) - RESTful API reference
|
||||
- [IGDB Integration](IGDB_INTEGRATION.md) - Game metadata matching
|
||||
|
||||
## Support
|
||||
|
||||
Need help?
|
||||
- 📖 Check the [docs/](.) folder
|
||||
- 🐛 [Open an issue](https://github.com/yourusername/turbovault/issues)
|
||||
- 💬 [Discussions](https://github.com/yourusername/turbovault/discussions)
|
||||
|
||||
---
|
||||
|
||||
**Congratulations!** You've successfully deployed TurboVault to Kubernetes! 🎉
|
||||
Reference in New Issue
Block a user