Un cliente escribe el nombre de un producto con una errata y obtiene una lista vacía de resultados, aunque el producto está disponible en la tienda. El mismo problema afecta a la documentación y a los catálogos de contenido complejos. Meilisearch permite añadir a tu aplicación una búsqueda tolerante a erratas. En este tutorial te mostraremos cómo desplegar Meilisearch en Saplo, cargar los primeros datos y ejecutar una consulta en el motor de búsqueda.
Qué es Meilisearch y para quién es una buena opción
Meilisearch es un motor de búsqueda que ofrece una API REST. Envías los datos seleccionados y tu sitio web obtiene los resultados a través de la API. Es una buena opción para un catálogo de productos, una base de conocimiento o un servicio con artículos. Puedes conocer sus aplicaciones en la página de hosting de Meilisearch en Saplo.
La instalación por sí sola no conecta automáticamente una tienda ni crea un formulario de búsqueda en el sitio. Necesitas una integración que transmita los datos y muestre los resultados. Empieza con un conjunto pequeño y público, por ejemplo, los nombres y descripciones de varios productos.
Requisitos y coste del hosting
El plan más barato que cumple los requisitos de instalación es Box S por 27 € al año. Este es el punto de partida para poner en marcha el servicio; el tamaño del índice de destino, la frecuencia de importación y las demás aplicaciones en Box influyen en los recursos necesarios. Antes de importar todo el catálogo, comprueba el espacio disponible y la memoria.
Prepara un Box activo, el nombre de la aplicación y un dominio o un subdominio disponible *.saploapp.pl. Para los siguientes ejemplos necesitas un terminal Bash y el programa curl en tu propio ordenador. No necesitas SSH para Box: harás la instalación en el panel, descargarás el archivo de inicio mediante SFTP y enviarás las solicitudes mediante HTTPS.
Instalación paso a paso
- Inicia sesión en el panel de Saplo y abre el Catálogo de aplicaciones.
- Selecciona Meilisearch y empieza a crear la aplicación.
- Asígnale un nombre, por ejemplo
wyszukiwarka, y selecciona un Box con recursos libres. - Selecciona un dominio o subdominio. Conserva la dirección HTTPS exacta que aparece en el panel.
- Confirma la instalación. Espera a que termine y comprueba el estado de la aplicación y los posibles mensajes.
- Conéctate por SFTP usando los datos de acceso de Box. En el directorio de la aplicación, busca y descarga el archivo
MEILISEARCH-SETUP.txt.
El instalador de Saplo ejecuta Meilisearch en modo de producción y genera una clave de administración. El archivo de inicio contiene la dirección de la API y esa clave. La vista previa integrada del buscador, conocida del modo de desarrollo, está desactivada, por lo que la ausencia de un panel de inicio de sesión en la dirección principal no indica un fallo.
Primera conexión y clave de administración
En la terminal Bash de tu propio ordenador, configura la dirección del archivo de inicio, sin barra final:
MEILI_URL='https://YOUR-APP-ADDRESS'
curl -sS "$MEILI_URL/health"
La respuesta correcta es {"status":"available"}. El endpoint comprueba la disponibilidad del motor, tal como explica la documentación del health check. Todavía no confirma que la importación de datos sea correcta.
Carga la clave de administración sin mostrarla en pantalla y sin escribir su valor en el historial de comandos:
read -r -s -p 'Meilisearch admin key: ' MEILI_ADMIN_KEY
printf '\n'
Pega el valor del archivo de inicio y pulsa Enter. Esta es la clave de Meilisearch, no la contraseña de Saplo. Úsala únicamente en un entorno administrativo de confianza. No la incluyas en el JavaScript de la página, en un repositorio ni en capturas de pantalla. La documentación de las claves de Meilisearch explica cómo separar los permisos.
Adición de los primeros documentos
Crea en tu ordenador un archivo products-demo.json en UTF-8:
[
{"id": 1, "name": "Ceramic mug", "description": "White coffee mug"},
{"id": 2, "name": "Glass jug", "description": "Tea jug"}
]
En la misma terminal, en el directorio donde está el archivo, ejecuta:
curl -sS -X POST "$MEILI_URL/indexes/products-demo/documents?primaryKey=id" \
-H "Authorization: Bearer $MEILI_ADMIN_KEY" \
-H 'Content-Type: application/json' \
--data-binary @products-demo.json
El campo id identifica el documento. La primera importación creará el índice products-demo. La respuesta incluye taskUid, es decir, el número de tarea de indexación. El esquema de importación se explica en la guía oficial de inicio de Meilisearch.
Comprobación de la indexación
Que la consulta sea aceptada no significa que el trabajo haya terminado. Introduce el número recibido en el campo taskUid y comprueba la tarea:
MEILI_TASK_ID='WPISZ_NUMER_TASKUID'
curl -sS "$MEILI_URL/tasks/$MEILI_TASK_ID" \
-H "Authorization: Bearer $MEILI_ADMIN_KEY"
Espera a status: succeeded. Si enqueued o processing, vuelve a comprobarlo dentro de un momento. Si failed, lee el campo error y corrige los datos antes de volver a importarlos. Encontrarás información sobre la cola en la documentación de tareas de API.
Una clave independiente para la búsqueda
Crea una clave con permiso de búsqueda únicamente en el índice de ejemplo:
curl -sS -X POST "$MEILI_URL/keys" \
-H "Authorization: Bearer $MEILI_ADMIN_KEY" \
-H 'Content-Type: application/json' \
--data-binary '{"description":"Search in the public demo catalog","actions":["search"],"indexes":["products-demo"],"expiresAt":null}'
Guarda el valor key de la respuesta. La restricción a products-demo es deliberada: una clave destinada a un solo catálogo no debe dar acceso a todos los índices. Esta clave permite leer los resultados de búsqueda, por lo que en el frontend público úsala solo con datos destinados a ser publicados. No incluyas en este índice datos de clientes ni notas internas.
Carga la clave obtenida y envía una consulta:
read -r -s -p 'Meilisearch search key: ' MEILI_SEARCH_KEY
printf '\n'
curl -sS -X POST "$MEILI_URL/indexes/products-demo/search" \
-H "Authorization: Bearer $MEILI_SEARCH_KEY" \
-H 'Content-Type: application/json' \
--data-binary '{"q":"mug"}'
En la tabla hits debería aparecer el documento “Taza de cerámica”. Repite la prueba con la consulta kubke para comprobar la tolerancia a los errores ortográficos con la configuración predeterminada. Al terminar, elimina las variables de la terminal:
unset MEILI_ADMIN_KEY MEILI_SEARCH_KEY
Conectar tu propio sitio web
Tras una prueba correcta, selecciona los datos que deben llegar al índice adecuado. Define cuándo la integración añade nuevos registros, actualiza los modificados y elimina los retirados. Prueba todo el ciclo con un producto antes de hacer una importación completa. Planifica también cómo reconstruir el índice a partir de la fuente de datos.
El formulario de búsqueda debe utilizar una clave independiente con permisos limitados. Para el contenido que requiere inicio de sesión, diseña el control de acceso en el lado de tu aplicación. Ocultar el campo en la interfaz no restringe el acceso a través de la API.
Preguntas frecuentes
¿Cuánto cuesta Meilisearch en Saplo?
El plan más barato que cumple los requisitos de instalación es Box S por 27 € al año. Con un conjunto de datos más grande, comprueba el consumo de recursos durante la importación y la búsqueda.
¿Por qué no veo el buscador bajo el dominio?
La instalación de Saplo funciona en modo de producción como API. Empieza por /health y luego realiza la importación y una consulta siguiendo el tutorial. El formulario para los usuarios lo añades en tu propia web.
¿Qué debes comprobar cuando aparece un error de autorización?
Compara la dirección de la API y la clave con la instalación correcta. La cabecera tiene este formato: Authorization: Bearer .... Una clave con solo el permiso search no sirve para importar documentos ni gestionar claves.
¿Por qué no hay resultados después de la importación?
Primero comprueba el estado de la tarea. Después, compara el nombre del índice en la URL de la consulta con el utilizado durante la importación. Comprueba también si el documento contiene el contenido que buscas.
¿Meilisearch recopila por sí solo los productos de una tienda?
No. La instalación inicia el motor de búsqueda. La integración con tu tienda o aplicación se encarga de sincronizar los datos y ofrecer el formulario de resultados.
Abre la oferta de Meilisearch en Saplo, activa el servicio y empieza con dos documentos de ejemplo. Cuando la importación y la búsqueda funcionen, conecta tu propio catálogo.
- #Meilisearch
- #Self-hosting
- #Guía
- #Buscador
