Skip to content
Klutch.sh Docs

Deploying a Typesense App

Introduction

Typesense is an open-source search engine optimized for instant, typo-tolerant search. This guide shows how to containerize Typesense with a Dockerfile, persist its data, secure the API key, and deploy it to Klutch.sh using TCP traffic.

Prerequisites

  • GitHub repository containing your Dockerfile.
  • Klutch.sh project ready in klutch.sh/app.

Project structure

.
└── Dockerfile

Sample Dockerfile

FROM typesense/typesense:latest


# Default Typesense port
ENV TYPESENSE_LISTEN_PORT=8108
EXPOSE 8108

Required environment variables

  • TYPESENSE_API_KEY – strong admin API key for read/write operations.
  • TYPESENSE_DATA_DIR=/data – where Typesense stores data.
  • TYPESENSE_LISTEN_PORT=8108 – internal port (default).
  • TYPESENSE_ENABLE_CORS=true – enable CORS if you serve from browsers.

Optional environment variables

  • TYPESENSE_PEERING_KEY – if clustering.
  • TYPESENSE_DEFAULT_NUM_MEMORY_MAPPED_PAGES – tune memory-mapped pages.
  • TYPESENSE_LOG_LEVEL – e.g., info or warn.

Persistence

Attach a persistent volume for indexes and snapshots:

  • Mount path: /data
  • Size: based on index size and replication snapshots

Networking

  • Protocol: TCP
  • Internal port: 8108
  • Clients connect to your TCP endpoint (e.g., example-app.klutch.sh:8000) while Klutch.sh routes to 8108 inside the container.
Terminal window
curl -X GET "http://localhost:8108/health"

Deployment on Klutch.sh

  1. Push your Dockerfile to GitHub.
  2. In klutch.sh/app, create a new app and select GitHub as the source.
  3. Klutch.sh automatically detects the Dockerfile in the repository root.
  4. Select TCP traffic and set the internal port to 8108.
  5. Add environment variables for TYPESENSE_API_KEY, TYPESENSE_DATA_DIR, and any tuning options. Mark sensitive values as secrets.
  6. Attach a persistent volume at /data sized for your search indexes.
  7. Deploy. Connect your apps to example-app.klutch.sh:8000 with the API key in the X-TYPESENSE-API-KEY header.

Verification

  • Health:

    Terminal window
    curl "http://example-app.klutch.sh:8000/health"

  • Create a sample collection:

    Terminal window
    curl -X POST "http://example-app.klutch.sh:8000/collections" \
      -H "X-TYPESENSE-API-KEY: $TYPESENSE_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{"name":"products","fields":[{"name":"title","type":"string"}]}'

Next steps

  • Add read-only keys for client-side search.
  • Configure snapshots and backups from the mounted /data path.
  • Tune memory mapping and replication if you scale out.