4.9 KiB
4.9 KiB
🚀 Deployment Guide
Quick reference for deploying your Lumina application to production.
Table of Contents
Quick Start
The fastest way to deploy using Make commands:
# Build and push Docker image
make docker-all
# Deploy to Kubernetes (fresh install)
make deploy-fresh
# Or upgrade existing deployment
make deploy
Docker
Build Image
# Using Makefile
make docker-build
# Or directly
docker build -t lumina-app:latest .
Test Locally
# Using docker-compose (recommended)
make compose-up
# Or run container directly
docker run -p 3000:3000 --env-file .env.local lumina-app:latest
Push to Harbor
# Login to Harbor
make docker-login
# Build and push
make docker-all
Kubernetes
Prerequisites
- Kubernetes cluster (1.25+)
- kubectl configured
- Helm 3.x installed
- Harbor registry access
Deploy Application
# Full fresh deployment with secrets
make deploy-fresh
# Or step by step:
# 1. Create namespace
make k8s-namespace
# 2. Create registry secret
make k8s-secret-registry
# 3. Create app secrets (from .env.local)
make k8s-secret-app
# 4. Install with Helm
make helm-install
Monitor Deployment
# View pods
make k8s-pods
# View logs
make k8s-logs
# Port forward to localhost
make k8s-port-forward
# Check Helm status
make helm-status
Update Deployment
# Build new image and upgrade
IMAGE_TAG=v1.1.0 make deploy
# Or just upgrade Helm release
make helm-upgrade
Customize Configuration
Edit helm/lumina-app/values.yaml to configure:
- Replicas: Number of pods
- Resources: CPU/Memory limits
- Autoscaling: Min/Max replicas
- Ingress: Domain settings
- Environment: Custom variables
- Persistence: Enable storage
Rollback
# Uninstall deployment
make helm-uninstall
# Or rollback to previous version
helm rollback $(helm list -n lumina-apps -q) -n lumina-apps
CI/CD
Gitea Integration
The template supports automated deployments via Gitea Actions:
- Push to main → Triggers build
- Build succeeds → Push to Harbor
- Harbor webhook → Update K8s deployment
Environment Variables
Required secrets in Gitea/CI:
HARBOR_USERNAME: Harbor registry usernameHARBOR_PASSWORD: Harbor registry passwordKUBECONFIG: Base64-encoded kubeconfig
Manual Workflow
# 1. Develop locally
pnpm dev
# 2. Test with Docker Compose
make compose-up
# 3. Build and push image
make docker-all
# 4. Deploy to staging
NAMESPACE=staging make helm-install
# 5. Deploy to production
NAMESPACE=production make helm-install
Troubleshooting
Pods not starting
# Check pod status
kubectl get pods -n lumina-apps
# Describe pod for events
kubectl describe pod <pod-name> -n lumina-apps
# Check logs
kubectl logs <pod-name> -n lumina-apps
Image pull errors
# Verify registry secret exists
kubectl get secret harbor-registry-secret -n lumina-apps
# Test registry access
docker login harbor.advisori.de
# Recreate secret
make k8s-secret-registry
Application errors
# Check application logs
make k8s-logs
# Check environment variables
kubectl exec -it <pod-name> -n lumina-apps -- env
# Verify secrets
kubectl get secret lumina-app-secrets -n lumina-apps -o yaml
Health check failures
# Test health endpoint
kubectl port-forward svc/app 3000:80 -n lumina-apps
curl http://localhost:3000/api/health
# Check probe configuration
kubectl describe pod <pod-name> -n lumina-apps | grep -A 10 "Liveness\|Readiness"
Ingress issues
# Check ingress configuration
kubectl get ingress -n lumina-apps
kubectl describe ingress -n lumina-apps
# Verify cert-manager certificates
kubectl get certificates -n lumina-apps
kubectl describe certificate lumina-app-tls -n lumina-apps
Useful Commands
# Show all available commands
make help
# View Helm values
helm get values $(helm list -n lumina-apps -q) -n lumina-apps
# Update single value
helm upgrade <release> ./helm/lumina-app \
--namespace lumina-apps \
--set image.tag=v1.2.0 \
--reuse-values
# Scale manually
kubectl scale deployment <release>-lumina-app --replicas=5 -n lumina-apps
# View HPA status
kubectl get hpa -n lumina-apps
kubectl describe hpa <release>-lumina-app -n lumina-apps
Support
Generated by Lumina - AI-Powered Development Platform