SYS.DOCS // DOCS

Deploy and Operate Typesense

Typesense is an open-source, typo-tolerant search engine with built-in clustering. Edka deploys it as a managed app in your Kubernetes cluster, provisions its persistent storage, generates its bootstrap admin API key, and can expose it through Envoy Gateway.

Edka installs its own Typesense Helm chart (typesense from https://charts.edka.io), not a manual Typesense install. Typesense keeps its own state on its persistent volumes; it does not need an existing database or object storage integration.

Architecture

Component	Purpose	How Edka connects it
Typesense nodes	Search API, indexing, and clustering	Installed from the Edka Typesense Helm chart, scaled by Node Count
Persistent volume	Stores each node’s search index and, optionally, aggregated search analytics	One volume per pod, sized and classed from the Storage tab
Admin API Key	Authenticates all Typesense API requests	Generated by Edka and stored in a Kubernetes Secret
Envoy Gateway (optional)	External HTTPS access to the API	Select a traffic class and hostname in the Access tab

Prerequisites

Before installing Typesense, prepare:

an Edka cluster with a storage class available for persistent volumes (Typesense defaults to hcloud-volumes)
a decision on Node Count: 1 node for lowest cost, or 3, 5, or 7 nodes for high availability
if you plan to expose the API outside the cluster: an Envoy Gateway traffic class and a DNS hostname for it

See Hetzner Integration for volume and storage class details, and Gateway API if a traffic class is not ready yet.

Install Typesense

Open your cluster and select Apps.
Find Typesense and select Install.
In General, choose the Namespace, Node Count, Typesense Chart Version, and Typesense Image Tag, and decide whether Edka may automatically apply chart and image updates.
In Configuration, review CORS, search analytics, and the query, indexing, and write-guardrail settings described below. Edka generates the Admin API Key automatically.
In Storage, set the Storage Size (Gi) and Storage Class.
In Resources, review the CPU and memory requests and limits.
In Placement, optionally select a Node Pool and tolerate its taints.
In Access, enable Expose Typesense via Gateway and set a Hostname if you want external access.
Select Install App and follow the operation progress until Typesense is ready.

Admin API Key

Secret	Purpose	Handling
Admin API Key	Authenticates all Typesense API requests	Generated by Edka at install (48 characters, minimum 16), stored in the app’s runtime Secret, not editable after install

Leaving the field blank on a configuration update keeps the current generated key; Edka does not overwrite it.

Configuration

CORS

Enable CORS (default off) lets browser applications call Typesense directly.
When enabled, CORS Domains is required: a comma-separated list of allowed origins, for example https://example.com,https://app.example.com.

Search analytics

Search Analytics (default off) persists aggregated search query analytics on the Typesense volume.
When enabled, set Analytics Flush Interval (seconds, default 3600, range 60-86400) and Analytics Rate Limit (events per minute, default 5, range 1-100000).

Query, indexing, and write guardrails

Setting	Default	Range
Cache Entries	1000	0 - 1,000,000
Indexing Concurrency	0 (Typesense decides)	0 - 256
Memory Write Limit	100%	1 - 100
Disk Write Limit	100%	1 - 100
Snapshot Interval	3600 seconds	60 - 86400
Max Results Per Page	250	1 - 1000
Max Group Limit	99	1 - 1000

Memory Write Limit and Disk Write Limit reject writes once memory or disk usage crosses the configured percentage. Snapshot Interval controls how often Typesense snapshots its replication log.

Storage, Resources, and Placement

Option	Default	Notes
Storage Size (Gi)	10	Minimum 10 GiB, per pod
Storage Class	`hcloud-volumes`	Fixed at install time
CPU Request	100m	Per pod
Memory Request	256Mi	Per pod
CPU Limit	1000m	Per pod
Memory Limit	512Mi	Per pod

Resources and storage are per pod, so a 3-node cluster reserves 300m CPU and 768Mi memory at the request level across the cluster. You can also place Typesense on a selected node pool and automatically tolerate that pool’s taints.

Access and Endpoints

Typesense is reachable in-cluster by default at http://<release-name>.<namespace>.svc.cluster.local:8108. To publish it outside the cluster, enable Expose Typesense via Gateway, then select a Traffic Class and a Hostname. Edka creates an HTTPRoute on the selected Gateway that matches all paths and forwards them to the Typesense service on port 8108.

After installation, Edka shows:

the internal Typesense API service URL and its port (8108)
the external HTTPS URL when Gateway access is enabled

Updates

Chart and image auto-updates are opt-in and cover two targets together: the Typesense chart version (from https://charts.edka.io) and the Typesense image tag (typesense/typesense). You can allow patch, minor, major, all, or a custom tag pattern (a glob: or regexp: filter), and choose how often Edka checks: every 5 minutes, every 30 minutes, every hour, every 6 hours, or daily. Updates preserve the generated Admin API Key.

Troubleshooting

Symptom	Check
CORS Domains is rejected	Required once Enable CORS is on; provide comma-separated origins
Traffic Class or Hostname is rejected	Both are required once Expose Typesense via Gateway is on
Hostname is rejected	Must pass domain validation, for example `typesense.example.com`
Storage Size (Gi) is rejected	Minimum is 10 GiB
Admin API Key edit has no effect	The field is not editable after install; leave it blank to keep the generated key
Typesense pod stays unready	Check that the persistent volume is bound on the selected storage class and that the requested resources fit the node pool