deskree/tetrixaidb-chart repository overview

⁠TetrixAIDb Helm Chart

Production-ready Helm chart for deploying TetrixAIDb Enterprise on Kubernetes: the tetrixaidb daemon plus the tetrixaidb-remote gateway (Web UI + MCP), with the four storage backends (PostgreSQL/pgvector, Neo4j, MeiliSearch, MinIO) bundled but optional.

⁠Prerequisites

• Kubernetes 1.23+
• Helm 3.8+
• An ingress-nginx controller (for the default Ingress)
• cert-manager with a ClusterIssuer (for automatic TLS), or a pre-created TLS secret
• A default StorageClass (or set *.persistence.storageClass) when using bundled backends
• A public DNS record pointing at the ingress controller for ingress.host (HTTPS is required — the UI uses crypto.randomUUID, which needs a secure context)

The deskree/tetrixaidb and deskree/tetrixaidb-remote images are published for both linux/amd64 and linux/arm64, so the chart runs on x86-64 and ARM (e.g. AWS Graviton, Apple Silicon) clusters alike.

⁠Install

The chart is published as an OCI artifact on Docker Hub — no helm repo add needed:

oci://registry-1.docker.io/deskree/tetrixaidb-chart

Pin a specific --version <VERSION> in production (chart versions track Git release tags). List available versions with helm show chart oci://registry-1.docker.io/deskree/tetrixaidb-chart --version <VERSION>. For development, substitute the local path deploy/helm/tetrixaidb for the OCI reference.

⁠Turnkey (bundled databases)

helm install tetrix oci://registry-1.docker.io/deskree/tetrixaidb-chart --version <VERSION> \
  --namespace tetrix --create-namespace \
  --set ingress.host=tetrix.example.com \
  --set ingress.tls.certManager.clusterIssuer=letsencrypt-prod \
  --set secrets.tetrixPassword="$(openssl rand -hex 24)" \
  --set secrets.postgresPassword="$(openssl rand -hex 24)" \
  --set secrets.neo4jPassword="$(openssl rand -hex 24)" \
  --set secrets.meiliMasterKey="$(openssl rand -hex 24)" \
  --set secrets.minioRootPassword="$(openssl rand -hex 24)" \
  --set secrets.aidbPassword="$(openssl rand -hex 24)" \
  --set secrets.openaiApiKey="sk-..."

⁠Bring-your-own (external) databases

helm install tetrix oci://registry-1.docker.io/deskree/tetrixaidb-chart --version <VERSION> \
  --namespace tetrix --create-namespace \
  --set ingress.host=tetrix.example.com \
  --set ingress.tls.certManager.clusterIssuer=letsencrypt-prod \
  --set postgres.enabled=false --set neo4j.enabled=false \
  --set meilisearch.enabled=false --set minio.enabled=false \
  --set externalPostgres.host=pg.internal \
  --set externalNeo4j.uri=bolt://neo4j.internal:7687 \
  --set externalMeilisearch.host=http://meili.internal:7700 \
  --set externalMinio.endpoint=minio.internal:9000 \
  --set secrets.tetrixPassword=... # plus the rest

A ready-made external-DB values file ships in the chart as values-minimal.yaml (pull/extract the chart to use it). When a backend is disabled, its external* connection block becomes required.

For external Postgres you must also create the tetrix role and the pgcrypto + vector (pgvector) extensions yourself before installing:

CREATE EXTENSION IF NOT EXISTS pgcrypto;
CREATE EXTENSION IF NOT EXISTS vector;
CREATE USER tetrix WITH PASSWORD '<POSTGRES_PASSWORD>' LOGIN;
GRANT ALL PRIVILEGES ON DATABASE tetrixaidb TO tetrix;
GRANT ALL ON SCHEMA public TO tetrix;

⁠Using an existing Secret

Create a Secret containing TETRIX_PASSWORD, AIDB_PASSWORD, POSTGRES_PASSWORD, NEO4J_PASSWORD, MEILI_MASTER_KEY, MINIO_ROOT_USER, MINIO_ROOT_PASSWORD, OPENAI_API_KEY, then:

helm install tetrix oci://registry-1.docker.io/deskree/tetrixaidb-chart --version <VERSION> \
  --set secrets.existingSecret=my-tetrix-secret \
  --set ingress.host=tetrix.example.com \
  --set ingress.tls.certManager.clusterIssuer=letsencrypt-prod

⁠Configuration

For the full list of configurable values, run:

helm show values oci://registry-1.docker.io/deskree/tetrixaidb-chart --version <VERSION>

⁠Access after install

With the default Ingress enabled (replace <host> with your ingress.host):

• Web UI — https://<host>/ — log in with username developer (the remote.aidb.username value) and the password from secrets.aidbPassword. HTTPS is required: the UI uses crypto.randomUUID, which needs a secure context.
• MCP SSE endpoint — https://<host>/mcp/v2/sse.

MCP clients (e.g. Cursor) authenticate with a bearer token that is the base64 of {"username":"developer","password":"<AIDB_PASSWORD>"}:

TOKEN=$(printf '{"username":"developer","password":"%s"}' "$AIDB_PASSWORD" | base64)

Cursor mcp.json:

{
  "mcpServers": {
    "tetrix": {
      "url": "https://<host>/mcp/v2/sse",
      "headers": { "Authorization": "Bearer <base64-token>" }
    }
  }
}

When ingress.enabled=false, reach the UI/MCP by port-forwarding the remote Service (<release> is your Helm release name, e.g. tetrix):

kubectl -n tetrix port-forward svc/<release>-tetrixaidb-remote 9091:9091

⁠Operations

⁠Verify

kubectl -n tetrix get pods -l app.kubernetes.io/instance=tetrix
helm test tetrix -n tetrix

⁠Upgrade

helm upgrade tetrix oci://registry-1.docker.io/deskree/tetrixaidb-chart --version <NEW_VERSION> \
  --namespace tetrix --reuse-values

⁠Uninstall

helm uninstall tetrix -n tetrix
# PVCs (data) are retained by design. Delete explicitly to wipe data:
kubectl -n tetrix delete pvc -l app.kubernetes.io/instance=tetrix

⁠Troubleshooting

⁠Bundled DB auth fails after a reinstall (password authentication failed)

The daemon crash-loops with an error like failed SASL auth: FATAL: password authentication failed for user "tetrix" (or the equivalent for Neo4j/MeiliSearch/MinIO).

helm uninstall does not delete PVCs (see Uninstall above), and the bundled backends only apply the password from the Secret on the first boot of an empty data directory. If you reinstall into a namespace that still holds the old data-* PVCs, the database keeps its previous password while the new release generates fresh credentials — and they no longer match. To fully reset bundled state:

helm uninstall tetrix -n tetrix
kubectl -n tetrix delete pvc -l app.kubernetes.io/instance=tetrix
# then reinstall

This does not apply to external (*.enabled=false) backends, where you manage credentials.

⁠Pods stuck Pending with unbound immediate PersistentVolumeClaims

The cluster has no usable default StorageClass, or its provisioner is unhealthy. Check kubectl get storageclass and kubectl -n <ns> describe pvc <name>, then either mark a StorageClass default or set global.storageClass (or per-backend <backend>.persistence.storageClass).

⁠Versioning & bundled images

Chart versions follow SemVer and track Git release tags (no leading v). For a published chart, version == appVersion == the application image tag it deploys. Bundled backends pin specific upstream images:

⁠Air-gapped / internal mirror

Pull once and relocate the chart and images into your own registry:

helm pull oci://registry-1.docker.io/deskree/tetrixaidb-chart --version <VERSION>
# Then push tetrixaidb-<VERSION>.tgz to your internal OCI registry and install with
# --set global.imageRegistry=registry.internal/ to relocate the container images too.

⁠MCP / SSE routing notes

The MCP Ingress strips the /mcp prefix (/mcp/v2/sse → upstream /v2/sse) and sets SSE-safe options: buffering off, 86400s read/send timeouts, HTTP/1.1.

⁠Architecture

                 ingress-nginx (TLS)
                   /            \
              "/"  |             | "/mcp"
                   v             v
        tetrixaidb-remote (UI :9091, MCP :8787)
                        |
                        v
              tetrixaidb daemon (:7779 / :9090)
                        |
        +-------+-------+--------+--------+
        v       v       v        v
     postgres neo4j  meilisearch minio   (bundled StatefulSets or external)