From 7daffb1770255701e0aaecbc33e1fce1c17309fd Mon Sep 17 00:00:00 2001 From: Samuel Allan Date: Tue, 20 Jan 2026 16:46:22 +1030 Subject: [PATCH] feat: add docs for Typesense search backend Document how to get started with the new Typesense search backend, and some tips about clustered Typesense and using a web dashboard. Private-ref: https://tasks.opencraft.com/browse/BB-10458 --- .../how-tos/use_typesense_search_backend.rst | 180 ++++++++++++++++++ 1 file changed, 180 insertions(+) create mode 100644 source/site_ops/how-tos/use_typesense_search_backend.rst diff --git a/source/site_ops/how-tos/use_typesense_search_backend.rst b/source/site_ops/how-tos/use_typesense_search_backend.rst new file mode 100644 index 000000000..297a6b61d --- /dev/null +++ b/source/site_ops/how-tos/use_typesense_search_backend.rst @@ -0,0 +1,180 @@ +.. _Use Typesense search backend: + +Use Typesense search backend +############################ + +.. tags:: site operator, how-to + +.. warning:: + + Typesense search support as discussed below has not been released yet; it is planned for the Verawood release. + +`Typesense `_ is a high performance search engine, +supported on the Open edX platform in the following search areas: + +* Course info (course search on the Discover New page) +* Courseware (course content search) +* Forum (threads and comments) + +This is an alternative to the default search backend, Meilisearch. + +**You may wish to select Typesense here if you require high availability (HA) for the search backend**. +Typesense supports high availability out of the box, while Meilisearch does not (at least for the self hosted version). + +Please note that either way, Meilisearch will still be required for Studio course content search; that does not yet have support for Typesense. + +Getting started +*************** + +See below for how to start using Typesense with your Open edX instance, depending on whether you use Tutor or not: + +Tutor +===== + +If you use Tutor, you can install the `tutor-contrib-typesense`_ +plugin, which will automatically deploy a single node Typesense instance +and configure the platform to use it. + +.. note:: + + This plugin does not support deploying Typesense as a HA cluster. If you require a cluster, please follow the manual configuration section below. + +#. Install the plugin: + + .. code-block:: shell + + pip install -e https://github.com/open-craft/tutor-contrib-typesense + tutor plugins enable typesense + +#. Configure if required. For most cases, the defaults will be fine. Available configuration is documented on `the plugin's readme `_. + + If you require custom configuration, set them using Tutor, for example: + + .. code-block:: shell + + tutor config save --set TYPESENSE_COLLECTION_PREFIX=my_instance_ + +#. Initialise the plugin - some examples: + + .. code-block:: shell + + # if an existing k8s deployment + tutor k8s do init --limit=typesense + + # if launching a devstack + tutor dev launch + +#. Reindex content - if this is an existing deployment with content already, you will need to manually run a reindex (the Typesense indexes are created automatically): + + .. code-block:: shell + + # reindex courseware content and course info + tutor dev exec cms -- python manage.py cms reindex_course --active + + # reindex forum threads and comments + tutor dev exec lms -- python manage.py lms rebuild_forum_indices + +#. Finally, to enable course content search on the frontend, create and enable a waffle flag named ``courseware.mfe_courseware_search``. You can do this from the LMS Django admin page, waffle flags section. + +Manual configuration +==================== + +If you aren't using Tutor, here are instructions for getting started manually. + +#. Deploy an instance of Typesense. See the `Typesense installation guide `_ for more information. + +#. Create an API key. See the Typesense `API Keys doc `_ for more information. + Optionally, for extra security, you can scope the API key permissions to a custom collection prefix. This prefix can be configured for the Open edX platform in the following step (the ``TYPESENSE_COLLECTION_PREFIX`` setting). + For example: + + .. code-block:: shell + + curl -X POST 'http://localhost:8108/keys' \ + -H 'Content-Type: application/json' -H 'X-TYPESENSE-API-KEY: mysecretadminkey' \ + --data-binary '{ + "value": "mysecretapikeyvalue", + "description": "API key for my Open edX instance", + "actions": ["*"], + "collections": ["^openedx_.*"] + }' + + +#. Set the following Django settings for LMS and CMS: + + .. code-block:: python + + # Enable the Typesense backend. + TYPESENSE_ENABLED = True + + # Set the API key for authenticating to Typesense. + TYPESENSE_API_KEY = "your-secret-api-key-for-typesense" + + # Set the internal urls where the LMS/CMS can reach the Typesense API. + # If Typesense is deployed as a cluster, provide the urls to all nodes here. + TYPESENSE_URLS = ["https://typesense-1.example.com:8108", "https://typesense-2.example.com:8108"] + + # The prefix that the backend should use for all collections (you can scope the API key permissions to this prefix for security). + # This is useful if the Typesense instance is shared with other software. + TYPESENSE_COLLECTION_PREFIX = "openedx_" + + # Optional: if you need to override the forum search backend module for testing + #FORUM_SEARCH_BACKEND = "forum.search.typesense.TypesenseBackend" + + # Optional: if you need to override the course search backend module for testing + #SEARCH_ENGINE = "search.typesense.TypesenseEngine" + + +#. Reindex content - if this is an existing deployment with content already, you will need to manually run a reindex (the Typesense indexes are created automatically): + + .. code-block:: shell + + # In the CMS environment: reindex courseware content and course info + python manage.py cms reindex_course --active + + # In the LMS environment: reindex forum threads and comments + python manage.py lms rebuild_forum_indices + +#. Finally, to enable course content search on the frontend, create and enable a waffle flag named ``courseware.mfe_courseware_search``. You can do this from the LMS Django admin page, waffle flags section. + + +Clustered Typesense +******************* + +Some notes regarding running Typesense in a cluster, for a HA setup. + +* For clustered Typesense, it's best to provide urls to all the nodes to ``TYPESENSE_URLS``, rather than putting it behind a load balancer. + This allows the Typesense client to manage load balancing and fallbacks itself. +* Be careful when running a Typesense cluster on Kubernetes, as there can be issues related to how consensus is implemented and that Kubernetes pods don't necessarily have static IP addresses. See `typesense/typesense#465 `_ and `typesense/typesense#2049 `_ for more information. + + +Typesense web dashboard +*********************** + +Typesense doesn't come with an official web dashboard, +but there is a community dashboard developed at https://github.com/bfritscher/typesense-dashboard. +You can visit it directly on the web without installing at https://bfritscher.github.io/typesense-dashboard/. + +For example, to connect to a Typesense server from a local Tutor devstack using the Typesense plugin, +visit the web dashboard url, and enter the following details at the login screen: + +* Api Key: (use the output from running ``tutor config printvalue TYPESENSE_API_KEY``) +* protocol: ``http`` +* host: ``localhost`` +* port: ``8108`` +* path: (leave blank) + + +.. seealso:: + + :ref:`Enable edX Search` + + +**Maintenance chart** + ++--------------+-------------------------------+----------------+--------------------------------+ +| Review Date | Working Group Reviewer | Release | Test situation | ++--------------+-------------------------------+----------------+--------------------------------+ +| 2026-01-21 | Samuel Allan | master | Pass | ++--------------+-------------------------------+----------------+--------------------------------+ + +.. _tutor-contrib-typesense: https://github.com/open-craft/tutor-contrib-typesense/