Skip to content

Build all single version Docker images with Lunr

Sarah German requested to merge single-images-lunr-search into main

What does this MR do and why?

We currently build multiple versions of the site with Google search. Right now, that's these copies of the site:

All versions that run on the archives site are built with Lunr.js for search. To facilitate this, we currently create two Docker images for each archived version (one with Google search, one with Lunr search).

This was never ideal because search result links for 17.4, 17.3, and 17.2 (in this example) link to the pre-release/latest docs. We were never able to index non-latest Docs with Google, but we decided that Google search was still the best option for these instances because the docs would be close enough, and the result quality is better than Lunr.

However, we are wiser now, and there are more benefits to only building archive versions with Lunr:

  • Simpler logic in our versioning code (no need to pass SEARCH_BACKEND or API keys as build args)
    • The way we passed API keys would've been problematic if we ever changed that key. No way to update packaged versions people have already downloaded. Any image that a customer runs themselves should not rely on third-party services like that.
  • Fewer Docker images to create/support (only 1 per release, rather than 1 google + 1 lunr per release)
  • Links in search results always stay within their version. Better UX.

While it is possible to index individual versions with Elastic, we are not pursuing that at this time. We can reconsider if result quality within archived versions becomes a priority.

Closes #1674 (closed)

How to set up and validate locally

Numbered steps to set up and validate the change are strongly suggested.

  1. Configure a local GitLab Docs environment: https://gitlab.com/gitlab-org/gitlab-docs/-/blob/main/doc/setup.md.
  2. Simulate creating a new archive release:
    • Create a Dockerfile from the template: cp dockerfiles/single.Dockerfile 17.4.Dockerfile (normally release.rake does this)
    • Edit line 8 to include the version: ARG VER=17.4 (normally release.rake does this)
    • Build the image: docker build -t docs:17.4 -f 17.4.Dockerfile . --build-arg VER=17.4 (this takes 15-20 min)
    • Run the image: docker run -it --rm -p 4000:4000 docs:17.4
    • Visit the new site at http://localhost:4000/17.4/

The resulting site should use Lunr for search, search should work (returns results; result links have the right paths), and should not throw errors during the build.

Merge request acceptance checklist

This checklist encourages us to confirm any changes have been analyzed to reduce risks in quality, performance, reliability, security, and maintainability.

Edited by Sarah German

Merge request reports