Configuración y uso de Typesense en ServBay

Typesense es un motor de búsqueda en memoria, de código abierto, ligero y extremadamente rápido, diseñado para ofrecer una experiencia de “búsqueda mientras escribes” (search-as-you-type) con baja latencia. A menudo se considera una alternativa ligera a Algolia o Elasticsearch. Gracias a ServBay, puedes implementar y gestionar fácilmente una instancia completamente funcional de Typesense en tu entorno local de macOS, dotando a tus aplicaciones de potentes capacidades de búsqueda.

Resumen

ServBay simplifica enormemente el proceso de instalación y configuración de Typesense. Los desarrolladores pueden realizar todos los ajustes necesarios desde la interfaz gráfica de ServBay, sin complicadas operaciones por línea de comandos, y obtener así un servicio local de búsqueda listo para usar.

Para mejorar aún más la experiencia de desarrollo, ServBay configura automáticamente un endpoint seguro y accesible por HTTPS para tu instancia de Typesense: https://typesense.servbay.host/. Esto significa que puedes empezar a hacer llamadas API con ese dominio directamente en tu aplicación, sin preocuparte por el mapeo de puertos ni la gestión de certificados SSL.

Requisitos previos

• Tener ServBay instalado y ejecutándose correctamente en tu sistema macOS.
• Estar desarrollando un proyecto que requiera integrar funcionalidades de búsqueda.
• Disponer de conocimientos básicos sobre motores de búsqueda (por ejemplo, colecciones/índices, documentos, claves API).

Pasos de configuración

1. Instalar el paquete de Typesense

Para empezar, instala el paquete Typesense desde ServBay:

1. Abre la aplicación ServBay.
2. En la barra de navegación izquierda, haz clic en Paquetes (Packages).
3. Busca en la lista de paquetes la sección Búsqueda - Typesense.
4. Haz clic en el botón de instalación a la derecha de Typesense y espera a que finalice el proceso.
5. Activa el servicio de Typesense usando el botón a la derecha.

2. Configurar el servicio Typesense

Tras la instalación, realiza la configuración básica de Typesense:

1. Haz clic en Search en la barra de navegación izquierda de ServBay.

2. Selecciona Typesense en el menú desplegable para acceder a la interfaz de configuración.

   

3. Aparecerán los siguientes parámetros, que puedes modificar según tus necesidades o dejar como por defecto:

   • Bind IP (Dirección IP vinculada): Es la IP donde Typesense escucha. El valor por defecto 127.0.0.1 garantiza que el servicio solo esté accesible desde tu máquina local, siendo la opción más segura en desarrollo local.
   • Port (Puerto): El puerto subyacente del API de Typesense. Por defecto es 8108. Aunque el servicio corre en ese puerto, te recomendamos fuertemente usar el dominio https://typesense.servbay.host que provee ServBay.
   • API Key (Clave API): Clave necesaria para autenticar todas las solicitudes API. Es fundamental para la seguridad de tus datos de búsqueda. No olvides establecer una clave robusta y única, y guárdala en un lugar seguro.
   • Data Path (Ruta de datos): Carpeta local donde Typesense almacena todos los índices y configuraciones. La ruta predeterminada es /Applications/ServBay/data/typesense. Puedes hacer clic en el icono de carpeta a la derecha para abrirlo rápidamente en Finder.

3. Guardar la configuración e iniciar el servicio

1. Tras finalizar la configuración, haz clic en Guardar (Save) en la esquina inferior derecha.
2. Luego, ve a la lista de Paquetes (Packages), localiza Typesense y activa el servicio usando el interruptor correspondiente.
3. Si todo está correcto, el indicador de estado cambiará a verde, señalando que Typesense está activo y en funcionamiento.

4. Integrar Typesense en tu aplicación

Tu aplicación (por ejemplo, JavaScript, PHP, Python, Go, etc.) puede conectarse a la instancia de Typesense en ServBay utilizando cualquier librería oficial o comunitaria disponible.

Al conectarte, usa la siguiente información de endpoint proporcionada por ServBay:

• Host/Nodo: typesense.servbay.host
• Puerto: 443 (puerto estándar para HTTPS)
• Protocolo: https
• Clave API: La API Key configurada en el paso 2

Ejemplo de código en JavaScript (utilizando el cliente typesense-js)

Primero, instala el cliente JavaScript de Typesense en tu proyecto:

npm install typesense
# O bien
yarn add typesense

Luego, inicializa el cliente e interactúa con tu instancia en el código:

import Typesense from 'typesense'

// Inicializa el cliente de Typesense
// Observa que usamos el dominio personalizado y seguro proporcionado por ServBay
const client = new Typesense.Client({
  nodes: [{
    host: 'typesense.servbay.host',
    port: 443,
    protocol: 'https'
  }],
  apiKey: 'YOUR-SUPER-STRONG-API-KEY', // Reemplaza con la API Key que configuraste en ServBay
  connectionTimeoutSeconds: 2
})

// Ejemplo: Crear una colección llamada '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 {
    // Crear la colección
    await client.collections().create(bookSchema);
    console.log("Collection 'books' created successfully.");

    // Agregar un documento de libro
    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.");

    // Realizar una búsqueda
    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();

Preguntas frecuentes (FAQ)

• P: Olvidé mi API Key, ¿cómo la restablezco?
  • R: Es muy sencillo restablecerla en ServBay. Solo tienes que introducir una nueva clave en el campo API Key de la interfaz de configuración de Typesense (Search -> Typesense), hacer clic en Guardar (Save) y reiniciar el servicio Typesense.
• P: El servicio Typesense no inicia, ¿qué puedo hacer?
  • R: Revisa lo siguiente:
    1. Haz clic en el icono de registro en la parte superior derecha de la configuración de Typesense para ver los mensajes de error detallados, lo que suele dar pistas directas sobre el fallo.
    2. Comprueba que el puerto local 8108 no esté ya en uso por otra aplicación.
    3. Verifica que el directorio especificado en Data Path existe y que ServBay tiene permisos de lectura y escritura sobre él.
• P: ¿Puedo acceder al API directamente desde http://127.0.0.1:8108?
  • R: Sí, el puerto estará disponible localmente. Sin embargo, te recomendamos encarecidamente conectar a través de https://typesense.servbay.host/, ya que así disfrutarás de cifrado HTTPS sin necesidad de configuraciones extra, acercándote mucho a un escenario de producción y con mayor seguridad.

Resumen

ServBay integra el potente motor de búsqueda Typesense en tu flujo de trabajo local de desarrollo en macOS de forma fluida. Gracias a su configuración gráfica simplificada y a su endpoint seguro por defecto en HTTPS, puedes enfocarte en construir las mejores experiencias de búsqueda para tus usuarios, dejando atrás la complejidad y el mantenimiento del entorno subyacente.