Deploy Typesense search to Kubernetes

Introduction

Document search is important for blogs, documentation sites, support centers, and product catalogs. Typesense is a fast open-source search engine that can be self-hosted when you want more control over infrastructure and data handling.

This guide shows a minimal Kubernetes deployment with persistent storage and a service endpoint.

Why search matters

Search helps users find the right page quickly, especially when content grows beyond a simple navigation tree:

1. Enhanced User Experience: Users no longer have the patience to navigate through a site's hierarchy or use generic search tools that return irrelevant results. An effective search tool understands user intent, offering accurate results swiftly.
2. Increased Engagement: When users can quickly find what they're looking for, they're more likely to stay on your website, reducing bounce rates.
3. Maximized Content Value: No matter how high-quality or valuable your content is, it loses its value if users can't find it. An efficient search tool ensures that your content is accessible and easy to discover.

Why self-host Typesense?

Self-hosting Typesense can be useful when you need:

1. Infrastructure control: Run search in your own cluster and network.
2. Operational flexibility: Tune scaling, storage, and rollout behavior to match your workload.
3. Clear data handling: Keep indexing and query traffic inside infrastructure you operate.
4. Predictable costs: Scale resources directly instead of relying only on hosted usage tiers.

Deploying Typesense on Kubernetes

The examples below use a simple single-node Typesense deployment. For production, review the current Typesense Kubernetes guidance and adapt storage, secrets, networking, and scaling to your environment.

1. Persistent Storage

Create a persistent volume so Typesense data survives pod restarts.

apiVersion: v1
kind: PersistentVolume
metadata:
  name: typesense-data-pv
  namespace: metrics
  labels:
    type: local
spec:
  storageClassName: "gp3"
  capacity:
    storage: 10Gi
  accessModes:
    - ReadWriteOnce
  hostPath:
    path: "/mnt/data"

Then create a PersistentVolumeClaim to request that storage:

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: typesense-data-pvc
  namespace: metrics
spec:
  storageClassName: "gp3"
  accessModes:
    - ReadWriteOnce
  resources:
    requests:
      storage: 10Gi
  selector:
    matchLabels:
      type: local

2. Deploying Typesense

Deploy Typesense with the persistent volume mounted at /data:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: typesense
  namespace: metrics
spec:
  replicas: 1
  selector:
    matchLabels:
      app: typesense
  template:
    metadata:
      namespace: metrics
      labels:
        app: typesense
    spec:
      containers:
        - name: typesense
          image: typesense/typesense:0.25.1
          args: ["--data-dir", "/data", "--api-key=africa", "--enable-cors"]
          ports:
            - containerPort: 8108
          volumeMounts:
            - mountPath: /data
              name: typesense-data
      volumes:
        - name: typesense-data
          persistentVolumeClaim:
            claimName: typesense-data-pvc

3. Exposing Typesense

Expose Typesense with a Kubernetes service:

apiVersion: v1
kind: Service
metadata:
  name: typesense-service
  namespace: metrics
spec:
  selector:
    app: typesense
  ports:
    - protocol: TCP
      port: 8108
      targetPort: 8108
  type: NodePort

Next steps

Before using this in production, move the API key into a Kubernetes Secret, choose a storage class that fits your cloud provider, add readiness and liveness probes, and decide whether the service should stay internal or be exposed through an ingress.