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
2. Quick Start
3. Deployment Scenarios
4. Configuration
5. Post-Deployment
6. Upgrading
7. Troubleshooting

Prerequisites

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

Installing Helm

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

# 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

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

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:

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

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

# 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

# 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

# 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

# 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

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

# 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

# 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

# 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

# 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

# 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

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

Backup and Restore

PostgreSQL Backup

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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
• Values Documentation
• Docker Deployment Guide
• Main README

Support

For issues and questions:

• GitHub Issues: https://github.com/yourusername/warehouse13/issues
• Helm Chart Issues: Tag with helm label