Configuring and Using the Typesense Search Engine in ServBay

Typesense is an open-source, lightweight, and lightning-fast in-memory search engine designed for low-latency, search-as-you-type experiences. It's often seen as a lighter alternative to Algolia or Elasticsearch. With ServBay, you can effortlessly deploy and manage a fully functional Typesense instance in your local macOS environment, powering your applications with robust search capabilities.

Overview

ServBay greatly simplifies the process of installing and configuring Typesense. Developers can complete all setup tasks through ServBay’s graphical interface, with no need for complex command-line operations, and get a ready-to-use local search service out of the box.

To further improve the developer experience, ServBay automatically configures a secure, easy-to-access HTTPS API endpoint for your Typesense instance: https://typesense.servbay.host/. This means you don’t have to worry about port mapping or SSL certificate setup—just use this domain to make API calls directly from your application.

Prerequisites

• ServBay is successfully installed and running on your macOS system.
• You’re working on a project that requires integrated search functionality.
• You have a basic understanding of search engine concepts (such as collections/indexes, documents, API keys).

Steps

1. Install the Typesense Package

First, install the Typesense package through ServBay:

1. Launch the ServBay application.
2. Click Packages in the left sidebar.
3. Find Search – Typesense in the list of packages.
4. Click the install button to the right of Typesense and wait for the installation to complete.
5. Toggle the switch to enable the Typesense service.

2. Configure the Typesense Service

Once installed, you’ll need to set up some basic configurations:

1. Click Search in the left sidebar of ServBay.

2. Choose Typesense from the dropdown, entering its configuration screen.

   

3. You'll see the following configuration options, which you can adjust or leave as default:

   • Bind IP: The IP address the Typesense service will listen on. The default 127.0.0.1 limits access to your machine only, which is the safest setting for local development.
   • Port: The internal API port for Typesense (default: 8108). Though the service runs on this port, we highly recommend using the ServBay-provided domain https://typesense.servbay.host for access.
   • API Key: The key required to authenticate all API requests. This is critical for securing your search data. Be sure to set a strong, unique key and keep it safe.
   • Data Path: The local directory where Typesense stores all index data and configuration. Default is /Applications/ServBay/data/typesense. You can quickly locate this folder in Finder by clicking the folder icon on the right.

3. Save Configuration and Start the Service

1. After configuring, click the Save button in the bottom right corner.
2. Go back to the Packages list, find Typesense, and use the toggle to start the service.
3. If configured correctly, the service status light will turn green, indicating that Typesense is up and running.

4. Integrate Typesense into Your Application

Your application (JavaScript, PHP, Python, Go, etc.) can connect to the Typesense instance running in ServBay via any official or community Typesense client library.

When connecting, use the dedicated endpoint provided by ServBay:

• Host/Node: typesense.servbay.host
• Port: 443 (standard HTTPS port)
• Protocol: https
• API Key: The API key you set in Step 2

JavaScript Code Example (Using typesense-js Client)

First, install the Typesense JavaScript client in your project:

npm install typesense
# or
yarn add typesense

Next, initialize the client and interact with the API:

import Typesense from 'typesense'

// Initialize Typesense client
// Note: we're using the dedicated, secure domain provided by ServBay
const client = new Typesense.Client({
  nodes: [{
    host: 'typesense.servbay.host',
    port: 443,
    protocol: 'https'
  }],
  apiKey: 'YOUR-SUPER-STRONG-API-KEY', // Replace with your API Key configured in ServBay
  connectionTimeoutSeconds: 2
})

// Example: Create a collection called 'books'
const bookSchema = {
  name: 'books',
  fields: [
    { name: 'title', type: 'string' },
    { name: 'author', type: 'string', facet: true },
    { name: 'publication_year', type: 'int32', facet: true }
  ],
  default_sorting_field: 'publication_year'
}

async function setupTypesense() {
  try {
    // Create collection
    await client.collections().create(bookSchema);
    console.log("Collection 'books' created successfully.");

    // Add a book document
    const bookDocument = {
      'title': 'The Hitchhiker\'s Guide to the Galaxy',
      'author': 'Douglas Adams',
      'publication_year': 1979
    };
    await client.collections('books').documents().create(bookDocument);
    console.log("Document added successfully.");

    // Perform a search
    const searchParameters = {
      'q': 'hitchhiker',
      'query_by': 'title',
      'sort_by': 'publication_year:desc'
    };
    const searchResults = await client.collections('books').documents().search(searchParameters);
    console.log('Search Results:', searchResults);

  } catch (error) {
    console.error('Typesense Error:', error);
  }
}

setupTypesense();

Frequently Asked Questions (FAQ)

• Q: I forgot my API Key. How can I reset it?
  • A: Resetting the API key in ServBay is simple. Go to the Typesense configuration screen (Search -> Typesense), enter a new value in the API Key field, click Save, and then restart the Typesense service.
• Q: Typesense service fails to start. What should I do?
  • A: Check the following:
    1. Click the log icon in the top-right corner of the Typesense configuration screen to view error details—this usually provides the most direct clues.
    2. Ensure that port 8108 on your machine is not occupied by another application.
    3. Verify that the specified Data Path exists and that ServBay has read/write permissions to it.
• Q: Can I access the API directly via http://127.0.0.1:8108?
  • A: Yes, this local port is accessible. However, we strongly recommend using https://typesense.servbay.host/ for connections, as it provides encrypted HTTPS access without extra setup, closely reflecting production environments for added security.

Summary

ServBay seamlessly integrates the powerful Typesense search engine into your local macOS development workflow. With simplified graphical configuration and preset secure HTTPS endpoints, you can focus on crafting excellent search experiences—instead of spending time on complex environment setup and maintenance.