warehouse13/docs/HELM-DEPLOYMENT.md

# Warehouse13 - Kubernetes Deployment with Helm

This guide covers deploying Warehouse13 to Kubernetes using the official Helm chart.

## Table of Contents

1. [Prerequisites](#prerequisites)
2. [Quick Start](#quick-start)
3. [Deployment Scenarios](#deployment-scenarios)
4. [Configuration](#configuration)
5. [Post-Deployment](#post-deployment)
6. [Upgrading](#upgrading)
7. [Troubleshooting](#troubleshooting)

## Prerequisites

- Kubernetes 1.19+ cluster
- Helm 3.0+
- kubectl configured to access your cluster
- Persistent volume provisioner (for production deployments)

### Installing Helm

```bash
# macOS
brew install helm

# Linux
curl https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 | bash

# Windows
choco install kubernetes-helm
```

## Quick Start

### 1. Standard Deployment (Internet Access)

```bash
# Create namespace
kubectl create namespace warehouse13

# Install with default values
helm install warehouse13 ./helm/warehouse13 \
  --namespace warehouse13

# Wait for pods to be ready
kubectl wait --for=condition=ready pod \
  --all --namespace warehouse13 --timeout=300s
```

### 2. Access the Application

```bash
# Frontend
kubectl port-forward -n warehouse13 svc/warehouse13-frontend 4200:80

# API
kubectl port-forward -n warehouse13 svc/warehouse13-api 8000:8000

# MinIO Console
kubectl port-forward -n warehouse13 svc/warehouse13-minio 9001:9001
```

Then visit:
- Frontend: http://localhost:4200
- API Docs: http://localhost:8000/docs
- MinIO Console: http://localhost:9001

## Deployment Scenarios

### Development Environment

For local testing or CI/CD:

```bash
helm install warehouse13-dev ./helm/warehouse13 \
  --namespace warehouse13-dev \
  --create-namespace \
  --values ./helm/warehouse13/values-dev.yaml
```

**Features:**
- Single replica for all services
- emptyDir storage (no persistence)
- Minimal resource requests
- Always pull latest dev images

### Production Environment

For production with ingress and high availability:

```bash
# First, update the values file with your domain and secrets
cp ./helm/warehouse13/values-production.yaml ./my-production-values.yaml

# Edit the file:
# - Set postgres.auth.password
# - Set minio.auth.rootUser and rootPassword
# - Set ingress.hosts[0].host to your domain
# - Update storageClass for your environment

# Install
helm install warehouse13 ./helm/warehouse13 \
  --namespace warehouse13 \
  --create-namespace \
  --values ./my-production-values.yaml
```

**Features:**
- 3 replicas for API and frontend
- Persistent storage with PVCs
- Ingress with TLS support
- Resource limits and requests
- Health checks enabled
- Pod anti-affinity for distribution

### Air-Gapped Environment

For restricted/disconnected environments:

```bash
# 1. First, push images to your internal registry
# Example using harbor.internal.example.com

# Pull images (on internet-connected machine)
docker pull postgres:15-alpine
docker pull minio/minio:latest
docker pull warehouse13/api:v1.0.0
docker pull warehouse13/frontend:v1.0.0

# Tag for internal registry
docker tag postgres:15-alpine harbor.internal.example.com/library/postgres:15-alpine
docker tag minio/minio:latest harbor.internal.example.com/library/minio:latest
docker tag warehouse13/api:v1.0.0 harbor.internal.example.com/warehouse13/api:v1.0.0
docker tag warehouse13/frontend:v1.0.0 harbor.internal.example.com/warehouse13/frontend:v1.0.0

# Push to internal registry
docker push harbor.internal.example.com/library/postgres:15-alpine
docker push harbor.internal.example.com/library/minio:latest
docker push harbor.internal.example.com/warehouse13/api:v1.0.0
docker push harbor.internal.example.com/warehouse13/frontend:v1.0.0

# 2. Update the values file with your registry
cp ./helm/warehouse13/values-airgapped.yaml ./my-airgapped-values.yaml

# Edit to match your environment:
# - Update all image.repository values
# - Set secure passwords
# - Configure storage classes
# - Add node selectors/tolerations if needed

# 3. Install on air-gapped cluster
helm install warehouse13 ./helm/warehouse13 \
  --namespace warehouse13 \
  --create-namespace \
  --values ./my-airgapped-values.yaml
```

**Features:**
- All images from custom registry
- Local storage class support
- Node selectors for specific nodes
- Tolerations for tainted nodes

## Configuration

### Configurable Images

All component images can be customized:

```yaml
# PostgreSQL
postgres:
  image:
    repository: postgres           # or your-registry/postgres
    tag: 15-alpine
    pullPolicy: IfNotPresent

# MinIO
minio:
  image:
    repository: minio/minio        # or your-registry/minio
    tag: latest
    pullPolicy: IfNotPresent

# API Backend
api:
  image:
    repository: warehouse13/api    # or your-registry/warehouse13-api
    tag: v1.0.0
    pullPolicy: IfNotPresent

# Frontend
frontend:
  image:
    repository: warehouse13/frontend  # or your-registry/warehouse13-frontend
    tag: v1.0.0
    pullPolicy: IfNotPresent
```

### Quick Image Override

```bash
# Override images from command line
helm install warehouse13 ./helm/warehouse13 \
  --set postgres.image.repository=myregistry.com/postgres \
  --set postgres.image.tag=15-alpine \
  --set minio.image.repository=myregistry.com/minio \
  --set minio.image.tag=latest \
  --set api.image.repository=myregistry.com/warehouse13-api \
  --set api.image.tag=v1.0.0 \
  --set frontend.image.repository=myregistry.com/warehouse13-frontend \
  --set frontend.image.tag=v1.0.0
```

### Storage Configuration

```yaml
# PostgreSQL storage
postgres:
  persistence:
    enabled: true
    size: 50Gi
    storageClass: "fast-ssd"  # or "" for default

# MinIO storage
minio:
  persistence:
    enabled: true
    size: 500Gi
    storageClass: "bulk-storage"  # or "" for default
```

### Resource Configuration

```yaml
# API resources
api:
  resources:
    requests:
      memory: "512Mi"
      cpu: "500m"
    limits:
      memory: "1Gi"
      cpu: "1000m"

# Frontend resources
frontend:
  resources:
    requests:
      memory: "256Mi"
      cpu: "250m"
    limits:
      memory: "512Mi"
      cpu: "500m"
```

### Ingress Configuration

```yaml
ingress:
  enabled: true
  className: "nginx"
  annotations:
    cert-manager.io/cluster-issuer: "letsencrypt-prod"
    nginx.ingress.kubernetes.io/ssl-redirect: "true"
  hosts:
    - host: warehouse13.example.com
      paths:
        - path: /
          pathType: Prefix
          backend: frontend
        - path: /api
          pathType: Prefix
          backend: api
  tls:
    - secretName: warehouse13-tls
      hosts:
        - warehouse13.example.com
```

## Post-Deployment

### Verify Installation

```bash
# Check all pods are running
kubectl get pods -n warehouse13

# Check services
kubectl get svc -n warehouse13

# Check PVCs
kubectl get pvc -n warehouse13

# Check ingress (if enabled)
kubectl get ingress -n warehouse13
```

### View Logs

```bash
# API logs
kubectl logs -n warehouse13 -l app.kubernetes.io/component=api --tail=100 -f

# Frontend logs
kubectl logs -n warehouse13 -l app.kubernetes.io/component=frontend --tail=100 -f

# PostgreSQL logs
kubectl logs -n warehouse13 warehouse13-postgres-0 --tail=100 -f

# MinIO logs
kubectl logs -n warehouse13 warehouse13-minio-0 --tail=100 -f
```

### Initialize MinIO Bucket

```bash
# Port-forward to MinIO console
kubectl port-forward -n warehouse13 svc/warehouse13-minio 9001:9001

# Open http://localhost:9001
# Login with credentials from values.yaml
# Create bucket: "artifacts"
```

## Upgrading

### Upgrade to New Version

```bash
# Update image tags in values file
# Then run upgrade
helm upgrade warehouse13 ./helm/warehouse13 \
  --namespace warehouse13 \
  --values ./my-production-values.yaml \
  --wait \
  --timeout 10m

# Check rollout status
kubectl rollout status deployment/warehouse13-api -n warehouse13
kubectl rollout status deployment/warehouse13-frontend -n warehouse13
```

### Rollback

```bash
# View revision history
helm history warehouse13 -n warehouse13

# Rollback to previous version
helm rollback warehouse13 -n warehouse13

# Rollback to specific revision
helm rollback warehouse13 2 -n warehouse13
```

### Update Values Only

```bash
# Update configuration without changing images
helm upgrade warehouse13 ./helm/warehouse13 \
  --namespace warehouse13 \
  --values ./my-updated-values.yaml \
  --reuse-values
```

## Backup and Restore

### PostgreSQL Backup

```bash
# Create backup
kubectl exec -n warehouse13 warehouse13-postgres-0 -- \
  pg_dump -U warehouse13user warehouse13 > backup-$(date +%Y%m%d).sql

# Restore
cat backup-20241016.sql | kubectl exec -i -n warehouse13 warehouse13-postgres-0 -- \
  psql -U warehouse13user warehouse13
```

### MinIO Backup

```bash
# Install MinIO Client
wget https://dl.min.io/client/mc/release/linux-amd64/mc
chmod +x mc

# Configure
kubectl port-forward -n warehouse13 svc/warehouse13-minio 9000:9000
mc alias set w13 http://localhost:9000 <access-key> <secret-key>

# Backup bucket
mc mirror w13/artifacts ./backup/artifacts-$(date +%Y%m%d)

# Restore
mc mirror ./backup/artifacts-20241016 w13/artifacts
```

### Full Backup

```bash
# Backup all PVCs
for pvc in $(kubectl get pvc -n warehouse13 -o name); do
  pvc_name=$(basename $pvc)
  kubectl get -n warehouse13 $pvc -o yaml > backup-${pvc_name}.yaml
done

# Backup Helm values
helm get values warehouse13 -n warehouse13 > backup-values.yaml
```

## Troubleshooting

### Pods Not Starting

```bash
# Check pod status
kubectl get pods -n warehouse13

# Describe pod for events
kubectl describe pod <pod-name> -n warehouse13

# Check logs
kubectl logs <pod-name> -n warehouse13

# Common issues:
# - ImagePullBackOff: Check image repository and credentials
# - Pending: Check PVC status and node resources
# - CrashLoopBackOff: Check application logs
```

### PVC Issues

```bash
# Check PVC status
kubectl get pvc -n warehouse13

# Describe PVC
kubectl describe pvc <pvc-name> -n warehouse13

# Common issues:
# - Pending: No storage class or insufficient storage
# - Bound: PVC is healthy
```

### Database Connection Issues

```bash
# Test PostgreSQL connection
kubectl exec -it -n warehouse13 warehouse13-postgres-0 -- \
  psql -U warehouse13user -d warehouse13

# Check database logs
kubectl logs -n warehouse13 warehouse13-postgres-0 --tail=100

# Verify secret
kubectl get secret -n warehouse13 warehouse13-secrets -o yaml
```

### Ingress Not Working

```bash
# Check ingress status
kubectl get ingress -n warehouse13
kubectl describe ingress -n warehouse13 warehouse13-ingress

# Check ingress controller logs
kubectl logs -n ingress-nginx -l app.kubernetes.io/component=controller

# Verify TLS certificate
kubectl get certificate -n warehouse13
kubectl describe certificate -n warehouse13 warehouse13-tls
```

### Performance Issues

```bash
# Check resource usage
kubectl top pods -n warehouse13
kubectl top nodes

# Check if pods are being throttled
kubectl describe pod <pod-name> -n warehouse13 | grep -A 5 "State:"

# Increase resources
helm upgrade warehouse13 ./helm/warehouse13 \
  --set api.resources.limits.memory=2Gi \
  --set api.resources.limits.cpu=2000m
```

## Uninstalling

```bash
# Uninstall the release
helm uninstall warehouse13 -n warehouse13

# Delete PVCs (data will be lost!)
kubectl delete pvc -n warehouse13 -l app.kubernetes.io/instance=warehouse13

# Delete namespace
kubectl delete namespace warehouse13
```

## Additional Resources

- [Helm Chart README](./helm/warehouse13/README.md)
- [Values Documentation](./helm/warehouse13/values.yaml)
- [Docker Deployment Guide](./DEPLOYMENT.md)
- [Main README](./README.md)

## Support

For issues and questions:
- GitHub Issues: https://github.com/yourusername/warehouse13/issues
- Helm Chart Issues: Tag with `helm` label