TypeSense

WordPressin oma haku on huono. Tai jos halutaan olla diplomaattisempia, se ei ole optimaalinen. Tämä tulee erikoisen hyvin esille esimerkiksi verkkokaupoissa, joissa on paljon tuotteita. Tämän blogin avulla voit kytkeä WordPress-sivustosi käyttämään  TypeSense-hakumoottoria. Jos olet Drupal-käyttäjä, ei hätää! Meillä on ohjeet myös Drupal-sivuston integrointiin, sillä ei se Drupalinkaan oma haku kovin kaksinen ole.

TypeSense on siis avoimen lähdekoodin hakumoottori, jonka voi kytkeä esimerkiksi WordPress- tai Drupal-sivustoihin. Se mahdollistaa nopeamman ja laadukkaamman hakutyökalun kuin esim. edellämainittujen alustojen omat haut. Sivuston käyttäjä ei välttämättä sinänsä huomaa, että sivusto käyttää ulkoista hakumoottoria, koska varsinainen työ tapahtuu käyttäjälle näkymättömissä. Lopputuloksen pitäisi kuitenkin olla toimiva ja miellyttävä.

Periaatteessa nämä ohjeet toimivat soveltaen myös muille hakumoottoreille, tai ainakin kouvolalaisittain “tästä näkee sen periaatteen”. Mekin kokeilimme käyttää ensin Solria, mutta sen kanssa oli kaikenlaista hankaluutta. TypeSense taas toimi heti (mikä toki on sekin epäilyttävää), ja ainakin toistaiseksi sen kanssa on saanut tehtyä kaiken mitä on haluttukin.

Teksti on palasteltu osiin, ja kunkin osan alussa on sen tekemiseen vaadittavat taidot ja resurssit. Pyrimme tarjoamaan kaiken tarvittavan tiedon suoraan tässä tekstissä, ja luotamme lukijan kykyyn hakea tarvittaessa lisätietoa.

Ja mikäli sinulla olisi tarvetta paremmalle hakutyökalulle, mutta myös muutakin tekemistä kuin lukea joidenkin koodiapinoiden ohjeita nöräilyhommiin, ole meihin yhteydessä! Hoitelemme TypeSensen asennuksen puolestasi, ja sinä voit tehdä sillä välin jotain järkevää, kuten katsoa pari jaksoa Regular Show’ta.

Nyt voit vetää hakumoottorin asennushousut jalkaan ja siirrytään itse ohjeeseen. (Voit tehdä asennuksen myös ilman housuja, jos siltä tuntuu!)

Missä indeksi on? 

Hakumoottorin käyttämän indeksin voi sijoittaa kolmannen osapuolen palveluun (https://cloud.typesense.org/), mutta me teimme itse ja säästimme! Jos kuitenkin päädyt käyttämään ulkopuolista palvelua, voit ohittaa kohdat Domain ja Container.

Domain

EDELLYTYS: SINULLA ON PÄÄSY KÄYTTÄMÄSI DOMAININ DNS-ASETUKSIIN JA OSAAT LISÄTÄ SIELLÄ TIETUEITA.

Ohjataan ensin haluttu domain osoittamaan palvelimelle. Esimerkissä meillä on käytössä domain domain.fi, jonka DNS-asetuksiin lisäämme A-tietueen alidomainille typesense ja ohjaamme sen palvelimen IP-osoitteeseen.

Container

EDELLYTYS: SINULLA ON PÄÄSY SSH-YHTEYDELLÄ PALVELIMELLE JA OIKEUKSIA TOIMIA SIELLÄ. OSAAT LUODA JA MUOKATA TIEDOSTOJA JA MUUTENKIN AJAA KOMENTOJA. PALVELIMELLA ON ASENNETTUNA DOCKER JA CERTBOT TAI PYSTYT ASENTAMAAN NE ITSE.

Indeksi on sijoitettuna palvelimella pyörivään containeriin elikkäs konttiin.

Tätä varten palvelimella pitää olla Docker asennettuna. Mikäli näin ei ole, siihen löytyy ohjeet täältä: https://docs.docker.com/engine/install/.

Kun Docker on toiminnassa, tarvitset kaksi tiedostoa kontin luomiseen. Ne voivat sijaita periaatteessa missä tahansa palvelimella, kunhan ovat samassa paikassa.

Tiedostoa varten tarvitset API-avaimen. Se voi olla mikä tahansa 20 merkkiä pitkä merkkijono ja voit generoida sen vaikkapa täällä: https://www.lastpass.com/features/password-generator.

Ensin tarvitset docker-compose.yml -tiedoston, johon tulee (korvaa api-key äsken luomallasi avaimella):

services:
  typesense:
    build:
      context: .
      dockerfile: Dockerfile
    image: typesense
    restart: on-failure
    ports:
      - "8108:8108"
    volumes:
      - ./typesense-data:/data
    command: '--data-dir /data --api-key=******************** --enable-cors'
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8108/health"]
      interval: 10s
      timeout: 2s
      retries: 5

Tämän lisäksi tarvitaan Dockerfile -tiedosto, johon tulee (versionumero voi luonnollisesti olla eri):

FROM typesense/typesense:29.0

RUN apt-get update

RUN apt-get install -y curl

Kun molemmat tiedostot on luotu, mene hakemistoon jossa ne ovat ja aja seuraavat komennot:

docker compose up -d

docker ps

Ensimmäinen komento käynnistää kontin, -d irrottaa sen pyörimään taustalle. Jälkimmäinen näyttää tietoja kontista, jotta voit varmistua, että se toimii oikein.

Luodaan vielä erillinen avain käytettäväksi TypeSense-lisäosan kanssa. Aja seuraava komento käyttäen itse luomaasi API-avainta tähtien tilalla.

curl 'http://localhost:8108/keys' \

    -X POST \

    -H "X-TYPESENSE-API-KEY: ********************" \

    -H 'Content-Type: application/json' \

    -d '{"description":"Admin key.","actions": ["*"], "collections": ["*"]}'

Saat vastauksena avaimen: ota se talteen.

Ohjataan vielä alussa luomamme domain osoittamaan konttiin. Lisätään kansioon  /etc/nginx/sites-available tiedosto typesense.domain.fi.conf, johon tulee:

server {

  server_name typesense.domain.fi;

  access_log /var/log/nginx/typesense.access.log;

  error_log /var/log/nginx/typesense.error.log;

  add_header X-Content-Type-Options "nosniff";

  #add_header Strict-Transport-Security 'max-age=31536000; includeSubDomains; preload';

  listen 80;

  location / {

    proxy_pass http://localhost:8108;

    proxy_http_version 1.1;

    proxy_set_header Host $host;

    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

  }

}

Huomaa, että toinen add_header on kommentoituna. Kommentointi otetaan pois myöhemmin. Kun olet tallentanut tiedoston, aja seuraavat komennot:

sudo ln -s /etc/nginx/sites-available/typesense.domain.fi.conf /etc/nginx/sites-enabled/

sudo nginx -t

Ja jos edellinen komento palauttaa OK, aja:

sudo service nginx reload

Muista vaihtaa typesense.domain.fi sekä tiedoston nimessä että sisällössä käyttämääsi domainiin. Lisää lopuksi sertifikaatti valitulle domainille certbotin avulla (vaatii nginx:n uudelleenkäynnistyksen):

sudo certbot —-nginx

Valitse oikean domainin numero ja kun prosessi on valmis, aja

sudo nginx -t

Jos edellinen palauttaa OK, aja jälleen

sudo service nginx reload

Tämän jälkeen voit ottaa kommentoinnin pois jälkimmäiseltä add_header -riviltä typesense.domain.fi.conf -tiedostossa.

WordPress-plugin

EDELLYTYS: SINULLA ON YLLÄPITO-OIKEUDET WORDPRESS-SIVUSTOLLE JA OSAAT SEKÄ ASENTAA ETTÄ KONFIGUROIDA LISÄOSIA. MIKÄLI HALUAT OTTAA KÄYTTÖÖN MAKSULLISEN WOOCOMMERCE-LAAJENNOKSEN TYPESENSEEN, TARVITSET MYÖS LUOTTOKORTIN.

(Jos olet Drupal-tyyppi, löytyy ohjeet sen kanssa mellastamiseksi alempaa.)

Seuraavaksi ladataan WordPress-plugin, joka huolehtii yhteydenotosta indeksiin. Löydät sen osoitteesta https://wordpress.org/plugins/search-with-typesense/ tai hakemalla WordPressin kautta. Tämän lisäksi, mikäli käytössä on WooCommerce, tarvitaan myös lisäosa sille: https://www.codemanas.com/downloads/typesense-search-for-woocommerce/. Tämä lisäosa on maksullinen, joten se pitää ostamisen jälkeen ladata itselleen ja sen jälkeen sivustolle.

Kun plugin on asennettu ja käytössä on joko kontti tai TypeSensen palvelu, pitää vielä konfiguroida pluginin asetukset.

Protokolla on https ja portti on 443. API-avaimen loit aiemmin curl-komennolla, voit laittaa saman avaimen sekä Admin- että Search-kohtiin.

Mikäli käytät maksullista WooCommerce -lisäosaa, lisää sen lisenssiavain.

Kun yhteys on luotu, voit indeksoida. Esimerkissä on indeksoitu vain tuotteet, mutta voit indeksoida hakuun mitä tahansa saatavilla olevia sisältötyyppejä.

Plugin korvaa WordPressin oletushaun automaattisesti, mutta jos käytät Elementoria, TypeSense luo kaksi widgetia, Autocomplete ja Instant Search. Autocomplete on perinteinen hakukenttä, joka nimensä mukaisesti tarjoaa vaihtoehtoja sitä mukaa, kun siihen kirjoittaa. Instant Search luo täysipainoisen hakutyökalun sisältäen mm. filtterit.

Voit myös luoda hakuelementtejä Shortcodes-välilehden alta löytyvien ohjeiden mukaan.

Näkymien muokkaus

Voit halutessasi muokata hakunäkymiä ja -elementtejä dokumentaatiosta löytyvien ohjeiden avulla: https://docs.wptypesense.com/template-overriding/.

Yksittäisenä huomiona: testisivustollamme hakutulosten “lisää ostoskoriin” -nappi heitti kävijän jostain syystä ylläpitosivulle, jolloin normaalikäyttäjällä tuli sen vuoksi 403-virhe. Linkki luodaan, kun tuote viedään indeksiin, joten tässä kohtaa tapahtuu jotain piruutta. Ratkaisimme asian asettamalla linkin käsin instant-search-hits.php -templatessa.

Kääntäminen suomeksi onnistui ainakin LocoTranslate-lisäosan avulla normaalisti.

Jos Drupal-asiat eivät kiinnosta, katso vielä tekstin lopusta kohta Indeksin optimointi.

Drupal-moduli

EDELLYTYS: SINULLA ON YLLÄPITO-OIKEUDET DRUPAL-SIVUSTOLLE JA OSAAT SEKÄ ASENTAA ETTÄ KONFIGUROIDA LISÄOSIA. SINULLA ON MYÖS PÄÄSY PALVELIMELLE, JOSSA ON ASENNETTUNA COMPOSER.

Mikäli olet Drupal-käyttäjä, tässä on ohjeita sinulle! Tee aiemmista ohjeista kaikki kohtaan WordPress-plugin saakka ja hyppää sitten tähän, missä olet nyt. Tervetuloa, aloitetaan!

Drupal-modulit asennetaan composer -työkalulla. Aja:

composer require 'drupal/search_api_typesense'

Kun moduli on asentunut, kytke se päälle joko sivuston käyttöliittymästä tai aja:

drush en search_api_typesense

Moduli tarjoaa ohjeistukseksi videon, jossa käydään läpi konfigurointi: https://youtu.be/RSLach_OLqE Siinä ei kuitenkaan selitetä mitään, joten alla on selostetut ohjeet aiheesta. Kannattaa silti katsoa tuo video ensin läpi, niin saat kokonaiskuvan prosessista.

TypeSensen konfiguraatio löytyy kohdasta Asetukset > Haku ja metadata > Search API.

Aloita klikkaamalla + Add server.

Määritä serverin nimi (voi olla mikä vaan, paitsi Localhost). Tässä tapauksessa TypeSense-serveri pyöri ddev-ympäristössä, joten API-key on ddev. Normaalisti tähän tulee ohjeissa aiemmin luotu API-avain.

Tähän tulee tiedot siitä, missä Drupal-sivusto itsessään sijaitsee. Protocol on aina https, muut arvot tilanteen mukaan.

Tähän taas tiedot siitä, missä TypeSense-instanssi on, eli sama domain ja portti, jota containerin asetuksissa käytettiin aikaisemmin tässä ohjeessa. Huomaa, että Isäntä-kenttään ei pidä laittaa protokollaa, koska moduli lisää sen automaattisesti Public protocol -valinnan perusteella.

Palaa sitten sivulle Asetukset > Haku ja metadata > Search API ja klikkaa Add index.

Indeksin nimi voi olla mikä vain. Valitse mitä kaikkea indeksiin tallennetaan. Yleensä Content riittää.

Kun valittuna on Content, valitaan vielä, mitkä sisältötyypit otetaan mukaan / jätetään pois.

Valitse halutut kielet.

Valitse, mihin instanssille indeksi kuuluu. Voit halutessasi myös lukita indeksin, jolloin sisältöä ei enää lisätä/muokata.

Klikkaa Save and add fields.

Valitse kaikki ne kentät (tai alakentät), jotka haluat mukaan indeksiin, ja tallenna.

Kun olet valinnut kentät, vaihda tyypiksi “Typesense:”-alkuinen versio datatyypistä. Klikkaa sitten Save changes.

Sinun pitäisi nähdä tallentamisen jälkeen tällainen nosto. Klikkaa Schema tab -linkkiä.

Schema tab -sivulla voit säätää jokaisen valitsemasi kentän asetuksia. Lähtökohtaisesti mitään ei tarvitse muuttaa, mutta esim. Facet tai Valinnainen voivat joskus olla tarpeen. Esim. tässä tapauksessa Sisältö-kenttää ei ole kaikissa valituissa sisältötyypeissä, joten sen kohdalla on valittava Valinnainen, jotta indeksointi menee läpi. Klikkaa lopuksi Tallenna.

Sen jälkeen pääset indeksointi-sivulle, jonka alalaidassa voit käynnistää indeksoinnin. Jos kaikki sujuu kuten pitää, valitsemasi data indeksoidaan.

Tämän jälkeen voit lisätä TypeSense-haun sivuille modulin tarjoaman lohkon avulla. Sekä lohko että tulokset vaativat jonkin verran työstöä, jotta niistä saa kivan näköiset. Kuvassa ei ole nähty asian eteen juurikaan vaivaa, mutta sinä olet viitsivämpi ihminen ja pystyt siihen!

Indeksin optimointi — synonyymit

Voit halutessasi myös luoda hakuihin synonyymeja. Asiasta on selitetty tarkemmin täällä: https://typesense.org/docs/29.0/api/synonyms.html, mutta tässä perusidea.

Voit luoda kahdenlaisia synonyymeja: yhdensuuntaisia ja monensuuntaisia. Nimensä mukaisesti yhdensuuntaiset toimivat vain yhteen suuntaan (“älypuhelin” hakee myös termeillä “android” ja “iphone”, mutta “android” ei hae termillä “iphone”) kun taas monensuuntaisessa kaikki parametrit hakevat kaikilla muilla (“takki”, “nuttu”, “parka” -synonyymit hakisivat kaikilla noilla sanoilla, kun mitä tahansa niistä käytetään).

Tässä esimerkit kummastakin ylläolevan linkin takaa:

Monensuuntainen:

curl "http://localhost:8108/collections/products/synonyms/coat-synonyms" -X PUT \

-H "Content-Type: application/json" \

-H "X-TYPESENSE-API-KEY: ********************" -d '{

  "synonyms": ["blazer", "coat", "jacket"]

}'

Yhdensuuntainen:

curl "http://localhost:8108/collections/products/synonyms/smart-phone-synonyms" -X PUT \

-H "Content-Type: application/json" \

-H "X-TYPESENSE-API-KEY: ********************" -d '{

    "root": "smart phone",

    "synonyms": ["iphone", "android"]

}'

Indeksin ylläpito

Useimmat järjestelmät tarvitsevat ylläpitoa toimiakseen (paitsi jos tehdään kerralla hyvä). Tässä muutama näppärä komento:

curl http://localhost:8108/health #näyttää indeksin tilan

curl http://localhost:8108/metrics.json -H "x-typesense-api-key: ********************" #näyttää kontin tietoja mm. muistiin ja CPU-arvoihin liittyen

curl http://localhost:8108/stats.json -H "x-typesense-api-key: ********************" #näyttää tietoja mm. välimuistista, hauista ja latenssista

Lopuksi

Ensimmäinen integraatio TypeSenseen voi olla vaivalloinen, etenkin jos pystyttää myös TypeSense-instanssin itse. Kun homman on kertaalleen tehnyt, siitä tulee jatkossa helpompaa, ihan jo siksikin, että kontin ja Drupalin osalta konfiguraatiotiedostoja voi käyttää uudelleen ja tietysti prosessi nopeutuu sitä mukaa, kun se tulee tutummaksi.

Pienellä sivustolla tällaiselle ei toki ole tarvetta, mutta kun sisältömäärä kasvaa, nopea ja toimiva haku on kaunis asia eikä maailmassa ole koskaan liikaa kauniita asioita.