How to Install and Run Typesense with Docker and Connect It to Hudu

This guide will walk you through setting up a self-hosted Typesense instance using Docker and integrating it with Hudu for lightning-fast search capabilities. If you are running self-hosted Hudu, you can add Typesense alongside your Hudu deployment in the same Docker Compose stack or run it on a separate server. If you are on Hosted Hudu (Hudu Cloud), you’ll need to connect to a Typesense server running separately, though you may also choose to use the fully managed Typesense Cloud service if you prefer not to host it yourself.

Self-Hosted Hudu Prerequisites

• Hudu running in Docker
• Docker Compose installed
• Hudu version 2.39.0
• Access to your Hudu installation folder (~/hudu2)
• A text editor for updating docker-compose.yml and .env

Note: With self-hosted Hudu, you have two deployment options for Typesense:

• Alongside your Hudu stack by adding it to your existing docker-compose.yml file (as shown below).

• On a separate server (VM, container host, or Kubernetes cluster). In that case, you’ll configure Hudu to point to the external Typesense endpoint instead of http://typesense:8108.

Add API Key to .env File

• Edit the .env file in the same directory.

• Create and add an API key (no default key is provided):

  TYPESENSE_API_KEY=your-secure-api-key

Add Typesense Service to Docker Compose

• Navigate to your Hudu installation directory:
  cd ~/hudu2
• Open your docker-compose.yml file.

• Add the following service block to the bottom of your .yml file. 

  • This guide was written for Typesense v29.x. If installing at a later date, review the official Typesense release notes to determine the appropriate version to deploy.
  • Do not replace ${TYPESENSE_API_KEY} with your actual key. The value will be loaded from your .env file.

  typesense:
    image: typesense/typesense:29.0
    restart: on-failure
    environment:
      TYPESENSE_API_KEY: ${TYPESENSE_API_KEY}
    volumes:
      - ./typesense-data:/data
    command: '--data-dir /data --enable-cors'
  

• If Typesense is running on a different host or outside the same Docker network as Hudu (for example, when your Hudu environment is cloud-hosted or you are using a separate server deployment), you must define the port mapping in your docker-compose.yml file:

ports:
  - "8108:8108"

Restart Docker Containers

• Stop your Docker containers:
  docker compose down
• Pull the latest images:
  docker compose pull
• Bring them back up:
  docker compose up -d

Hosted Hudu Prerequisites

If you are running Hudu Cloud (hosted by Hudu) and want to integrate with Typesense, keep the following prerequisites in mind:

• Hudu version 2.39.0
• A Reachable Typesense Instance

  • You must provide an external Typesense endpoint that Hudu Cloud can access over the internet.

  • This can be either:

    • Typesense Cloud (managed) – simplest option, no infrastructure to maintain.

    • Self-hosted Typesense – deployed on your own server, VM, or container platform, with HTTPS enabled.

Note: If you are self-hosting Typesense while on Hudu Cloud, it must run on a separate server that is reachable over HTTPS. Unlike self-hosted Hudu, you cannot attach Typesense directly to Hudu’s Docker stack in the cloud environment.
 

Deploy Typesense with Docker Compose (HTTPS-ready)

• Create a persistent data folder - From the directory where you’ll keep your Compose file, create a data dir that will be mounted into the container. The official Typesense guide shows this step explicitly.

  mkdir "$(pwd)"/typesense-data
  

• Create docker-compose.yml

  • This example runs a single Typesense node and prepares it to sit behind a reverse proxy (for HTTPS). The API key you set here is the admin key—use it only server-side and generate scoped keys for clients later. (See Server Configuration → API keys.)

  • version: "3.9"
    
    services:
      typesense:
        image: typesense/typesense:29.0
        container_name: typesense
        restart: unless-stopped
        command:
          - "--data-dir=/data"
          - "--api-key=${TYPESENSE_API_KEY}"
          - "--api-address=0.0.0.0"
          - "--api-port=8108"
          # If you terminate TLS at a proxy, you do NOT need --ssl-* here.
          # To enable CORS for browser-based clients (optional):
          # - "--enable-cors"
          # - "--cors-domains=https://yourapp.example"
        volumes:
          - ./typesense-data:/data
        ports:
          - "8108:8108"  # keep internal; expose HTTPS via a reverse proxy
        environment:
          # Alternatively you can pass env vars instead of command flags
          # TYPESENSE_DATA_DIR: /data
          # TYPESENSE_API_KEY: set via .env
          TZ: UTC
    

Tip: You can configure these same parameters as CLI flags (shown above), via a config file, or via environment variables—the Typesense docs cover all three.

• Bring it up
  • Run Compose from the same directory. The official guide’s quickstart shows running docker compose up after creating the data dir.

  • docker compose up -d
    # (or: docker-compose up -d on older Compose versions)

• Add HTTPS with a reverse proxy (recommended)
  • Typesense can serve HTTPS directly if you provide cert/key paths as server flags, but in most deployments you’ll terminate TLS at a reverse proxy (Caddy / Nginx / Traefik) and keep Typesense on plain HTTP internally. The “SSL / HTTPS” section outlines direct TLS flags if you prefer that route.
• Health check and version

• Once HTTPS is set up (or even before, on HTTP), verify the server is ready:

  • GET /health should return “OK” when ready.

  • GET /debug shows the running version. (Both endpoints are noted in the install guide.)

• Next steps: keys and hardening

  • Create scoped API keys for apps / integrations (don’t expose your admin key). See Typesense Guide for more information.

Enable Typesense in Hudu

• In Hudu, navigate to Admin > Integrations.
• Select the Typesense integration.
• Enter:
  • API Key: The same key you placed in .env
  • Host Path: http://typesense:8108

    • If you run Typesense alongside Hudu in Docker, use the internal service name (e.g., http://typesense:8108).

    • If you run Typesense on a separate server, replace this with your external HTTPS URL (e.g., https://typesense.yourdomain.com).

• Save the integration settings.

Once saved, Hudu will automatically test the connection to Typesense. If the connection is successful, it will immediately begin reindexing your data to improve search performance.

Verify the Integration

• Perform a search in Hudu to confirm results are powered by Typesense.
• Check the Typesense integration logs if there are issues.

Additional Resources

For more details, check out:

• Typesense Installation Guide – Official documentation on installing Typesense

• Hudu Typesense Integration Guide – Steps for integrating with Hudu 

• System Requirements for Typesense – Hardware and software prerequisites

• Synonyms – Official Typesense documentation on Synonyms

Export the Typesense API key

Exporting the API key saves it as an environment variable in your current shell session. This lets you reference it in commands (e.g., $TYPESENSE_API_KEY) instead of hard-coding the actual key each time. It’s both more convenient and more secure, since your real key won’t appear in your command history or shared examples.

Use the same admin key you set in .env as TYPESENSE_API_KEY. Export it once per shell session:

export TYPESENSE_API_KEY='your-real-admin-key'

Quick health check:

curl -sS -H "X-TYPESENSE-API-KEY: $TYPESENSE_API_KEY" http://localhost:8108/health

List Hudu collections

These are the common Hudu collections in Typesense:

• articles
• assets
• procedures
• websites
• asset_passwords
• companies

To confirm on your system:

curl -sS -H "X-TYPESENSE-API-KEY: $TYPESENSE_API_KEY" \
  "http://localhost:8108/collections"

Create or update synonyms (per collection)

Multi-way (all terms are equivalent):

curl -sS -X PUT \
  "http://localhost:8108/collections/articles/synonyms/colors" \
  -H "X-TYPESENSE-API-KEY: $TYPESENSE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"synonyms":["red","scarlet","crimson"]}'

One-way (many → one root term):

curl -sS -X PUT \
  "http://localhost:8108/collections/articles/synonyms/smartphone" \
  -H "X-TYPESENSE-API-KEY: $TYPESENSE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"root":"smartphone","synonyms":["iphone","android"]}'

Verify a synonym

curl -sS -H "X-TYPESENSE-API-KEY: $TYPESENSE_API_KEY" \
  "http://localhost:8108/collections/articles/synonyms/colors"

List or delete synonyms

# List all synonyms on a collection
curl -sS -H "X-TYPESENSE-API-KEY: $TYPESENSE_API_KEY" \
  "http://localhost:8108/collections/articles/synonyms"

# Delete a synonym by ID
curl -sS -X DELETE -H "X-TYPESENSE-API-KEY: $TYPESENSE_API_KEY" \
  "http://localhost:8108/collections/articles/synonyms/colors"

Notes

• Synonyms are per-collection and affect the search query (q) only.
• Replace articles with the target collection name from your Hudu list above.
• For common words (like red), exact matches may rank above synonym-expanded hits; use a Typesense Override if you need to pin a specific result.