lumina-nextjs-template/DEPLOYMENT.md

🚀 Deployment Guide

Quick reference for deploying your Lumina application to production.

Table of Contents

• Quick Start
• Docker
• Kubernetes
• CI/CD
• Troubleshooting

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:

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

# 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

• 📚 Documentation
• 💬 Support
• 🐛 Report Issues

---

Generated by Lumina - AI-Powered Development Platform