Initial commit

docs/DEPLOY_CHECKLIST.md

@@ -0,0 +1,151 @@
+# 🚀 Kubernetes Deployment Checklist
+
+## ✅ Pre-Deployment Checklist
+
+Before deploying, ensure:
+
+1. **k3s is running:**
+   ```bash
+   sudo systemctl status k3s
+   # If not running:
+   sudo systemctl start k3s
+   ```
+
+2. **Docker images are built and imported:**
+   ```bash
+   # Build images
+   docker build -t fastapi-backend:latest --target api -f Dockerfile .
+   docker build -t nats-worker:latest --target worker -f Dockerfile .
+   
+   # Import to containerd (k3s uses containerd, not Docker)
+   docker save fastapi-backend:latest | sudo k3s ctr images import -
+   docker save nats-worker:latest | sudo k3s ctr images import -
+   ```
+
+3. **NATS JetStream stream is created:**
+   ```bash
+   # Run the setup script
+   ./setup-jetstream.sh
+   # Or manually:
+   python3 scripts/setup_jetstream.py
+   ```
+
+4. **kubectl is configured:**
+   ```bash
+   # On your local machine, ensure kubectl points to k3s
+   kubectl get nodes
+   ```
+
+## 🚀 Deployment Steps
+
+### Option 1: Simple Deployment (Recommended)
+```bash
+cd kubernetes
+chmod +x simple-deploy.sh
+./simple-deploy.sh
+```
+
+### Option 2: Manual Deployment
+```bash
+cd kubernetes/manifests
+
+# 1. Create namespace
+kubectl apply -f namespace.yaml
+
+# 2. Create secrets
+kubectl apply -f secrets.yaml
+
+# 3. Deploy FastAPI
+kubectl apply -f fastapi-deployment.yaml
+kubectl apply -f fastapi-service.yaml
+kubectl apply -f fastapi-hpa.yaml
+
+# 4. Deploy Workers
+kubectl apply -f worker-deployment.yaml
+kubectl apply -f worker-hpa.yaml
+
+# 5. Deploy Gateway (optional)
+kubectl apply -f gateway.yaml
+```
+
+## 🔍 Verify Deployment
+
+```bash
+# Check pods
+kubectl get pods -n nats-backend
+
+# Check services
+kubectl get svc -n nats-backend
+
+# Check Gateway
+kubectl get gateway -n nats-backend
+
+# Watch pods in real-time
+kubectl get pods -n nats-backend -w
+
+# Check logs
+kubectl logs -f deployment/fastapi-backend -n nats-backend
+kubectl logs -f deployment/nats-worker -n nats-backend
+```
+
+## 🌐 Access Your Application
+
+**Gateway Ports:**
+- HTTP: Port `8201`
+- HTTPS: Port `8441`
+
+**Note:** The Gateway uses non-standard ports (8201/8441) to avoid conflicts with Traefik on port 80/443.
+
+**To access via Gateway:**
+```bash
+# Port forward to test locally
+kubectl port-forward -n nats-backend svc/fastapi-backend 8000:8000
+
+# Then test:
+curl http://localhost:8000/health
+```
+
+## ⚠️ Troubleshooting
+
+### Pods not starting?
+```bash
+# Check pod status
+kubectl describe pod <pod-name> -n nats-backend
+
+# Check events
+kubectl get events -n nats-backend --sort-by='.lastTimestamp'
+```
+
+### ImagePullBackOff error?
+- Ensure images are imported to containerd (see step 2 above)
+- Check `imagePullPolicy: Never` in deployments
+
+### Worker pods crashing?
+- Ensure JetStream stream is created (see step 3 above)
+- Check NATS connection: `kubectl logs deployment/nats-worker -n nats-backend`
+
+### Gateway not working?
+- Gateway requires cert-manager for TLS (optional)
+- HTTP should work without cert-manager
+- Check Gateway status: `kubectl describe gateway api-gateway -n nats-backend`
+
+## 📊 Monitoring
+
+```bash
+# Check HPA status
+kubectl get hpa -n nats-backend
+
+# Check resource usage
+kubectl top pods -n nats-backend
+```
+
+## 🛑 Undeploy
+
+```bash
+# Delete all resources
+kubectl delete namespace nats-backend
+
+# Or delete individually
+kubectl delete -f manifests/
+```
+