SYS.DOCS // DOCS

Deploy and Operate Meilisearch

Meilisearch is a fast, typo-tolerant search engine reachable behind an HTTP API. Edka deploys it as a managed app in your Kubernetes cluster from the official Helm chart, with a generated master key, persistent storage for indexes, and Prometheus metrics wired into the platform.

Architecture

Component	Purpose	How Edka connects it
Meilisearch	HTTP API for search, indexing, and task management	Installed from the official Meilisearch Helm chart
Metrics proxy (nginx)	Authenticates to Meilisearch’s own `/metrics` route and re-exposes it	Deployed as a sidecar container in the Meilisearch pod
Persistent volume	Indexes and the task queue	ReadWriteOnce PersistentVolumeClaim on the selected storage class
Metrics Server	Cluster metrics API for pod CPU and memory usage in the Edka app view	Installed automatically as Meilisearch’s required add-on
Envoy Gateway	Optional public HTTPS access to the API	Select a traffic class and hostname in the Access tab

Prerequisites

Before installing Meilisearch, prepare:

a target namespace, or let Edka create the default meilisearch namespace
a storage class for the persistent volume (defaults to hcloud-volumes)
if you plan to publish the API publicly: an Envoy Gateway traffic class and a DNS hostname

Meilisearch does not depend on an external database. Indexes and the task queue live entirely on its own persistent volume.

See Gateway API and Domains and TLS if you plan to expose the API and these are not ready yet.

Install Meilisearch

Open your cluster and select Apps.
Find Meilisearch and select Install.
In General, choose the Namespace, set the Meilisearch Chart Version (default 0.32.0) and Meilisearch Image Tag (default v1.42.1), and leave Master Key blank to let Edka generate one.
In Storage, set Storage Size (Gi) (minimum 10, default 10) and select the Storage Class (default hcloud-volumes).
In Resources, review the CPU and memory requests and limits for the Meilisearch pod and the metrics proxy sidecar.
In Placement, optionally pin Meilisearch to a Node Pool. Keep Tolerate Node Pool Taints enabled to automatically inherit that pool’s taints.
In Access, decide whether to enable Expose API via Gateway. If enabled, select a Traffic Class and enter a Hostname.
Select Install App and follow the operation progress until Meilisearch is ready.

Storage Class and Namespace are fixed once Meilisearch is installed. Meilisearch Chart Version and Meilisearch Image Tag stay editable afterwards; bump either field later to move to a newer chart or image release.

Master Key

The master key protects every Meilisearch API route, including search and indexing requests, and also authenticates the metrics proxy’s request to Meilisearch’s own /metrics endpoint.

Secret	Purpose	Handling
Master Key (`MEILI_MASTER_KEY`)	Authenticates all Meilisearch API requests and the metrics proxy	Generated at install (32 characters) unless you supply your own value of at least 16 characters; stored in the `<release>-master-key` Secret in the app namespace

Edka does not expose a reveal action for the master key in the app configuration UI. Read it directly from the <release>-master-key Secret in your cluster to authenticate API calls outside Edka.

The Master Key field is not editable from the configuration UI after install. Rotating it is a manual operation: update the MEILI_MASTER_KEY key in the <release>-master-key Secret, then restart the Meilisearch pod so the new key takes effect.

Access and Endpoints

Meilisearch is reachable inside the cluster by default. After install, Edka shows:

Meilisearch API: internal HTTP endpoint for search and indexing at http://<release>.<namespace>.svc.cluster.local:7700
Service Port: 7700

Enabling Expose API via Gateway in the Access tab publishes the API through the selected Envoy Gateway traffic class on your hostname. Edka then also shows:

External Access: the Gateway URL at https://<hostname>

Storage, Resources, and Placement

Option	Default	Notes
Storage Size (Gi)	`10`	Minimum `10`; resizable after install
Storage Class	`hcloud-volumes`	Fixed at install time
Meilisearch CPU / Memory request	`250m` / `512Mi`
Meilisearch CPU / Memory limit	`1000m` / `2Gi`
Metrics Proxy CPU / Memory request	`10m` / `32Mi`
Metrics Proxy CPU / Memory limit	`100m` / `64Mi`
Node Pool	none	Optional; pins Meilisearch to a specific node pool
Tolerate Node Pool Taints	enabled	Adds tolerations for the selected node pool’s taints automatically

Metrics

Meilisearch exposes Prometheus metrics behind its master key. Edka runs an nginx sidecar (metrics proxy) that authenticates to Meilisearch’s own /metrics route with the master key and re-exposes it on :9110/metrics, so scrapers do not need the master key themselves. The pod is annotated for scraping on port 9110 at path /metrics.

When the cluster metrics backend is available, Edka’s app view surfaces:

request rate: HTTP requests per second, excluding metrics scrapes
p95 latency: 95th percentile HTTP response time, excluding metrics scrapes
database size: total database size on disk
used storage: used database storage
documents: indexed documents across all indexes
indexes: total number of indexes
queued tasks: tasks waiting to be processed
failed tasks: failed tasks recorded by Meilisearch

See Cluster Metrics for the metrics backend setup.

Troubleshooting

Symptom	Check
Namespace is rejected	Use a valid Kubernetes name: lowercase alphanumeric characters and hyphens
Meilisearch pod stays unready	Check that the PersistentVolumeClaim is Bound on the selected storage class
Access configuration is rejected	Traffic Class and Hostname are both required once Expose API via Gateway is enabled
API calls are rejected	Every Meilisearch API route requires the master key as a Bearer token; read it from the `<release>-master-key` Secret
Metrics are empty	Confirm the cluster metrics backend is installed and scraping the Meilisearch pod on port `9110`