Introducción
Meilisearch es un motor de búsqueda de código abierto y autónomo escrito en el lenguaje de programación Rust. En comparación con otros motores de búsqueda populares, las implementaciones de Meilisearch requieren muy pocos pasos, y puedes ejecutar un servidor Meilisearch y consultarla utilizando un único binario de línea de comandos. Meilisearch tiene características como coincidencia difusa e indexación sin esquema e incluye una interfaz web para propósitos de demostración. Las implementaciones más complejas admiten la integración con la biblioteca de javascript InstantSearch.
En este tutorial, primero ejecutarás Meilisearch en un servidor Ubuntu 22.04 usando Docker para experimentar con él. Lo poblarás con datos de muestra y lo consultarás tanto desde la línea de comandos como desde la interfaz web incorporada. También explorarás cómo cambiar la ponderación de la búsqueda y otros detalles de configuración. Luego, utilizarás docker compose para configurar un servicio de Meilisearch listo para producción que almacena datos persistentes y se reinicia automáticamente con tu servidor
Prerrequisitos
Para seguir este tutorial, necesitarás:
-
Un servidor Ubuntu 22.04 configurado siguiendo la guía de configuración inicial del servidor Ubuntu 22.04, incluyendo un usuario sudo no root y un firewall.
-
Docker y Docker-compose instalados siguiendo Cómo instalar y usar Docker en Ubuntu 22.04 y el primer paso de Cómo instalar y usar Docker-Compose en Ubuntu 22.04
Paso 1 — Instalación de Meilisearch y Carga de Datos de Muestra
Meilisearch proporciona paquetes de instalación para muchos entornos. Debido a que está en desarrollo activo, y su estructura de datos interna aún está siendo actualizada, es una buena idea instalar Meilisearch a través de Docker. De esta manera, puedes fijar una configuración específica de Meilisearch para tu sistema y actualizarla de forma elegante según sea necesario.
Comience por extraer la última imagen de Meilisearch (0.26.1 en el momento de escribir esto) de Docker Hub:
Ahora puede iniciar la imagen de Meilisearch en Docker proporcionando algunos parámetros a docker run:
Este comando se puede desglosar de la siguiente manera:
docker run –rmutiliza la bandera--rmpara asegurar que el contenedor se limpie después de salir.-p 127.0.0.1:7700:7700redirige el tráfico en la interfaz localhost de su servidor en el puerto 7700 al puerto predeterminado7700de Meilisearch dentro del contenedor Docker, para que pueda acceder a él como de costumbre.127.0.0.1es sinónimo delocalhostal usar direcciones IPv4.getmeili/meilisearch:v0.26.1ejecuta la imagen que acaba de descargar.
Cuando ejecuta Meilisearch, generará automáticamente algunos detalles de configuración y los incluirá en la salida. Tenga en cuenta que el directorio de índices de Meilisearch ./data.ms se ha generado automáticamente dentro del contenedor. Cambiará la ubicación más adelante en este tutorial. También tenga en cuenta que Meilisearch por defecto se ejecuta en un entorno de configuración development en lugar de production.
…
[secondary_label Output]
Database path: "./data.ms"
Server listening on: "http://0.0.0.0:7700"
Environment: "development"
Commit SHA: "unknown"
Commit date: "unknown"
Package version: "0.26.1"
…
Ahora tiene una instancia de Meilisearch en funcionamiento sin datos. Necesitará cargar algunos datos de ejemplo para empezar a trabajar con Meilisearch. El proceso meilisearch bloqueará la terminal en la que se inició mientras esté en ejecución, así que también querrá abrir una conexión separada a su servidor para continuar ejecutando otros comandos.
El proyecto Meilisearch proporciona un conjunto de datos de muestra en formato JSON extraído de TMDB, The Movie Database. Descargue los datos desde docs.meilisearch.com utilizando el comando wget:
Puede ejecutar tail para ver un fragmento del contenido de este archivo:
Output…
{"id":"289239","title":"Mostly Ghostly: Have You Met My Ghoulfriend?","poster":"https://image.tmdb.org/t/p/w500/eiVY4kKpbo1f7wyNubgJX5ILpxg.jpg","overview":"Bella Thorne, Madison Pettis and Ryan Ochoa lead an ensemble cast in this spook-tacular adventure with new ghosts, new thrills, and the return of some old friends. Max (Ochoa) only has eyes for Cammy (Thorne), the smart, popular redhead at school. When Max finally scores a date with Cammy on Halloween, Phears, an evil ghost with plans on taking over the world, unleashes his ghouls and things go haywire. With the help of his ghostly pals, Tara and Nicky, can Max thwart Phears' evil plot, help reunite his ghost friends with their long-lost parents and still make his date with Cammy on Halloween? R.L. Stine's Mostly Ghostly: Have You Met My Ghoulfriend? is a frightful family delight!","release_date":1409619600,"genres":["Family","Fantasy","Horror"]},
{"id":"423189","title":"Right Here Right Now","poster":"https://image.tmdb.org/t/p/w500/sCo1excKlzhKas681CTSe1ujcOa.jpg","overview":"Hamburg, St. Pauli, New Year's Eve. Oskar Wrobel runs a music club in an old hospital at the edge of the Reeperbahn. While fireworks go off in the streets of St. Pauli, he prepares the big final party - the club has to close. Thankfully there is no time to think about it because the chaos is breaking into his living room, all while hell break loose at the club. The film, based on the novel by Tino Hanekamp, was filmed with hundreds of extras attending a real-life three-night-long party.","release_date":1530579600,"genres":["Documentary","Music"]},
{"id":"550315","title":"Fireman Sam - Set for Action!","poster":"https://image.tmdb.org/t/p/w500/2atmRsuSA4tX6sbOEgFzquFWcCV.jpg","overview":"","release_date":1538010000,"genres":["Family","Animation"]}
]
Cada entrada contiene un id, un título, un enlace a una imagen de póster, opcionalmente una descripción general de la película, una fecha de lanzamiento en formato de marca de tiempo, y una lista de géneros.
Puede cargar los datos en Meilisearch utilizando curl para construir una solicitud HTTP POST. curl es una herramienta poderosa y ubicua para crear solicitudes web en la línea de comandos, y HTTP POST es uno de los pocos verbos HTTP comunes (junto con PUT y GET, utilizados por los navegadores web), utilizados para enviar datos formateados a puntos finales de API.
Los diversos argumentos del comando curl son:
-X POST http://urlespecifica que se realizará una solicitud POST y se enviarán datos.-H 'Content-Type: application/json'proporciona un encabezado h, especificando el tipo de archivo.--data-binary @movies.jsonincluye el propio archivo.- Los caracteres
\al final de cada línea son estándar cuando desea dividir un comando de shell en varias líneas sin dividir el propio comando.
Meilisearch se ejecuta en el puerto 7700 de forma predeterminada, y 127.0.0.1 refleja una IP de localhost. En este caso, estás creando un nuevo índice de Meilisearch en /indexes/movies/documents, y proporcionando el formato necesario en tu solicitud para subir un archivo JSON. Esta es una forma estándar de subir JSON con CURL.
El comando debería devolver una salida indicando que tu solicitud fue enqueued exitosamente. Meilisearch procesa todas las solicitudes de manera asíncrona en lugar de esperar a que se completen.
Output{"uid":0,"indexUid":"movies","status":"enqueued","type":"documentAddition","enqueuedAt":"2022-03-09T17:23:18.233702815Z"}
Puedes verificar el estado de esta solicitud realizando una solicitud curl -X GET al nuevo punto final /tasks/ creado en el mismo índice. Estos datos deberían procesarse muy rápidamente, por lo que la respuesta debería incluir el parámetro finishedAt:
Output{"uid":0,"indexUid":"movies","status":"succeeded","type":"documentAddition","details":{"receivedDocuments":19547,"indexedDocuments":19546},"duration":"PT29.866920116S","enqueuedAt":"2022-03-09T17:23:18.233702815Z","startedAt":"2022-03-09T17:23:18.241475424Z","finishedAt":"2022-03-09T17:23:48.108395540Z"}
Ahora tienes un índice de Meilisearch poblado con datos de muestra. En el siguiente paso, probarás algunas consultas de ejemplo para explorar los datos.
Paso 2 – Búsqueda con Meilisearch
Para buscar en un índice de Meilisearch, puedes enviar consultas individuales a través de la API, o buscar con una interfaz web.
Buscar a través de la API funciona de manera similar a subir datos mediante POST HTTP. Para buscar, realizas una solicitud al punto final /search, y puedes incluir toda tu consulta JSON en la línea de comandos. Intenta buscar saint para ver qué películas se devuelven usando el siguiente comando curl:
Devolverá un objeto JSON que contiene una lista de resultados:
Output{
"hits": [
{
"id": "45756",
"title": "Saint",
"poster": "https://image.tmdb.org/t/p/w500/pEPd4mgMwvz6aRhuWkmPUv98P1O.jpg",
"overview": "A horror film that depicts St. Nicholas as a murderous bishop who kidnaps and murders children when there is a full moon on December 5.",
"release_date": 1288486800,
"genres": []
},
{
"id": "121576",
"title": "Saint Philip Neri I Prefer Heaven",
"poster": "https://image.tmdb.org/t/p/w500/z9OsQoM343WsIrP0zMEE06pO1vH.jpg",
"overview": "An epic feature film on the famous 'Apostle of Rome' and great friend of youth in the 16th century. One of the most popular saints of all time, St. Philip Neri was widely known for his great charity, deep prayer life, and tremendous humor. Hoping to join St. Ignatius of Loyola's new order of Jesuits and be a missionary to India, Philip was instead guided by Providence to seek out the poor and abandoned youth of Rome to catechize them in the faith and help them find a better life. He became the founder of the religious congregation, the Oratory, that worked with the youth and also labored to re-evangelize a decadent Rome.",
"release_date": 1284944400,
"genres": [
"Drama"
]
},
{
"id": "221667",
"title": "Saint Laurent",
"poster": "https://image.tmdb.org/t/p/w500/ekpT7mTk4t5PjRYZfiyh0sTKpY5.jpg",
"overview": "1967-1976. As one of history's greatest fashion designers entered a decade of freedom, neither came out of it in one piece.",
"release_date": 1411434000,
"genres": [
"Drama"
]
},
...
Nota: Para lograr un formato JSON más legible en la línea de comandos, puedes instalar otra herramienta llamada jq usando sudo apt install jq. Luego, utiliza tuberías de shell para pasar la salida JSON de Meilisearch a través de jq, agregando | jq al comando.
Por ejemplo, para listar solo los títulos para la consulta de ejemplo saint, instala jq y luego ejecuta el siguiente comando:
Recibirás una lista de títulos como esta:
[secondary_label Output
Saint
Saint Philip Neri I Prefer Heaven
Saint Laurent
. . .
Para demostrar la funcionalidad de coincidencia difusa de Meilisearch, también puedes intentar buscar seint, suponiendo que un usuario haya cometido un error tipográfico:
Los resultados serán ligeramente diferentes debido a los detalles de la clasificación de la consulta, pero seguirás viendo muchas entradas que contienen “saint”.
Output{
"hits": [
{
"id": "10105",
"title": "Saints and Soldiers",
"poster": "https://image.tmdb.org/t/p/w500/efhqxap8fLi4v1GEXVvakey0z3S.jpg",
"overview": "Five American soldiers fighting in Europe during World War II struggle to return to Allied territory after being separated from U.S. forces during the historic Malmedy Massacre.",
"release_date": 1063242000,
"genres": [
"War",
"Action",
"Drama"
]
},
{
"id": "121576",
"title": "Saint Philip Neri I Prefer Heaven",
"poster": "https://image.tmdb.org/t/p/w500/z9OsQoM343WsIrP0zMEE06pO1vH.jpg",
"overview": "An epic feature film on the famous 'Apostle of Rome' and great friend of youth in the 16th century. One of the most popular saints of all time, St. Philip Neri was widely known for his great charity, deep prayer life, and tremendous humor. Hoping to join St. Ignatius of Loyola's new order of Jesuits and be a missionary to India, Philip was instead guided by Providence to seek out the poor and abandoned youth of Rome to catechize them in the faith and help them find a better life. He became the founder of the religious congregation, the Oratory, that worked with the youth and also labored to re-evangelize a decadent Rome.",
"release_date": 1284944400,
"genres": [
"Drama"
]
},
{
"id": "133558",
"title": "Saints and Soldiers: Airborne Creed",
"poster": "https://image.tmdb.org/t/p/w500/gwqR9UY0xqBZwP2qb8ZPmf9b2lq.jpg",
"overview": "A group of American GIs work their way through war-torn France during the final days of the Second World War.",
"release_date": 1345165200,
"genres": [
"Drama"
]
},
…
Ahora que has experimentado con la búsqueda en la línea de comandos, si estás ejecutando Meilisearch en una máquina local, puedes navegar a http://localhost:7700/ en un navegador para ver la interfaz web. Si estás ejecutando en un servidor remoto y has seguido los requisitos previos para este tutorial, la configuración de tu firewall evitará que esta URL sea accesible. Necesitarás crear un túnel SSH para acceder a la interfaz de búsqueda. Para crear un túnel desde tu máquina local a tu servidor, ejecuta ssh con la bandera -L. Proporciona el número de puerto 7700 junto con la dirección IP de tu servidor remoto:
Luego deberías poder acceder al panel en un navegador en http://localhost:7700.
La búsqueda en la interfaz de demostración de Meilisearch es extremadamente rápida y debería proporcionar una emocionante vista previa del uso en producción. En el siguiente paso, encontrarás ejemplos para ajustar la clasificación de búsqueda y el filtrado para sesgar ciertos parámetros sobre otros.
Paso 3 – Ajuste de la Clasificación de Búsqueda y Filtrado
Una característica importante de los motores de búsqueda es que todos implementan algún método para ponderar la importancia de diferentes campos. Otro término para esta ponderación es sesgo. Por ejemplo, supongamos que su índice de búsqueda contiene varios campos, y realiza una consulta con una sola palabra clave. El motor de búsqueda necesita instrucciones sobre cómo clasificar o sesgar sus resultados en función de la importancia de un campo.
Algunos motores de búsqueda de código abierto no permiten configurar sesgos, y los resultados de las consultas pueden ser excesivamente amplios o sesgados por tendencias en los datos más que por la relevancia de los términos de búsqueda. Meilisearch tiene un conjunto predeterminado de reglas de sesgo que puedes configurar aún más. Esta personalización puede ayudar a producir resultados más intuitivos y relevantes basados en las particularidades de tus datos.
Para verificar tus reglas de clasificación, puedes hacer una solicitud GET HTTP utilizando curl al punto final /settings/ranking-rules:
Output["words","typo","proximity","attribute","sort","exactness"]
Estas reglas se explican con más detalle en la documentación de Meilisearch. Básicamente, te permiten ajustar de manera más precisa las formas en que Meilisearch prioriza la corrección de errores comunes, frente a la proximidad de las palabras en frases.
Puedes enviar una solicitud POST HTTP con curl de vuelta a ese punto final con el mismo conjunto de reglas reorganizadas para cambiar su orden de prioridad. Si tu conjunto de datos incluye campos cuantitativos, también puedes agregar reglas de clasificación que sesgarán esos campos en orden ascendente o descendente. En este conjunto de datos, release_date es uno de esos campos, que podrías incluir de la siguiente manera:
Esta solicitud devolverá una respuesta enqueued, similar a la primera solicitud POST HTTP que usaste para cargar el archivo movies.json:
Output{"uid":1,"indexUid":"meteorites","status":"enqueued","type":"settingsUpdate","enqueuedAt":"2022-03-10T21:36:47.592902987Z"}
Meilisearch te permite consultar y actualizar reglas que describen qué atributos son buscables, qué atributos se muestran en los resultados y qué atributos se pueden filtrar o ordenar, utilizando el mismo enfoque de HTTP GET y HTTP POST.
Por ejemplo, si solo quieres que ciertos atributos sean buscables en primer lugar, y otros (como id, que probablemente no tiene valor para un usuario final) se excluyan de los resultados, puedes enviar una lista JSON de searchableAttributes al punto final settings:
Ahora solo los campos title, overview y genres son buscables, y el resto se excluyen del proceso de indexación.
También puedes cambiar qué atributos se muestran u ocultan en los resultados de búsqueda enviando por POST una lista de displayedAttributes:
Ahora todos los campos de una película están ocultos, excepto los que incluiste en la lista de displayedAttributes.
Finalmente, también puedes proporcionar una lista de atributos de tus datos para filtrar o ordenar. Esta lista incluye tanto el filtrado cuantitativo a través del uso de operadores comparativos (como > para mayor que o < para menor que) como el filtrado mediante la inclusión en un conjunto especificado, también conocido como búsqueda facetada.
Juntas, estas reglas te permiten crear consultas como la siguiente:
Esta consulta es equivalente a la frase escrita: “encuentra todas las películas con género de terror de más reciente a más antigua, que también contienen la palabra ‘casa’ en el título”. Recibirás una salida como la siguiente:
Output{
"hits": [
{
"id": "82505",
"title": "House at the End of the Street",
"poster": "https://image.tmdb.org/t/p/w500/t9E3Inaar1CAn5Cwj0M8dTwtD8H.jpg",
"overview": "A mother and daughter move to a new town and find themselves living next door to a house where a young girl murdered her parents. When the daughter befriends the surviving son, she learns the story is far from over.",
"release_date": 1348189200,
"genres": [
"Horror",
"Thriller"
]
},
{
"id": "29293",
"title": "House of the Dead 2",
"poster": "https://image.tmdb.org/t/p/w500/r95UYIFeCjIVKZ1MPxZwEHITAhg.jpg",
"overview": "In Guesta Verde University, the deranged Professor Curien is trying to bring back the dead, killing students for the experiment. There is an outbreak of zombies in the campus, and the government sends a NSA medical research team, formed by Dr. Alexandra Morgan a.k.a. Nightingale and lieutenant Ellis, with a special force leaded by lieutenant Dalton, trying to get the zero sample from the first generation zombie. The team has a very short time to accomplish their mission and leave the place before missiles are sent to destroy the area. However, the place is crowded of hyper sapiens and the group has to fight to survive.",
"release_date": 1139616000,
"genres": [
"TV Movie",
"Horror"
]
},
{
"id": "10066",
"title": "House of Wax",
"poster": "https://image.tmdb.org/t/p/w500/r0v8qg78Ol9NIsRGe3DME27ORpd.jpg",
"overview": "A group of unwitting teens are stranded near a strange wax museum and soon must fight to survive and keep from becoming the next exhibit.",
"release_date": 1114822800,
"genres": [
"Horror",
"Drama"
]
},
…
Incluir y excluir campos en la indexación, búsqueda y visualización de documentos son características fundamentales de los motores de búsqueda basados en documentos. Habilitarlos condicionalmente te permite mantener el rendimiento de búsqueda y personalizar rápidamente y exhaustivamente tu motor de búsqueda para satisfacer a los usuarios finales.
Ahora que has explorado cómo ejecutar, consultar y configurar Meilisearch, en el siguiente paso de este tutorial, crearás una configuración de docker-compose para Meilisearch que le permitirá ejecutarse en segundo plano con una clave de autenticación segura.
Paso 4 – Creación de una configuración Docker-Compose y uso de autenticación basada en claves
Como cualquier otra aplicación del lado del servidor, los usuarios finales de un índice de Meilisearch deben suponer que estará en funcionamiento y disponible en todo momento. Para garantizar que Meilisearch pueda reiniciarse regularmente con su servidor, y que sus registros sean rastreados, debería crear una configuración de docker-compose que le permita ser administrado automáticamente.
Primero, cree un directorio en /var/local que pueda ser utilizado por Meilisearch para almacenar permanentemente su índice de búsqueda y otros detalles de configuración:
Después de eso, cree un directorio en su entorno de trabajo existente llamado meilisearch-docker, que se utilizará para almacenar una configuración Docker para Meilisearch, y luego cd en ese directorio:
A continuación, utilizando nano o su editor de texto favorito, abra un archivo llamado docker-compose.yml:
Copie el siguiente contenido en el archivo. Este será su configuración Docker de Meilisearch.
version: "3.9"
services:
meilisearch:
image: "getmeili/meilisearch:v0.26.1"
restart: unless-stopped
ports:
- "127.0.0.1:7700:7700"
volumes:
- /var/local/meilisearch:/data.ms
env_file:
- ./meilisearch.env
Guarde y cierre el archivo. Si está utilizando nano, presione Ctrl+X, luego cuando se le solicite, Y y luego ENTER.
La configuración utilizada en este archivo es similar a la sintaxis original de docker que ejecutaste anteriormente en este tutorial, con algunas adiciones:
restart:unless-stoppedsignifica que este servicio seguirá ejecutándose en segundo plano y persistirá a través de reinicios a menos que lo detengas manualmente.- Tu índice de Meilisearch ahora es persistente y se almacena en
/var/local/meilisearchen tu máquina local. env_filedeclara un archivo de entorno,./meilisearch.env, para configurar opciones de Meilisearch.
Las variables de entorno te permiten ejecutar meilisearch con opciones adicionales, para declarar efectivamente tu configuración en tiempo de ejecución. Usar variables de entorno es una forma consistente y global de configurar parámetros de aplicación sin necesidad de editar un archivo de configuración específico de la aplicación. docker-compose te permite declarar variables de entorno en un archivo separado para evitar incluir información secreta en la configuración principal de docker-compse.yml.
Para ejecutar Meilisearch en modo de producción, necesitarás configurar una clave API para un uso seguro. Puedes crear tu propia clave, o generar una usando el siguiente comando de openssl:
Output173e95f077590ed33dad89247247be8d8ce8b6722ccc87829aaefe3207be
Toma nota de esta clave en algún lugar seguro. Finalmente, utilizando nano o tu editor de texto favorito nuevamente, abre ese nuevo archivo llamado meilisearch.env:
Pega tu clave en el archivo como la variable de entorno MEILI_MASTER_KEY:
MEILI_MASTER_KEY="173e95f077590ed33dad89247247be8d8ce8b6722ccc87829aaefe3207be"
Guarde y cierre el archivo. Si todavía tiene una instancia de Meilisearch ejecutándose en otra terminal, ahora debe cerrarla navegando de vuelta a esa ventana de terminal y presionando Ctrl+C. Ahora, puede iniciar la nueva instancia de Meilisearch Docker, utilizando docker-compose up con --detach para ejecutarlo en segundo plano:
Puede verificar que se inició correctamente utilizando docker ps:
Output Name Command State Ports
------------------------------------------------------------------------------------------------------------
meilisearch-docker_meilisearch_1 tini -- /bin/sh -c ./meili ... Up 127.0.0.1:7700->7700/tcp
A partir de ahora, Meilisearch se reiniciará automáticamente en reinicios del servidor. Si alguna vez lo necesita, puede detener el contenedor Docker navegando de vuelta al directorio ~/docker-meilisearch y ejecutando docker compose stop.
Esta configuración de docker-compose también creará un nuevo índice de búsqueda vacío que necesitará rellenar para continuar trabajando con los datos de muestra. Si necesita migrar alguna regla que haya creado con su índice existente, puede seguir la documentación de actualización de Meilisearch.
Su instancia de Meilisearch ahora también está utilizando autenticación basada en clave, lo que requiere que se incluya un encabezado adicional -H 'Authorization: Bearer 173e95f077590ed33dad89247247be8d8ce8b6722ccc87829aaefe3207be' con cada solicitud de API. Puede revisar la documentación de autenticación de Meilisearch para crear múltiples claves de autenticación con niveles de permiso más granulares, si es necesario.
Conclusión
En este tutorial, desplegaste y configuraste un índice de Meilisearch utilizando Docker. Viste ejemplos de su análisis de consultas y las estructuras de respuesta de su API, así como el rendimiento de búsqueda de su interfaz web. Puedes realizar consultas a Meilisearch utilizando solicitudes JSON enviadas desde cualquier aplicación, de la misma manera que lo hiciste usando curl. Experimentaste con cambios en la ponderación de los resultados de búsqueda y creaste un archivo docker-compose.yml para gestionar la ejecución de tu servidor Meilisearch.
También creaste una clave API y la configuraste como una variable de entorno para Meilisearch para prepararte para un despliegue seguro en producción. Sin embargo, la interfaz de búsqueda basada en web que utilizaste en este tutorial no está diseñada para ser utilizada en producción, ya que tiene un soporte limitado para facetas y otras funciones avanzadas de búsqueda. En el próximo tutorial de esta serie, desplegarás un frontend de Meilisearch utilizando la biblioteca InstantSearch en una aplicación Node.js.
