270 lines
4.9 KiB
Markdown
270 lines
4.9 KiB
Markdown
# 🚀 Deployment Guide
|
|
|
|
Quick reference for deploying your Lumina application to production.
|
|
|
|
## Table of Contents
|
|
|
|
- [Quick Start](#quick-start)
|
|
- [Docker](#docker)
|
|
- [Kubernetes](#kubernetes)
|
|
- [CI/CD](#cicd)
|
|
- [Troubleshooting](#troubleshooting)
|
|
|
|
## Quick Start
|
|
|
|
The fastest way to deploy using Make commands:
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# Using Makefile
|
|
make docker-build
|
|
|
|
# Or directly
|
|
docker build -t lumina-app:latest .
|
|
```
|
|
|
|
### Test Locally
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
1. **Push to main** → Triggers build
|
|
2. **Build succeeds** → Push to Harbor
|
|
3. **Harbor webhook** → Update K8s deployment
|
|
|
|
### Environment Variables
|
|
|
|
Required secrets in Gitea/CI:
|
|
|
|
- `HARBOR_USERNAME`: Harbor registry username
|
|
- `HARBOR_PASSWORD`: Harbor registry password
|
|
- `KUBECONFIG`: Base64-encoded kubeconfig
|
|
|
|
### Manual Workflow
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
- 📚 [Documentation](https://github.com/advisori/lumina)
|
|
- 💬 [Support](mailto:info@advisori.de)
|
|
- 🐛 [Report Issues](https://github.com/advisori/lumina/issues)
|
|
|
|
---
|
|
|
|
**Generated by Lumina** - AI-Powered Development Platform
|