HINDSIGHT HELM CHART INSTALLATION GUIDE
=====================================

PREREQUISITES
-------------
- Kubernetes cluster (1.19+)
- kubectl configured
- Helm 3.x installed
- PostgreSQL database with pgvector extension (if not using bundled PostgreSQL)

BASIC INSTALLATION
------------------

1. Install with default values (requires external PostgreSQL):

   helm install hindsight ./hindsight \
     --set postgresql.external.host=your-postgres-host \
     --set postgresql.external.password=your-password \
     --set api.secrets.MEMORY_LLM_API_KEY=your-api-key

2. Install with custom values file:

   helm install hindsight ./hindsight -f hindsight/values-production.yaml

3. Install in a specific namespace:

   kubectl create namespace hindsight
   helm install hindsight ./hindsight -n hindsight

CONFIGURATION OPTIONS
---------------------

Development setup (using values-development.yaml):
   helm install hindsight ./hindsight -f hindsight/values-development.yaml

Production setup (using values-production.yaml):
   helm install hindsight ./hindsight -f hindsight/values-production.yaml

Custom LLM provider:
   helm install hindsight ./hindsight \
     --set api.env.MEMORY_LLM_PROVIDER=openai \
     --set api.env.MEMORY_LLM_MODEL=gpt-4 \
     --set api.secrets.MEMORY_LLM_API_KEY=sk-your-key

Enable ingress:
   helm install hindsight ./hindsight \
     --set ingress.enabled=true \
     --set ingress.hosts[0].host=hindsight.example.com

Enable autoscaling:
   helm install hindsight ./hindsight \
     --set autoscaling.enabled=true \
     --set autoscaling.minReplicas=2 \
     --set autoscaling.maxReplicas=10

UPGRADE
-------

Upgrade existing installation:
   helm upgrade hindsight ./hindsight

Upgrade with new values:
   helm upgrade hindsight ./hindsight -f hindsight/values-production.yaml

UNINSTALL
---------

Remove the Helm release:
   helm uninstall hindsight

Remove with namespace:
   helm uninstall hindsight -n hindsight

TESTING
-------

Test the installation with dry-run:
   helm install hindsight ./hindsight --dry-run --debug

Validate templates:
   helm template hindsight ./hindsight

Lint the chart:
   helm lint ./hindsight

ACCESSING THE SERVICES
----------------------

Port-forward control plane:
   kubectl port-forward svc/hindsight-control-plane 3000:3000

Port-forward API:
   kubectl port-forward svc/hindsight-api 8888:8888

Get service URLs:
   helm status hindsight

DATABASE INITIALIZATION
-----------------------

NOTE: Database migrations now run automatically when the API service starts.
      You typically don't need to run migrations manually.

If you want to pre-initialize the database before deploying (optional):
   kubectl run hindsight-init --rm -it --restart=Never \
     --image=hindsight/api:latest \
     --env="DATABASE_URL=postgresql://user:pass@host:5432/hindsight" \
     -- python -c "from hindsight.migrations import run_migrations; run_migrations()"

TROUBLESHOOTING
---------------

Check pod status:
   kubectl get pods -l app.kubernetes.io/name=hindsight

View logs for API:
   kubectl logs -l app.kubernetes.io/component=api

View logs for control plane:
   kubectl logs -l app.kubernetes.io/component=control-plane

Describe a pod:
   kubectl describe pod <pod-name>

Check configuration:
   kubectl get configmap hindsight-config -o yaml
   kubectl get secret hindsight-secret -o yaml

NOTES
-----
- Make sure PostgreSQL has pgvector extension enabled
- Run database migrations before first use
- Configure proper resource limits for production
- Use external secrets management for production
- Enable TLS/SSL for production deployments