Skip to content

Commit 062e051

Browse files
samuelallan72samuelallan72
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 5b9e601 commit 062e051

1 file changed

Lines changed: 172 additions & 0 deletions

File tree

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

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

0 commit comments

Comments
 (0)