Skip to content

Commit 79638e6

Browse files
samuelallan72sarina
samuelallan72
authored and
sarina
committed
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
1 parent 5a07858 commit 79638e6

1 file changed

Lines changed: 180 additions & 0 deletions

File tree

‎source/site_ops/how-tos/use_typesense_search_backend.rst‎

Lines changed: 180 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,180 @@
1+
.. _Use Typesense search backend:
2+
3+
Use Typesense search backend
4+
############################
5+
6+
.. tags:: site operator, how-to
7+
8+
.. warning::
9+
10+
Typesense search support as discussed below has not been released yet; it is planned for the Verawood release.
11+
12+
`Typesense <https://typesense.org/>`_ is a high performance search engine,
13+
supported on the Open edX platform in the following search areas:
14+
15+
* Course info (course search on the Discover New page)
16+
* Courseware (course content search)
17+
* Forum (threads and comments)
18+
19+
This is an alternative to the default search backend, Meilisearch.
20+
21+
**You may wish to select Typesense here if you require high availability (HA) for the search backend**.
22+
Typesense supports high availability out of the box, while Meilisearch does not (at least for the self hosted version).
23+
24+
Please note that either way, Meilisearch will still be required for Studio course content search; that does not yet have support for Typesense.
25+
26+
Getting started
27+
***************
28+
29+
See below for how to start using Typesense with your Open edX instance, depending on whether you use Tutor or not:
30+
31+
Tutor
32+
=====
33+
34+
If you use Tutor, you can install the `tutor-contrib-typesense`_
35+
plugin, which will automatically deploy a single node Typesense instance
36+
and configure the platform to use it.
37+
38+
.. note::
39+
40+
This plugin does not support deploying Typesense as a HA cluster. If you require a cluster, please follow the manual configuration section below.
41+
42+
#. Install the plugin:
43+
44+
.. code-block:: shell
45+
46+
pip install -e https://github.com/open-craft/tutor-contrib-typesense
47+
tutor plugins enable typesense
48+
49+
#. Configure if required. For most cases, the defaults will be fine. Available configuration is documented on `the plugin's readme <https://github.com/open-craft/tutor-contrib-typesense?tab=readme-ov-file#configuration>`_.
50+
51+
If you require custom configuration, set them using Tutor, for example:
52+
53+
.. code-block:: shell
54+
55+
tutor config save --set TYPESENSE_COLLECTION_PREFIX=my_instance_
56+
57+
#. Initialise the plugin - some examples:
58+
59+
.. code-block:: shell
60+
61+
# if an existing k8s deployment
62+
tutor k8s do init --limit=typesense
63+
64+
# if launching a devstack
65+
tutor dev launch
66+
67+
#. 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):
68+
69+
.. code-block:: shell
70+
71+
# reindex courseware content and course info
72+
tutor dev exec cms -- python manage.py cms reindex_course --active
73+
74+
# reindex forum threads and comments
75+
tutor dev exec lms -- python manage.py lms rebuild_forum_indices
76+
77+
#. 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.
78+
79+
Manual configuration
80+
====================
81+
82+
If you aren't using Tutor, here are instructions for getting started manually.
83+
84+
#. Deploy an instance of Typesense. See the `Typesense installation guide <https://typesense.org/docs/guide/install-typesense.html>`_ for more information.
85+
86+
#. Create an API key. See the Typesense `API Keys doc <https://typesense.org/docs/latest/api/api-keys.html>`_ for more information.
87+
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).
88+
For example:
89+
90+
.. code-block:: shell
91+
92+
curl -X POST 'http://localhost:8108/keys' \
93+
-H 'Content-Type: application/json' -H 'X-TYPESENSE-API-KEY: mysecretadminkey' \
94+
--data-binary '{
95+
"value": "mysecretapikeyvalue",
96+
"description": "API key for my Open edX instance",
97+
"actions": ["*"],
98+
"collections": ["^openedx_.*"]
99+
}'
100+
101+
102+
#. Set the following Django settings for LMS and CMS:
103+
104+
.. code-block:: python
105+
106+
# Enable the Typesense backend.
107+
TYPESENSE_ENABLED = True
108+
109+
# Set the API key for authenticating to Typesense.
110+
TYPESENSE_API_KEY = "your-secret-api-key-for-typesense"
111+
112+
# Set the internal urls where the LMS/CMS can reach the Typesense API.
113+
# If Typesense is deployed as a cluster, provide the urls to all nodes here.
114+
TYPESENSE_URLS = ["https://typesense-1.example.com:8108", "https://typesense-2.example.com:8108"]
115+
116+
# The prefix that the backend should use for all collections (you can scope the API key permissions to this prefix for security).
117+
# This is useful if the Typesense instance is shared with other software.
118+
TYPESENSE_COLLECTION_PREFIX = "openedx_"
119+
120+
# Optional: if you need to override the forum search backend module for testing
121+
#FORUM_SEARCH_BACKEND = "forum.search.typesense.TypesenseBackend"
122+
123+
# Optional: if you need to override the course search backend module for testing
124+
#SEARCH_ENGINE = "search.typesense.TypesenseEngine"
125+
126+
127+
#. 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):
128+
129+
.. code-block:: shell
130+
131+
# In the CMS environment: reindex courseware content and course info
132+
python manage.py cms reindex_course --active
133+
134+
# In the LMS environment: reindex forum threads and comments
135+
python manage.py lms rebuild_forum_indices
136+
137+
#. 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.
138+
139+
140+
Clustered Typesense
141+
*******************
142+
143+
Some notes regarding running Typesense in a cluster, for a HA setup.
144+
145+
* For clustered Typesense, it's best to provide urls to all the nodes to ``TYPESENSE_URLS``, rather than putting it behind a load balancer.
146+
This allows the Typesense client to manage load balancing and fallbacks itself.
147+
* 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 <https://github.com/typesense/typesense/issues/465>`_ and `typesense/typesense#2049 <https://github.com/typesense/typesense/issues/2049>`_ for more information.
148+
149+
150+
Typesense web dashboard
151+
***********************
152+
153+
Typesense doesn't come with an official web dashboard,
154+
but there is a community dashboard developed at https://github.com/bfritscher/typesense-dashboard.
155+
You can visit it directly on the web without installing at https://bfritscher.github.io/typesense-dashboard/.
156+
157+
For example, to connect to a Typesense server from a local Tutor devstack using the Typesense plugin,
158+
visit the web dashboard url, and enter the following details at the login screen:
159+
160+
* Api Key: (use the output from running ``tutor config printvalue TYPESENSE_API_KEY``)
161+
* protocol: ``http``
162+
* host: ``localhost``
163+
* port: ``8108``
164+
* path: (leave blank)
165+
166+
167+
.. seealso::
168+
169+
:ref:`Enable edX Search`
170+
171+
172+
**Maintenance chart**
173+
174+
+--------------+-------------------------------+----------------+--------------------------------+
175+
| Review Date | Working Group Reviewer | Release | Test situation |
176+
+--------------+-------------------------------+----------------+--------------------------------+
177+
| 2026-01-21 | Samuel Allan | master | Pass |
178+
+--------------+-------------------------------+----------------+--------------------------------+
179+
180+
.. _tutor-contrib-typesense: https://github.com/open-craft/tutor-contrib-typesense/

0 commit comments

Comments
 (0)