Automating Algolia Search with Azure Static Web App

2023-01-06 5 min read Hugo Thedevopscat

Having just completed the setup of algolia search on this site I felt compelled to write a new post and let you know my experience, as it may save you some time! Suffice to say, the potentially difficult part was easy, and the easy part was hard! This may be down to the combination of my (feature rich) Bilberry theme and Hugo, so if you choose this combination, This may be of particular interest.

I chose to use algolia for my search as support is built-in to the bilberry theme, and having briefly played with some local scripted alternatives, algolia seemed like the path of least resistance for my basic and initially low volume search needs.

Create an Account

I won’t go too in-depth here, this process has been documented elsewhere and is straight forward, but in summary we create a new algolia account, then create our first (empty) index, from this process we need to capture our app ID, our (search only) API key, and the name we chose for our index.

These parameters are then added to our config.toml file for our site, then we can enable algolia_search. Your setting should be along the line of the code snippet below (the appid, apikey and index name are unique to you):

…
# Enable / Disable algolia search
algolia_search = true
algolia_appId = "DOC3HO0A3S"
algolia_apiKey = "199d489edd990a99db5915d882d7232db"
algolia_indexName = "myblogindex"
# Set this option to false if you want to search within all articles in all languages at once
algolia_currentLanguageOnly = true

The Index File

You would naively hope that was it! But it turns out that a website search facility is more complex behind the scenes than a non-techie might imagine. An index needs to be created and maintained each time the site content is modified, having already automated the deployment of my site to Azure via GitHub actions, the thought of downloading more binaries to my local machine and manually running scripts to generate an index file to manually upload to the algolia website each time I make an update to the site was not something I wanted to get into, and is so not DevOps!

Consequently, rightly or wrongly, I went straight to the automation phase to add this dependency to my deployment pipeline, which I expected might be the difficult bit, but as it happened work first time! The manual process of creating/updating the index file is covered in the bilberry theme readme . All I did was refer to the GitHub action help page and integrated this additional step into my GitHub action, which for reference now looks like this:

name: Azure Static Web Apps CI/CD

on:
  push:
    branches:
      - main
  pull_request:
    types: [opened, synchronize, reopened, closed]
    branches:
      - main

jobs:
  build_and_deploy_job:
    if: github.event_name == 'push' || (github.event_name == 'pull_request' && github.event.action != 'closed')
    runs-on: ubuntu-latest
    name: Build and Deploy Job
    steps:
      - uses: actions/checkout@v3
        with:
          submodules: true
      - name: Build And Deploy
        id: builddeploy
        uses: Azure/static-web-apps-deploy@latest
        with:
          azure_static_web_apps_api_token: ${{ secrets.AZURE_STATIC_WEB_APPS_API_TOKEN }}
          repo_token: ${{ secrets.GITHUB_TOKEN }} # Used for Github integrations (i.e. PR comments)
          action: "upload"
          ###### Repository/Build Configurations - These values can be configured to match your app requirements. ######
          # For more information regarding Static Web App workflow configurations, please visit: https://aka.ms/swaworkflowconfig
          app_location: "/website/" # App source code path
          api_location: "/website/algolia/" # Api source code path - optional
          output_location: "public" # Built app content directory - optional
          api_build_command: "npm run data-upload -- -c -f ../public/index.json -a DOC3HO0A3S -k ${{ secrets.ALGOLIA_ADMIN_API_KEY }} -n myblogindex"
          ###### End of Repository/Build Configurations ######

  close_pull_request_job:
    if: github.event_name == 'pull_request' && github.event.action == 'closed'
    runs-on: ubuntu-latest
    name: Close Pull Request Job
    steps:
      - name: Close Pull Request
        id: closepullrequest
        uses: Azure/static-web-apps-deploy@latest
        with:
          azure_static_web_apps_api_token: ${{ secrets.AZURE_STATIC_WEB_APPS_API_TOKEN }}
          action: "close"

Now, when I perform a new deployment, the automated Hugo site compilation recreates a new index file and the JavaScript built-in to the theme is called to upload the index file to the algolia website to populate the live index using my algolia admin API key which is stored in GitHub as a secret for obvious reasons.

We can check this is working by going to the algolia portal, we should now see our index has been automatically populated and we can search from the algolia portal for keywords featured on our blog site and note some matches.

The Missing Link - Troubleshooting

Surely now we are done? but no(!), the search function on my site stubbornly returned no results, time for some troubleshooting…

What we know:

The pipeline ran with no errors
The index was populated and search works in the algolia portal

What I did next:

Substitute out the bilberry example site algolia settings on my local test site (this worked with their results)
Website verified, I Reverted back to my algolia settings
Checked the query logs from the algolia portal (my website searches were hitting my index but returning no results)
Considered what could be different in my setup from the example site…

From the algolia portal Search API Logs I noticed my blog site searches query request body was filtering on language and figured this was my issue:

{
  "params": "query=aaa&hitsPerPage=5&filters=language%3A%20en"
}

I verified my theory by changing the algolia_currentLanguageOnly = true setting to false in my config.toml and the search results worked immediately. This is more of a work-around rather than a fix, so I set about adding the missing settings for my index.

Launguage Setting and Filters in the Index

From the algolia portal, in the index configuration page I firstly set the index languages and query languages to English.

Then, under filtering and faceting, I added a facet for language, ignoring the unknown attribute warning encountered as some of the content lacks the language marking from my site.

I could then set algolia_currentLanguageOnly = true in my config.toml file for my site and it worked perfectly. Phew!

Conclusions

Bilberry theme has multilingual support, this may have made my search journey more complicated, always take the time to read the documentation that goes with your theme as it will likely save you some time down the line.

Automation and Github actions are great!

thedevopscat blog