--- title: "Cómo instalar el motor de búsqueda Sonic en Ubuntu 24.04" description: "Instala Sonic en Ubuntu 24.04 como servicio systemd, indexa textos con su protocolo Sonic Channel y consulta búsquedas y autocompletado desde Python." category: "Motores de Búsqueda" language: es source: https://cubepath.com/es/docs/motores-de-búsqueda/instalacion-de-sonic-motor-de-busqueda-ligero updated: 2026-09-25 --- # Cómo instalar el motor de búsqueda Sonic en Ubuntu 24.04 Sonic es un backend de búsqueda escrito en Rust que consume unas decenas de MB de RAM. A diferencia de Elasticsearch o Solr, no guarda los documentos: solo mantiene un índice invertido que asocia palabras con identificadores de objetos. Tu aplicación le pregunta por unos términos, Sonic devuelve los IDs que coinciden y tú recuperas los datos completos de tu base de datos. En este tutorial instalarás Sonic en Ubuntu 24.04 como servicio systemd, indexarás y buscarás textos con su protocolo Sonic Channel y lo integrarás en un script de Python. ## Requisitos previos Para seguir esta guía necesitas: - Un servidor con Ubuntu 24.04 LTS de 64 bits (x86_64), por ejemplo un VPS de CubePath. - Un usuario no root con privilegios `sudo`. - 512 MB de RAM libres son suficientes para empezar. - `nc` (netcat), que viene instalado por defecto en Ubuntu 24.04. Sonic escuchará solo en `127.0.0.1:1491`, por lo que no hace falta abrir ningún puerto en el cortafuegos. ## Cómo organiza Sonic los datos Antes de indexar conviene entender su jerarquía de tres niveles: | Nivel | Qué representa | Ejemplo | |-------|----------------|---------| | Colección (`collection`) | El tipo de contenido que buscas | `productos`, `articulos` | | Bucket | Una partición dentro de la colección, por ejemplo por cliente. Si no necesitas particionar, usa un nombre fijo | `default`, `cliente-42` | | Objeto (`object`) | El identificador del registro en tu base de datos | `prod-001` | Sonic se usa a través de tres modos de conexión: `ingest` para escribir en el índice, `search` para consultar y `control` para tareas de administración. ## Paso 1: Descargar el binario de Sonic El proyecto publica binarios para Linux en GitHub. Descarga la última versión (1.10.0 al escribir esta guía; consulta la [página de versiones](https://github.com/valeriansaliou/sonic/releases) por si hay una más reciente): ```bash SONIC_VERSION=1.10.0 cd /tmp wget "https://github.com/valeriansaliou/sonic/releases/download/v${SONIC_VERSION}/v${SONIC_VERSION}-x86_64-gnu.tar.gz" tar xzf "v${SONIC_VERSION}-x86_64-gnu.tar.gz" ``` El archivo contiene el binario y un archivo de configuración de ejemplo: ```bash ls sonic/ ``` ```output config.cfg sonic ``` Instala el binario en `/usr/local/bin`: ```bash sudo install -m 0755 sonic/sonic /usr/local/bin/sonic ``` ## Paso 2: Crear el usuario y los directorios Sonic no necesita privilegios, así que lo ejecutarás con un usuario de sistema propio que solo puede escribir en su directorio de datos: ```bash sudo useradd --system --no-create-home --shell /usr/sbin/nologin sonic sudo install -d -o sonic -g sonic -m 0750 /var/lib/sonic sudo install -d -m 0755 /etc/sonic ``` Parte del archivo de configuración oficial que venía en el paquete: ```bash sudo install -o root -g sonic -m 0640 sonic/config.cfg /etc/sonic/config.cfg ``` ## Paso 3: Configurar Sonic Genera una contraseña aleatoria para el canal. Cualquier cliente la necesitará para conectarse: ```bash openssl rand -hex 24 ``` Copia el valor y abre el archivo de configuración: ```bash sudo nano /etc/sonic/config.cfg ``` Modifica solo las siguientes claves y deja el resto con sus valores por defecto. Sustituye `your_sonic_password` por la contraseña que acabas de generar: ```toml [server] log_level = "info" [channel] inet = "127.0.0.1:1491" tcp_timeout = 300 auth_password = "your_sonic_password" ``` Más abajo, en las secciones `[store.kv]` y `[store.fst]`, cambia las rutas relativas por rutas absolutas dentro de `/var/lib/sonic`: ```toml [store.kv] path = "/var/lib/sonic/store/kv/" ``` ```toml [store.fst] path = "/var/lib/sonic/store/fst/" ``` El almacén `kv` guarda el índice invertido (en RocksDB) y el `fst` guarda los grafos de palabras que se usan para el autocompletado. El valor `graph.consolidate_after = 180` de la sección `[store.fst]` indica cada cuántos segundos se incorporan las palabras nuevas al grafo de sugerencias. ## Paso 4: Crear el servicio systemd Crea la unidad del servicio: ```bash sudo nano /etc/systemd/system/sonic.service ``` Añade este contenido: ```ini [Unit] Description=Sonic search backend After=network.target [Service] Type=simple User=sonic Group=sonic ExecStart=/usr/local/bin/sonic -c /etc/sonic/config.cfg Restart=on-failure RestartSec=5 LimitNOFILE=65536 NoNewPrivileges=true ProtectSystem=strict ReadWritePaths=/var/lib/sonic ProtectHome=true PrivateTmp=true [Install] WantedBy=multi-user.target ``` `ProtectSystem=strict` deja todo el sistema de archivos en solo lectura para el proceso excepto `/var/lib/sonic`. Recarga systemd e inicia el servicio: ```bash sudo systemctl daemon-reload sudo systemctl enable --now sonic ``` Comprueba que está activo y escuchando: ```bash sudo systemctl status sonic sudo ss -tlnp | grep 1491 ``` ```output LISTEN 0 1024 127.0.0.1:1491 0.0.0.0:* users:(("sonic",pid=4121,fd=12)) ``` ## Paso 5: Indexar textos con el modo ingest Sonic Channel es un protocolo de texto sobre TCP, parecido al de Redis, así que puedes probarlo con `nc`. Conéctate: ```bash nc 127.0.0.1 1491 ``` ```output CONNECTED ``` A partir de aquí escribes comandos y Sonic responde línea a línea. Entra en modo `ingest` con tu contraseña: ```text START ingest your_sonic_password ``` ```output STARTED ingest protocol(1) buffer(20000) ``` Indexa tres productos con `PUSH ""`. El texto va siempre entre comillas. `LANG(spa)` indica que el texto está en español (código ISO 639-3) para que Sonic elimine las palabras vacías correctas; si lo omites, intenta detectar el idioma por sí mismo: ```text PUSH productos default prod-001 "Camiseta básica de algodón en varios colores" LANG(spa) PUSH productos default prod-002 "Zapatillas de running ligeras con amortiguación" LANG(spa) PUSH productos default prod-003 "Zapatillas de montaña para senderismo" LANG(spa) ``` Cada `PUSH` correcto responde `OK`. Comprueba cuántos objetos hay en el bucket con `COUNTB` y sal: ```text COUNTB productos default QUIT ``` ```output RESULT 3 ENDED quit ``` Sonic no tiene un comando para actualizar un objeto. Si el texto de un producto cambia, bórralo con `FLUSHO productos default prod-001` y vuelve a indexarlo con `PUSH`. Para vaciar un bucket entero existe `FLUSHB` y para una colección completa, `FLUSHC`. ## Paso 6: Buscar y autocompletar con el modo search Abre una nueva conexión y entra en modo `search`: ```bash nc 127.0.0.1 1491 ``` ```text START search your_sonic_password QUERY productos default "zapatillas" LIMIT(10) ``` Las consultas son asíncronas: Sonic responde primero con `PENDING` y un marcador, y después envía el resultado con el mismo marcador: ```output STARTED search protocol(1) buffer(20000) PENDING Bt2m2gYa EVENT QUERY Bt2m2gYa prod-003 prod-002 ``` El resultado son los identificadores de los objetos, no los textos. `SUGGEST` completa una palabra a partir de su comienzo, que es lo que necesitas para un buscador con sugerencias mientras el usuario escribe: ```text SUGGEST productos default "zapa" QUIT ``` ```output PENDING z98uDE0f EVENT SUGGEST z98uDE0f zapatillas ENDED quit ``` > Nota: las palabras nuevas tardan hasta `graph.consolidate_after` segundos (180 por defecto) en aparecer en `SUGGEST`. Si acabas de indexar y no ves sugerencias, espera unos minutos o fuerza la consolidación desde el modo `control` con `TRIGGER consolidate`. ## Paso 7: Integrar Sonic en una aplicación Python En una aplicación real no usarás `nc`, sino una librería cliente. Crea un entorno virtual para no mezclar paquetes con los del sistema: ```bash sudo apt install python3-venv python3 -m venv ~/sonic-demo ~/sonic-demo/bin/pip install sonic-client ``` Crea el script de ejemplo: ```bash nano ~/sonic-demo/demo.py ``` El script indexa unos productos (en tu aplicación vendrían de la base de datos) y después busca y pide sugerencias. Guarda la contraseña en una variable de entorno en lugar de escribirla en el código: ```python import os from sonic import IngestClient, SearchClient HOST, PORT = "127.0.0.1", 1491 PASSWORD = os.environ["SONIC_PASSWORD"] productos = { "prod-004": "Pantalón vaquero slim de corte moderno", "prod-005": "Chaqueta impermeable para montaña", } with IngestClient(HOST, PORT, PASSWORD) as ingest: for object_id, texto in productos.items(): ingest.push("productos", "default", object_id, texto, lang="spa") with SearchClient(HOST, PORT, PASSWORD) as search: ids = search.query("productos", "default", "montaña", limit=10) print("IDs encontrados:", ids) print("Sugerencias:", search.suggest("productos", "default", "zapa", limit=5)) ``` Ejecútalo pasando la contraseña como variable de entorno: ```bash SONIC_PASSWORD='your_sonic_password' ~/sonic-demo/bin/python ~/sonic-demo/demo.py ``` ```output IDs encontrados: ['prod-005', 'prod-003'] Sugerencias: ['zapatillas'] ``` Con esos IDs tu aplicación lanza una consulta del tipo `SELECT ... WHERE id IN (...)` contra su base de datos y muestra los resultados. Cuando un registro cambie o se borre en la base de datos, repite el `FLUSHO` y el `PUSH` correspondientes para que el índice siga sincronizado. ## Solución de problemas **El servicio no arranca.** Revisa el log del servicio: ```bash sudo journalctl -u sonic -n 50 --no-pager ``` Un error de permisos sobre `/var/lib/sonic` suele indicar que el directorio no pertenece al usuario `sonic`; corrígelo con `sudo chown -R sonic:sonic /var/lib/sonic`. Un error de sintaxis apunta a una comilla o sección mal escrita en `/etc/sonic/config.cfg`. **`ENDED authentication_failed` al hacer `START`.** La contraseña no coincide con `auth_password`. Recuerda reiniciar el servicio (`sudo systemctl restart sonic`) después de cambiar la configuración. **`ERR invalid_format` al indexar.** El texto de `PUSH` debe ir entre comillas dobles y las comillas internas deben escaparse como `\"`. **Una búsqueda no encuentra una palabra que sí está indexada.** Sonic descarta las palabras vacías del idioma detectado. Si indexas textos cortos sin `LANG(...)`, la detección puede fallar; indica el idioma de forma explícita tanto al indexar como al consultar. ## Conclusión Tienes Sonic funcionando como servicio en Ubuntu 24.04, con su índice en `/var/lib/sonic`, y sabes indexar, buscar y obtener sugerencias tanto con el protocolo Sonic Channel como desde Python. Como siguientes pasos, puedes programar una reindexación completa periódica desde tu base de datos para corregir desajustes, usar el comando `TRIGGER backup` del modo `control` para hacer copias del índice, o probar otras librerías cliente como `sonic-channel` para Node.js.