# 🚀 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