Meilisearch

Overview

Meilisearch is an open-source (MIT) search engine for instant, typo-tolerant, faceted search — a self-hosted alternative to Algolia, driven entirely by a REST API on a single port. This template deploys one Meilisearch server with persistent index storage, mandatory master-key authentication, an indexing memory budget derived from the container’s own memory limit, optional scheduled Meilisearch snapshots, and scheduled platform volume backups. The image is the Community build, compiled without any Enterprise code. Replication and sharding are not part of it, so the template runs exactly one replica (see Scaling and Availability).

This template deploys into an existing GVC. It does not create one. Every resource lands in the GVC you pass at install time, so cpln workload exec, cpln logs and uninstalling all work against that GVC. Install into a GVC with a single location: a workload runs in every location its GVC has, and each location would get its own independent, diverging index behind one endpoint.

What Gets Created

Resource	Name	Purpose	Optional
Workload	`RELEASE_NAME-meilisearch`	Meilisearch server (stateful, 1 replica), REST API on port `7700`	—
Volume Set	`RELEASE_NAME-meilisearch-data`	`ext4` volume mounted at `/meili_data` holding the index (`data.ms`), Meilisearch snapshots and dumps; scheduled platform snapshots and a final snapshot on delete	—
Identity	`RELEASE_NAME-meilisearch-identity`	Workload identity used to read the master-key secret	—
Policy	`RELEASE_NAME-meilisearch-policy`	`reveal` on exactly the one secret named in `auth.secretName`	—

The template creates no secrets of its own and needs no database, cache or object store. The master-key secret is yours, created before installing and left untouched on uninstall.

Prerequisites

Create the master-key secret

Meilisearch refuses every route except GET /health without a master key, and the key must be at least 16 bytes while server.env is production. Create an opaque secret whose entire payload is the key:

printf '%s' "$(openssl rand -hex 32)" | cpln secret create-opaque --name SECRET_NAME --encoding plain -f -

Set auth.secretName to this name.

The secret must exist before you install. A workload that references a secret that does not exist wedges silently: it never becomes ready, cpln logs returns nothing, and the only place the missing secret is named is status.versions[].message:

cpln workload get-deployments RELEASE_NAME-meilisearch --gvc GVC_NAME -o yaml

Once the secret exists the deployment recovers on its own after several minutes, or immediately with cpln workload force-redeployment RELEASE_NAME-meilisearch --gvc GVC_NAME.

Treat the master key as write-once. Meilisearch derives all four of its built-in API keys from it, so rotating it changes every key and breaks every deployed client until you redistribute them. If you must rotate, update the secret, then run cpln workload force-redeployment RELEASE_NAME-meilisearch --gvc GVC_NAME — a changed secret is only picked up when the replica restarts.

Nothing else is required: no cloud account, no bucket, no external database. Backups use platform volume snapshots.

Installation

Install with the secret name from the prerequisite step; every other value has a working default.

cpln helm install RELEASE_NAME oci://ghcr.io/controlplane-com/templates/meilisearch \
  --version 1.0.0 --gvc GVC_NAME \
  --set auth.secretName=SECRET_NAME

Install the template using your preferred method:

UI

Browse, install, and manage templates visually

CLI

Manage templates from your terminal

Terraform

Declare templates in your Terraform configurations

Pulumi

Declare templates in your Pulumi programs

Configuration

Image

image: getmeili/meilisearch:v1.52.0

Pin a concrete tag. Raising it on a populated volume requires the procedure in Upgrading Meilisearch.

Resources

resources:
  minCpu: 250m
  maxCpu: 1000m
  minMemory: 512Mi
  maxMemory: 2Gi

tuning:
  indexingMemoryPercent: 50 # MEILI_MAX_INDEXING_MEMORY = this percent of maxMemory (20–80)

Searches are served from a memory-mapped index, so steady-state RAM is modest — indexing is the hungry phase. The indexing budget is derived, not absolute: MEILI_MAX_INDEXING_MEMORY is set to tuning.indexingMemoryPercent of resources.maxMemory (at the defaults, 1024MiB), and there is no absolute override, so it can never exceed the container’s own limit. Raise maxMemory to index faster and hold a larger index; raise indexingMemoryPercent (accepted range 20–80, enforced at render time) only if the instance indexes far more often than it searches.

The platform rejects a maxCpu-to-minCpu ratio greater than 4:1 on a stateful workload. The defaults sit exactly at 4:1, so raising maxCpu means raising minCpu too.

Storage

volumeset:
  capacity: 20 # GiB (platform minimum 10) — index, snapshots and dumps share it

The single ext4 volume at /meili_data holds data.ms (the index), snapshots/ and dumps/. The chart rejects a capacity below 10 at render time.

Master Key

auth:
  secretName: my-meilisearch-master-key # name of your pre-created opaque secret

The name of the opaque secret from Prerequisites. Its whole payload is the master key; the chart grants the workload reveal on exactly that secret and nothing else.

Server

server:
  env: production            # production | development — development also serves the search-preview UI at /
  logLevel: INFO             # ERROR | WARN | INFO | DEBUG | TRACE
  maxPayloadSize: "100 MB"   # largest accepted request body; a bigger import is rejected with HTTP 413
  telemetry: false           # true = send anonymous usage data upstream
  upgradeDb: false           # true for ONE deploy when moving to a newer image tag, then set back to false

With server.env: production, GET / returns HTTP 200 with {"status":"Meilisearch is running"} and no HTML. That is a healthy instance — the browser search-preview UI is only served with server.env: development. The master key protects every route either way.

Metrics

metrics:
  enabled: false # true = Prometheus /metrics on port 7700 (needs an API key with the metrics.get action)

These are index-level metrics (documents indexed, searches per index, database size) that the platform’s built-in workload metrics cannot see. The route requires an API key carrying the metrics.get action.

Snapshots

snapshots:
  enabled: false         # scheduled .snapshot files in /meili_data/snapshots — only the newest is kept
  intervalSeconds: 86400 # seconds between snapshots

Meilisearch’s own application-level .snapshot files, written onto the same volume. These are distinct from the platform volume snapshots under backup — see Backing Up for how the two relate.

Backup

backup:
  enabled: true
  schedule: "0 3 * * *" # cron in UTC — daily 03:00 (hourly is the platform max)
  retention: 7d         # how long each snapshot is kept (e.g. 7d, 720h, 30d)

Platform volume snapshots of the whole /meili_data volume. No cloud account or bucket is needed. backup.enabled: false disables the schedule only; the final snapshot on delete is always taken and kept for backup.retention. Changing any backup value updates the volume set without restarting the workload.

Access

publicAccess:
  enabled: false # true = REST API over HTTPS on the auto *.cpln.app endpoint
internalAccess:
  type: same-gvc # none | same-gvc | same-org | workload-list
  workloads: []  # used only with workload-list
  # workloads:
  #   - //gvc/GVC_NAME/workload/WORKLOAD_NAME

`internalAccess.type`	Who can reach port `7700` inside the platform
`none`	No workload
`same-gvc`	Every workload in the same GVC (default)
`same-org`	Every workload in the same org
`workload-list`	Only the workload links in `internalAccess.workloads`

Firewall changes take a few minutes to propagate. After toggling publicAccess or internalAccess, requests may keep returning the old behavior (or 503) for a while — re-test before concluding the knob does not work.

Connecting

What	Address	Notes
Internal REST API (same GVC)	`http://RELEASE_NAME-meilisearch.GVC_NAME.cpln.local:7700`	`Authorization: Bearer <key>` on every route except `GET /health`
Public REST API (`publicAccess.enabled: true`)	`status.canonicalEndpoint` of the workload	HTTPS at the platform edge; same header
Master key	`cpln secret reveal SECRET_NAME -o yaml`	Use it only to fetch the derived API keys below

Read the public hostname from the workload status:

cpln workload get RELEASE_NAME-meilisearch --gvc GVC_NAME -o yaml   # status.canonicalEndpoint

Verify the server is up without exposing it, from your own machine:

cpln port-forward RELEASE_NAME-meilisearch 7700:7700 --gvc GVC_NAME
# in a second terminal
curl http://localhost:7700/health

A healthy server answers {"status":"available"}.

Use a Scoped API Key

On first boot Meilisearch derives four API keys from the master key. Fetch them once and hand the right one to each caller; never give the master key to a browser.

curl -H "Authorization: Bearer YOUR_MASTER_KEY" http://localhost:7700/keys

Key	Use it for
Default Search API Key	Front-ends — search only; writes are rejected with `403 invalid_api_key`
Default Admin API Key	Your indexing pipeline — everything except key management
Default Read-Only Admin API Key	Dashboards and monitoring
Default Chat API Key	The experimental chat route

Index and Search

Indexing is asynchronous: writes return 202 Accepted with a taskUid you can poll on /tasks. From another workload in the GVC, replace localhost:7700 with the internal address above.

MEILI=http://localhost:7700
KEY=YOUR_ADMIN_API_KEY

# create an index
curl -X POST "$MEILI/indexes" -H "Authorization: Bearer $KEY" \
  -H 'Content-Type: application/json' \
  -d '{"uid":"movies","primaryKey":"id"}'

# add documents
curl -X POST "$MEILI/indexes/movies/documents" -H "Authorization: Bearer $KEY" \
  -H 'Content-Type: application/json' \
  -d '[{"id":1,"title":"Interstellar","genre":"sci-fi"}]'

# search — typo tolerance is on by default
curl -X POST "$MEILI/indexes/movies/search" -H "Authorization: Bearer $KEY" \
  -H 'Content-Type: application/json' \
  -d '{"q":"interstelar"}'

The misspelled query returns the Interstellar document.

Operations

Backing Up

Two different things are called “snapshots” here, and they do different jobs:

Mechanism	What it is	Where it lives	Default
`backup`	Platform volume snapshots — crash-consistent copies of the whole `/meili_data` volume	Platform snapshot store, kept for `backup.retention`	On, daily
`snapshots`	Meilisearch’s own `.snapshot` file — an application-consistent copy of the database	`/meili_data/snapshots` on the same volume; only the newest is kept	Off

List the platform snapshots the volume set holds, or take one on demand before a risky change:

cpln volumeset snapshot get RELEASE_NAME-meilisearch-data --gvc GVC_NAME
cpln volumeset snapshot create RELEASE_NAME-meilisearch-data --gvc GVC_NAME --snapshot-name pre-upgrade

Meilisearch can also write its own backups on demand, with or without the schedule enabled. Both are asynchronous tasks you can follow on /tasks:

# application-consistent snapshot → /meili_data/snapshots (same Meilisearch version only)
curl -X POST http://localhost:7700/snapshots -H "Authorization: Bearer YOUR_ADMIN_API_KEY"
# portable dump → /meili_data/dumps (the format that moves data between Meilisearch versions)
curl -X POST http://localhost:7700/dumps -H "Authorization: Bearer YOUR_ADMIN_API_KEY"

A Meilisearch snapshot is version-locked and a dump is not, so a dump is the right file to keep before a version upgrade. Both files sit on the volume, so a platform snapshot of the volume captures them too.

Restoring a Backup

No restore path for this template has been verified. Meilisearch imports a .snapshot or .dump file only at launch, through the --import-snapshot / --import-dump flags, and the chart exposes no values key that sets them. The platform’s volume-snapshot restore has also not been exercised against this template.

What the chart does make true: the index, Meilisearch snapshots and dumps all live on the RELEASE_NAME-meilisearch-data volume set, which the platform snapshots on backup.schedule and on delete. Recovering from one of those snapshots therefore means restoring the volume set rather than anything inside Meilisearch — consult the volume set reference for the platform’s restore procedure. Test any procedure on a disposable release before relying on it.

Upgrading Meilisearch

Meilisearch refuses to open a database written by an older version, so raising image on a populated volume fails by design until you ask for the migration. The chart’s server.upgradeDb sets MEILI_UPGRADE_DB, the upstream in-place upgrade flag.

Confirm a recent backup exists

The migration is not atomic. List the volume set’s snapshots (see Backing Up) and take a Meilisearch dump as a portable fallback.

Deploy the new image with the migration flag

Set image to the new tag and server.upgradeDb: true in the same helm upgrade. The database is upgraded on startup.

Turn the flag back off

Once the workload is ready on the new tag, set server.upgradeDb: false and upgrade again so the migration flag is not left permanently on.

If you raise the image tag without the flag, the new container exits with Your database version (X) is incompatible with your current engine version (Y). and restarts in a loop. The previous, working version keeps serving for a while before the deployment goes not-ready, so a forgotten flag looks fine at first — check cpln workload get-deployments RELEASE_NAME-meilisearch --gvc GVC_NAME -o yaml, not just the first minute.

Scaling and Availability

The template runs exactly one replica, and there is no replicas knob. Replication and sharding are Meilisearch Enterprise features that are not compiled into the Community image, so a second replica would serve a separate, empty index behind the same endpoint. Consequences to plan around:

A helm upgrade or restart is a real outage of the search endpoint, and it begins some time after the command returns. Have your application fall back to a database query while search is unavailable.
An abrupt replica loss recovers on its own with data intact; the volume reattaches to the rescheduled replica.
Scale vertically: raise resources.maxMemory (which also raises the indexing budget) and volumeset.capacity.

Troubleshooting

Deployment never becomes ready and cpln logs returns nothing

Cause: the master-key secret named in auth.secretName does not exist, or did not exist when the workload was created. The container never starts, so there is no container output to collect.Fix: read status.versions[].message, which names the missing secret:

cpln workload get-deployments RELEASE_NAME-meilisearch --gvc GVC_NAME -o yaml

Create the secret (see Prerequisites) and either wait several minutes or run cpln workload force-redeployment RELEASE_NAME-meilisearch --gvc GVC_NAME.

Container exits with: The master key must be at least 16 bytes in a production environment

Cause: the secret’s payload is shorter than 16 bytes while server.env is production.Fix: replace the secret’s value with a longer key (openssl rand -hex 32 produces 64 characters) and force a redeployment. Every derived API key changes with it.

Container restarts with: Your database version (X) is incompatible with your current engine version (Y)

Cause: the image tag was raised on a populated volume without server.upgradeDb: true.Fix: follow Upgrading Meilisearch — redeploy with the same new tag and server.upgradeDb: true, then set it back to false.

Import rejected with HTTP 413 payload_too_large

Cause: the request body is larger than server.maxPayloadSize (default 100 MB). Nothing from that request is written.Fix: send the documents in smaller batches, or raise server.maxPayloadSize and upgrade the release.

GET /metrics returns HTTP 400 feature_not_enabled

Cause: metrics.enabled is false (the default). The route exists but the experimental feature is off, so the answer is 400, not 404.Fix: set metrics.enabled: true, upgrade the release, and call the route with an API key that has the metrics.get action. Without any key the route answers 401.

GET / returns JSON instead of the search-preview UI

Cause: server.env is production, which suppresses the browser UI by design. {"status":"Meilisearch is running"} is a healthy answer.Fix: set server.env: development if you want the playground at /. The master key still protects every route.

Writes fail with HTTP 403 invalid_api_key

Cause: the caller is using the Default Search API Key, which is search-only.Fix: use the Default Admin API Key for indexing (see Use a Scoped API Key). Keep the search key for anything running in a browser.

Important Notes

Create the master-key secret before installing, and confirm it exists with cpln secret reveal SECRET_NAME -o yaml; without it the deployment wedges silently.
Rotating the master key changes every derived API key and requires a forced redeployment to take effect — treat it as write-once.
Never hand the master key to a browser; use the Default Search API Key for front-ends.
Set server.upgradeDb: true for exactly one deploy when raising the image tag, then set it back to false. Confirm a backup first; the migration is not atomic.
Size indexing with resources.maxMemory — the indexing budget is a percentage of it and has no absolute override.
Batch large imports below server.maxPayloadSize; an oversized body is rejected with HTTP 413 and nothing is written.
Install into a single-location GVC; each location gets its own volume and its own diverging index.
Uninstall deletes the volume set. A final snapshot is kept for backup.retention; your master-key secret is left untouched.

External References

Meilisearch Documentation

Official Meilisearch documentation

Configuration Reference

Every environment variable and command-line option

API Keys and Security

Master key, derived keys, and scoping access

Snapshots and Dumps

Meilisearch’s own snapshot and dump formats

Updating Meilisearch

The database migration procedure between versions

Meilisearch Template

View the source files, default values, and chart definition

Template Catalog

Templates

Overview

What Gets Created

Prerequisites

Installation

UI

CLI

Terraform

Pulumi

Configuration

Image

Resources

Storage

Master Key

Server

Metrics

Snapshots

Backup

Access

Connecting

Use a Scoped API Key

Index and Search

Operations

Backing Up

Restoring a Backup

Upgrading Meilisearch

Scaling and Availability

Troubleshooting

Important Notes

External References

Meilisearch Documentation

Configuration Reference

API Keys and Security

Snapshots and Dumps

Updating Meilisearch

Meilisearch Template

​Overview

​What Gets Created

​Prerequisites

​Installation

UI

CLI

Terraform

Pulumi

​Configuration

​Image

​Resources

​Storage

​Master Key

​Server

​Metrics

​Snapshots

​Backup

​Access

​Connecting

​Use a Scoped API Key

​Index and Search

​Operations

​Backing Up

​Restoring a Backup

​Upgrading Meilisearch

​Scaling and Availability

​Troubleshooting

​Important Notes

​External References

Meilisearch Documentation

Configuration Reference

API Keys and Security

Snapshots and Dumps

Updating Meilisearch

Meilisearch Template

Overview

What Gets Created

Prerequisites

Installation

Configuration

Image

Resources

Storage

Master Key

Server

Metrics

Snapshots

Backup

Access

Connecting

Use a Scoped API Key

Index and Search

Operations

Backing Up

Restoring a Backup

Upgrading Meilisearch

Scaling and Availability

Troubleshooting

Important Notes

External References