Actyze Helm Charts

Production-ready Helm charts for deploying Actyze on Kubernetes — the open-source AI-native analytics platform.

Main repo · Docker Compose · Documentation · Website

Who this is for

Actyze is built for three teams:

Teams already running Trino. The AI/BI layer your federation has been missing — natural-language queries, dashboards, and ML predictions on top of the catalogs you already have.
Metabase or Superset users. Add NL queries and no-code ML predictions without ripping out your stack.
Cortex / Genie escapees. Same AI capabilities — text-to-SQL, semantic understanding, predictions — on your own infrastructure, no per-credit pricing, no vendor lock-in.

AGPL v3, fully self-hosted, your data never leaves your network.

Overview

Actyze is an AI-powered natural language to SQL analytics platform that enables users to query databases using plain English.

Components:

Frontend: React-based web interface
Nexus: FastAPI orchestration service
Schema Service: FAISS-powered schema recommendations with multilingual support (50+ languages)
PostgreSQL: Application database
Trino: Distributed SQL query engine for federated queries

Image Pull Policy: All Actyze images are configured with pullPolicy: Always to automatically pull the latest versions from Docker Hub:

actyze/dashboard-nexus:main-llm-flex
actyze/dashboard-frontend:latest
actyze/dashboard-schema-service:latest

Prerequisites

Kubernetes cluster: v1.24 or higher
Helm: 3.x
kubectl: Configured to access your cluster
Resources: See Production Requirements below

Recommended Cluster Sizing

For production deployments:

Standard Production: 4-5 nodes × 8 CPU × 16Gi RAM (or 3 nodes × 16 CPU × 32Gi RAM)
Enterprise: 4-5 nodes × 16 CPU × 32Gi RAM (or 3 nodes × 32 CPU × 64Gi RAM)
Minimum (Dev/Testing): 2-3 nodes × 4 CPU × 8Gi RAM

See Complete Resource Specifications for detailed requirements per service.

Quick Start

# Clone repository
git clone https://github.com/actyze/helm-charts.git
cd helm-charts

# Configure secrets
cp dashboard/values-secrets.yaml.template dashboard/values-secrets.yaml
nano dashboard/values-secrets.yaml
# Add your LLM API key and other secrets

# Install Actyze
helm install dashboard ./dashboard \
  --namespace actyze \
  --create-namespace \
  --values dashboard/values.yaml \
  --values dashboard/values-secrets.yaml \
  --wait

Production Configuration

Resource Requirements

Actyze provides three production-ready resource tiers:

Tier	Use Case	Total Resources	Cluster Size
Minimum	Dev/Testing	~4 CPUs, ~7Gi RAM	2-3 nodes × 4 CPU × 8Gi RAM
Recommended	Standard Production	~12 CPUs, ~21Gi RAM	4-5 nodes × 8 CPU × 16Gi RAM
Enterprise	Maximum Performance	~30 CPUs, ~46Gi RAM	4-5 nodes × 16 CPU × 32Gi RAM

Key Services (Recommended Tier):

Trino: 12Gi RAM, 6 CPUs (distributed SQL queries)
Schema Service: 6Gi RAM, 4 CPUs (CPU-intensive FAISS + spaCy operations)
Nexus: 1Gi RAM, 500m CPU × 3 replicas (orchestration)
Frontend: 256Mi RAM, 200m CPU × 2 replicas
PostgreSQL: 2Gi RAM, 1 CPU

See Production-Grade Resource Specifications for:

Complete YAML examples for each tier
Cluster size calculators
Autoscaling configurations
Storage requirements

Operational Configuration

Production deployments require proper configuration of:

Cache Configuration:

Query cache (100-500 queries)
LLM response cache (100-500 responses)
Schema cache (512Mi-2Gi)
Metadata cache (256Mi-1Gi)

Timeout Configuration:

SQL execution: 120-300 seconds (EXECUTE_TIMEOUT_SECONDS — also sets frontend HTTP timeout to this value + 30s)
LLM API calls: 120 seconds (EXTERNAL_LLM_TIMEOUT)
Trino queries: 300-600 seconds (hard upper limit, separate from execution timeout)
Ingress timeouts: must be ≥ EXECUTE_TIMEOUT_SECONDS + 60s to avoid ingress dropping long queries

Connection Pools:

20-50 connections per Nexus replica
Connection recycling every 1-3 hours
Proper timeout and overflow settings

Rate Limiting:

Ingress: 100-500 requests/min per IP
Application: 50-200 requests/min per user
LLM API: 10-50 calls/min (cost control)

Retry & Circuit Breaker:

Exponential backoff for external services
Circuit breaker for Schema Service and LLM API
Trino query retries with proper limits

See Operational Configuration Guide for complete YAML examples and production-ready values.

Architecture

┌─────────────┐
│   Frontend  │  (React + Tailwind)
└──────┬──────┘
       │
┌──────▼──────┐
│    Nexus    │  (FastAPI Orchestration)
└──────┬──────┘
       │
       ├────────────────┬────────────────┐
       │                │                │
┌──────▼──────┐  ┌──────▼──────┐  ┌─────▼─────┐
│   Schema    │  │   Trino     │  │ PostgreSQL│
│   Service   │  │   Engine    │  │           │
└─────────────┘  └──────┬──────┘  └───────────┘
                        │
                 ┌──────▼──────────┐
                 │  Your Databases │
                 │  (PostgreSQL,   │
                 │   MongoDB,      │
                 │   Snowflake,    │
                 │   BigQuery...)  │
                 └─────────────────┘

Architecture Highlights:

Frontend communicates with Nexus API
Nexus orchestrates Schema Service, Trino, and PostgreSQL
Schema Service uses FAISS for intelligent table recommendations
Trino federates queries across multiple data sources
PostgreSQL stores application metadata and user data

Documentation

Complete Helm Guide - Comprehensive deployment reference
Getting Started - Step-by-step setup guide
VALUES_README.md - Configuration reference
LLM_PROVIDERS.md - LLM provider setup
MIGRATIONS_README.md - Database migrations
Features Guide - Platform features

Configuration

AI Provider Setup

Connect Actyze to your preferred AI provider with simple configuration.

🌟 Powered by LiteLLM

Actyze supports 100+ AI providers through LiteLLM integration - from major cloud providers to local open-source models.

📚 See All Supported Providers:

AI Providers Documentation - Complete list of 100+ providers
LiteLLM Providers - Official provider documentation

Direct Connection (Recommended for most organizations)

# values.yaml
modelStrategy:
  externalLLM:
    enabled: true
    model: "claude-sonnet-4-20250514"  # or gpt-4, gemini/gemini-pro, etc.

# values-secrets.yaml
secrets:
  externalLLM:
    apiKey: "sk-ant-xxxxx"  # Provider-specific API key

Enterprise Gateway (For IT-managed AI access)

# values.yaml
modelStrategy:
  externalLLM:
    enabled: true
    mode: "openai-compatible"
    model: "your-internal-model"
    baseUrl: "https://llm-gateway.company.com/v1/chat/completions"
    authType: "bearer"
    extraHeaders: '{"X-Department": "engineering"}'

# values-secrets.yaml
secrets:
  externalLLM:
    apiKey: "your-enterprise-token"

Popular AI Providers:

Anthropic Claude (Recommended) - Best for most users with excellent SQL accuracy
OpenAI GPT-4 - Best for enterprises already using OpenAI services
Google Gemini - Best for cost-conscious users needing fast responses
AWS Bedrock - Best for organizations on AWS infrastructure
Azure OpenAI - Best for Microsoft Azure customers with compliance requirements
Perplexity, Groq, and 90+ more

Benefits:

✅ No Vendor Lock-in - Switch providers anytime
✅ Simple Setup - Just 2 configuration settings
✅ Use What You Have - Works with existing accounts
✅ Enterprise Ready - Connect through your company gateway
✅ Cost Transparency - Track usage and spending

See LLM Provider Configuration for detailed provider-specific examples and enterprise integration.

Database Connectors (Trino Catalogs)

Configure Trino catalogs in values.yaml to connect to your data sources:

trino:
  catalogs:
    postgres:
      connector.name: postgresql
      connection-url: jdbc:postgresql://your-host:5432/database
      connection-user: your-user
      connection-password: your-password
    
    snowflake:
      connector.name: snowflake
      snowflake.account: your-account
      snowflake.user: your-user
      snowflake.password: your-password

Supported Data Sources:

Relational: PostgreSQL, MySQL, SQL Server, Oracle, MariaDB
Cloud Data Warehouses: Snowflake, Databricks, BigQuery, Redshift
NoSQL: MongoDB, Cassandra, Elasticsearch
Data Lakes: Iceberg, Delta Lake, Hudi, Hive

See Database Connectors Guide for configuration examples.

Ingress Configuration

Configure ingress for external access:

ingress:
  enabled: true
  className: "nginx"
  annotations:
    cert-manager.io/cluster-issuer: "letsencrypt-prod"
  hosts:
    - host: analytics.yourcompany.com
      paths:
        - path: /
          pathType: Prefix
          service: frontend
        - path: /api
          pathType: Prefix
          service: nexus
  tls:
    - secretName: actyze-tls
      hosts:
        - analytics.yourcompany.com

Development

Testing Charts Locally

# Lint the chart
helm lint ./dashboard

# Dry run to see what will be deployed
helm install dashboard ./dashboard \
  --dry-run --debug \
  --values dashboard/values.yaml \
  --values dashboard/values-secrets.yaml

# Template the chart to see rendered manifests
helm template dashboard ./dashboard \
  --values dashboard/values.yaml \
  --values dashboard/values-secrets.yaml > output.yaml

Upgrading Charts

# Upgrade an existing release
helm upgrade dashboard ./dashboard \
  --namespace actyze \
  --values dashboard/values.yaml \
  --values dashboard/values-secrets.yaml

# Check upgrade status
helm status dashboard --namespace actyze

# Rollback if needed
helm rollback dashboard --namespace actyze

Management

Common Operations

# Check deployment status
helm list --namespace actyze
kubectl get pods --namespace actyze

# View logs
kubectl logs -f deployment/dashboard-nexus --namespace actyze
kubectl logs -f deployment/dashboard-schema-service --namespace actyze

# Update images (with pullPolicy: Always, just restart)
kubectl rollout restart deployment/dashboard-nexus --namespace actyze
kubectl rollout restart deployment/dashboard-frontend --namespace actyze
kubectl rollout restart deployment/dashboard-schema-service --namespace actyze

# Scale services
kubectl scale deployment/dashboard-nexus --replicas=5 --namespace actyze

# Access services directly (for debugging)
kubectl port-forward svc/dashboard-frontend 3000:80 --namespace actyze
kubectl port-forward svc/dashboard-nexus 8002:8002 --namespace actyze

Uninstall

# Uninstall Actyze (preserves PVCs)
helm uninstall dashboard --namespace actyze

# Delete PVCs if needed
kubectl delete pvc --all --namespace actyze

# Delete namespace
kubectl delete namespace actyze

Features

Core Capabilities:

Natural Language to SQL conversion using LLMs
Multilingual support (50+ languages via sentence-transformers)
FAISS-based intelligent schema recommendations
CSV/Excel file upload for ad-hoc analysis
Role-Based Access Control (Admin, User, Read-Only)
Scheduled KPIs (gold layer) — pre-aggregate metrics on a 1-24h schedule as real queryable tables
Preferred tables (user-curated table priority list with full metadata sent to LLM)
Organization-level metadata descriptions
Query caching for performance and cost optimization
Multi-database federation via Trino

See Features Overview for detailed descriptions.

Support

Documentation: https://docs.actyze.io
Website: https://actyze.ai
GitHub Issues: https://github.com/actyze/helm-charts/issues
Docker Hub: https://hub.docker.com/u/actyze
Main Project: https://github.com/actyze/dashboard

Related Repositories

actyze/dashboard — primary monorepo (frontend, Nexus API, schema service)
actyze/dashboard-docker — Docker Compose deployment for local / single-host installs

License

AGPL-3.0-or-later

Name		Name	Last commit message	Last commit date
.github		.github
dashboard		dashboard
.gitignore		.gitignore
DEPLOYMENT.md		DEPLOYMENT.md
LICENSE		LICENSE
README.md		README.md
RELEASE_PREP_COMMANDS.md		RELEASE_PREP_COMMANDS.md
deploy-to-kind.sh		deploy-to-kind.sh

Navigation Menu

Uh oh!

Repository files navigation

Actyze Helm Charts

Who this is for

Overview

Prerequisites

Recommended Cluster Sizing

Quick Start

Production Configuration

Resource Requirements

Operational Configuration

Architecture

Documentation

Configuration

AI Provider Setup

Database Connectors (Trino Catalogs)

Ingress Configuration

Development

Testing Charts Locally

Upgrading Charts

Management

Common Operations

Uninstall

Features

Support

Related Repositories

License

About

Releases

Packages

Contributors

Languages

Uh oh!

Latest commit

History

Folders and files

Repository files navigation

Actyze Helm Charts

Who this is for

Overview

Prerequisites

Recommended Cluster Sizing

Quick Start

Production Configuration

Resource Requirements

Operational Configuration

Architecture

Documentation

Configuration

AI Provider Setup

Database Connectors (Trino Catalogs)

Ingress Configuration

Development

Testing Charts Locally

Upgrading Charts

Management

Common Operations

Uninstall

Features

Support

Related Repositories

License

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages