Configurer et utiliser le moteur de recherche Typesense avec ServBay

Typesense est un moteur de recherche open source léger et ultra-rapide en mémoire, conçu pour offrir une expérience « search-as-you-type » à très faible latence. Il est souvent considéré comme une alternative plus légère à Algolia ou Elasticsearch. Grâce à ServBay, vous pouvez facilement déployer et gérer une instance Typesense complète sur votre environnement macOS local, et ainsi ajouter une fonctionnalité de recherche puissante à vos applications.

Présentation

ServBay simplifie grandement le processus d’installation et de configuration de Typesense. Les développeurs peuvent tout configurer via l’interface graphique de ServBay, sans passer par des commandes complexes en ligne de commande, et profiter ainsi d’un service de recherche local prêt à l’emploi.

Pour améliorer encore l’expérience de développement, ServBay configure automatiquement pour votre instance Typesense un point d’accès HTTPS sécurisé et facile à utiliser : https://typesense.servbay.host/. Ainsi, vous n’avez pas à vous préoccuper du mappage de ports ou des certificats SSL : il vous suffit d’utiliser ce nom de domaine dans vos applications pour effectuer vos appels API.

Prérequis

• ServBay doit être installé et en cours d’exécution sur votre système macOS.
• Vous développez un projet nécessitant une fonction de recherche intégrée.
• Vous avez une connaissance de base des principaux concepts des moteurs de recherche (tels que collection/index, document, clé API).

Étapes d’utilisation

1. Installer le package Typesense

Pour commencer, installez Typesense via ServBay :

1. Ouvrez l’application ServBay.
2. Dans la barre latérale gauche, cliquez sur Packages (Packages).
3. Dans la liste des packages, trouvez Recherche – Typesense.
4. Cliquez sur le bouton d’installation à droite de Typesense et patientez jusqu’à la fin du processus.
5. Activez le service Typesense en cliquant sur le bouton correspondant à droite.

2. Configurer le service Typesense

Après l’installation, effectuez la configuration de base de Typesense :

1. Dans la barre latérale de gauche de ServBay, cliquez sur Search.

2. Dans le menu déroulant, sélectionnez Typesense pour accéder à l’interface de configuration.

   

3. Vous verrez les paramètres suivants, que vous pouvez modifier selon vos besoins ou laisser par défaut :

   • Bind IP (Adresse IP d’écoute) : Adresse IP sur laquelle Typesense écoute. La valeur par défaut 127.0.0.1 limite l’accès au service à la machine locale — c’est l’option la plus sûre pour le développement local.
   • Port : Port de communication de l’API Typesense. La valeur par défaut est 8108. Même si le service s’exécute sur ce port, nous recommandons fortement d’utiliser le domaine fourni par ServBay, https://typesense.servbay.host, pour accéder à l’API.
   • API Key (Clé API) : Clé servant à authentifier tous les appels API. Ceci est essentiel pour la sécurité de vos données de recherche. Veillez à définir une clé sûre et unique, puis à bien la conserver.
   • Data Path (Chemin des données) : Chemin local où Typesense stocke toutes les données d’index et configurations. Par défaut : /Applications/ServBay/data/typesense. Cliquez sur l’icône de dossier pour ouvrir rapidement ce répertoire dans Finder.

3. Sauvegarder la configuration et démarrer le service

1. Une fois la configuration terminée, cliquez sur le bouton Save (Enregistrer) en bas à droite.
2. Ensuite, retournez à la liste Packages et activez le service Typesense en basculant son interrupteur à droite.
3. Si la configuration est correcte, l’indicateur d’état du service passe au vert, signe que Typesense fonctionne avec succès.

4. Intégrer Typesense dans votre application

Votre application (en JavaScript, PHP, Python, Go, etc.) peut se connecter à votre instance Typesense installée avec ServBay, en utilisant l’un des clients officiels ou communautaires.

Lors de la connexion, utilisez les informations de point d’accès fournies par ServBay :

• Host/Node (Serveur/Nœud) : typesense.servbay.host
• Port : 443 (port standard HTTPS)
• Protocol (Protocole) : https
• API Key (Clé API) : La clé API que vous avez définie à l’étape 2

Exemple de code JavaScript (client typesense-js)

Installez d’abord le client JavaScript de Typesense dans votre projet :

npm install typesense
# ou
yarn add typesense

Puis, initialisez et utilisez le client comme suit :

import Typesense from 'typesense'

// Initialisation du client Typesense
// On utilise le domaine sécurisé fourni par ServBay
const client = new Typesense.Client({
  nodes: [{
    host: 'typesense.servbay.host',
    port: 443,
    protocol: 'https'
  }],
  apiKey: 'YOUR-SUPER-STRONG-API-KEY', // Remplacez par la clé API définie dans ServBay
  connectionTimeoutSeconds: 2
})

// Exemple : création d’une collection appelée '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 {
    // Création de la collection
    await client.collections().create(bookSchema);
    console.log("La collection 'books' a été créée avec succès.");

    // Ajout d’un document livre
    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 ajouté avec succès.");

    // Exécution d’une recherche
    const searchParameters = {
      'q': 'hitchhiker',
      'query_by': 'title',
      'sort_by': 'publication_year:desc'
    };
    const searchResults = await client.collections('books').documents().search(searchParameters);
    console.log('Résultats de la recherche :', searchResults);

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

setupTypesense();

Foire aux questions (FAQ)

• Q : J’ai oublié ma clé API, comment la réinitialiser ?
  • R : Réinitialiser la clé via ServBay est très simple. Il suffit de saisir une nouvelle clé dans le champ API Key de l’interface de configuration de Typesense (Search -> Typesense), puis de cliquer sur Save (Enregistrer) et enfin de redémarrer le service Typesense.
• Q : Le service Typesense ne démarre pas, que faire ?
  • R : Veuillez vérifier les points suivants :
    1. Cliquez sur l’icône journal en haut à droite de l’interface de configuration Typesense et consultez les messages d’erreur pour diagnostiquer le problème.
    2. Vérifiez que le port local 8108 n’est pas déjà utilisé par une autre application.
    3. Contrôlez que le répertoire spécifié dans Data Path existe bien et que ServBay dispose des droits de lecture/écriture nécessaires.
• Q : Puis-je accéder à l’API directement via http://127.0.0.1:8108 ?
  • R : Oui, ce port est accessible localement. Mais il est fortement recommandé d’utiliser plutôt https://typesense.servbay.host/ car ce domaine permet une connexion chiffrée en HTTPS sans configuration supplémentaire : cela se rapproche plus d’un environnement de production et renforce la sécurité.

Conclusion

ServBay intègre de façon transparente le puissant moteur de recherche Typesense dans votre flux de travail de développement macOS local. Grâce à sa configuration graphique simplifiée et à son point d’accès HTTPS sécurisé par défaut, vous pouvez vous concentrer sur la création d’expériences de recherche exceptionnelles au lieu de perdre du temps sur la configuration et la maintenance de votre environnement.