Налаштування та використання пошукової системи Typesense у ServBay

Typesense — це сучасний, легкий і надзвичайно швидкий пошуковий рушій із відкритим кодом, створений для забезпечення миттєвого пошуку з низькою затримкою (search-as-you-type). Його часто рекомендують як легку альтернативу Algolia або Elasticsearch. За допомогою ServBay ви легко можете розгорнути та керувати повноцінним інстансом Typesense на macOS для локальної розробки, щоб додати потужний пошук до своїх застосунків.

Огляд

ServBay максимально спрощує процес встановлення й налаштування Typesense. Для розробників немає потреби у складних командних інструкціях — усі налаштування виконуються через графічний інтерфейс ServBay, і ви миттєво отримуєте готовий до роботи локальний пошуковий сервіс.

Щоб полегшити розробку ще більше, ServBay автоматично налаштовує для вас захищений та зручний HTTPS API-ендпоінт: https://typesense.servbay.host/. Тепер не потрібно турбуватися про проброс портів чи генерування SSL-сертифікатів — ви можете безпечно використовувати цей домен напряму зі свого коду.

Передумови

• На вашому Mac вже встановлено й запущено ServBay.
• Ви розробляєте проєкт, якому потрібна інтеграція з пошуком.
• Ви маєте базові знання про пошукові рушії (наприклад, колекції/індекси (Collection), документи (Document), API ключі).

Покрокова інструкція

1. Встановлення пакета Typesense

Для початку потрібно додати пакет Typesense до ServBay:

1. Відкрийте застосунок ServBay.
2. У лівій панелі оберіть Пакети (Packages).
3. Знайдіть у переліку пакетів розділ Пошук — Typesense.
4. Натисніть кнопку встановлення навпроти Typesense і зачекайте, доки інсталяція завершиться.
5. Після встановлення активуйте сервіс Typesense праворуч.

2. Налаштування сервісу Typesense

Після встановлення проведіть базову конфігурацію Typesense:

1. У лівій панелі ServBay перейдіть до розділу Search.

2. У випадаючому меню виберіть Typesense для переходу на сторінку налаштувань.

   

3. Ви побачите такі конфігураційні поля, які можна змінити або залишити за замовчуванням:

   • Bind IP (Прив’язка IP): IP-адреса, на якій слухає Typesense. За замовчуванням 127.0.0.1 — це гарантує, що сервіс доступний лише на вашому Mac, що є найкращою практикою для локальної розробки.
   • Port (Порт): Базовий порт API Typesense. Стандартно — 8108. Хоча інстанс працює на цьому порту, настійно рекомендується підключатися через домен ServBay https://typesense.servbay.host.
   • API Key (API-ключ): Ключ для автентифікації всіх API-запитів. Це критично важливо для безпеки ваших пошукових даних! Обов’язково задайте сильний унікальний ключ і збережіть його в безпеці.
   • Data Path (Шлях до даних): Локальний шлях зберігання індексів і файлів конфігурації Typesense. За замовчуванням — /Applications/ServBay/data/typesense. Ви можете натиснути іконку папки праворуч для швидкого відкриття цієї директорії у Finder.

3. Збереження конфігурації та запуск сервісу

1. Перевіривши та змінивши налаштування за потреби, натисніть кнопку Save (Зберегти) внизу праворуч.
2. Далі перейдіть до розділу Пакети (Packages), знайдіть Typesense та увімкніть його перемикачем справа.
3. Якщо все налаштовано правильно, індикатор статусу зміниться на зелений — це означає, що Typesense успішно запущено.

4. Інтеграція Typesense у ваш застосунок

Ваш застосунок (написаний на JavaScript, PHP, Python, Go чи іншій мові) може підключатися до Typesense у ServBay через офіційні чи спільнотні клієнтські бібліотеки.

Використовуйте такі параметри для підключення:

• Host/Node (Хост/Вузол): typesense.servbay.host
• Port (Порт): 443 (стандартний порт HTTPS)
• Protocol (Протокол): https
• API Key (API-ключ): той, що ви вказали на кроці 2

Приклад коду для JavaScript (з клієнтом typesense-js)

Спершу встановіть бібліотеку Typesense для JavaScript у ваш проект:

npm install typesense
# або
yarn add typesense

Далі ініціалізуйте клієнт і взаємодійте з Typesense у коді:

import Typesense from 'typesense'

// Ініціалізація клієнта Typesense
// Зверніть увагу: тут використовується захищений домен ServBay
const client = new Typesense.Client({
  nodes: [{
    host: 'typesense.servbay.host',
    port: 443,
    protocol: 'https'
  }],
  apiKey: 'YOUR-SUPER-STRONG-API-KEY', // Замініть на ваш API-ключ, встановлений у ServBay
  connectionTimeoutSeconds: 2
})

// Приклад: створення колекції '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 {
    // Створити колекцію
    await client.collections().create(bookSchema);
    console.log("Collection 'books' створено успішно.");

    // Додати документ книги
    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("Документ додано успішно.");

    // Виконати пошук
    const searchParameters = {
      'q': 'hitchhiker',
      'query_by': 'title',
      'sort_by': 'publication_year:desc'
    };
    const searchResults = await client.collections('books').documents().search(searchParameters);
    console.log('Результати пошуку:', searchResults);

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

setupTypesense();

Часті питання (FAQ)

• Q: Забув API-ключ. Як його скинути?
  • A: У ServBay це дуже просто. Перейдіть у налаштування Typesense (Search -> Typesense), введіть новий ключ у полі API Key, натисніть Save (Зберегти) і перезапустіть сервіс Typesense.
• Q: Не вдається запустити сервіс Typesense. Що робити?
  • A: Перевірте наступне:
    1. Натисніть іконку журналу у верхньому правому куті інтерфейсу налаштувань Typesense — тут ви знайдете журнал помилок із причинами збою.
    2. Переконайтеся, що порт 8108 на вашому Mac не зайнятий іншими застосунками.
    3. Перевірте, чи існує каталог Data Path і чи має ServBay права на читання/запис у ньому.
• Q: Чи можу я звертатися до API напряму через http://127.0.0.1:8108?
  • A: Можна, цей порт доступний локально. Однак наполегливо рекомендуємо підключатися через https://typesense.servbay.host/ — це забезпечує шифрування HTTPS "з коробки" та є надійною практикою, наближеною до бойового середовища.

Висновок

ServBay органічно інтегрує потужний пошуковий рушій Typesense у ваш робочий процес на macOS. Завдяки спрощеній графічній конфігурації та попередньо налаштованому захищеному HTTPS-ендпоінту, ви можете сконцентруватись на створенні ідеального пошукового досвіду, а не витрачати час на ненудні налаштування інфраструктури.