feat: port to Typesense

Port the Meilisearch plugin from
https://github.com/open-craft/tutor-contrib-meilisearch to
Typesense. For now, only add support for an internally managed, single
node Typesense server. Support for an external Typesense server or
a clustered Typesense server group is being discussed.

Also make some updates to related dev environment files: update the
Makefile, add a mise.toml for convenience of setting up an virtual env,
add a CI workflow, and some other small updates.

Private-ref: https://tasks.opencraft.com/browse/BB-9972

Author: samuelallan72

.github/workflows/test.yml

@@ -0,0 +1,31 @@
+name: Run tests
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+
+jobs:
+  tests:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+         python-version: ['3.11', '3.12']
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "${{ matrix.python-version }}"
+
+      - name: Install dependencies
+        run: |
+          # Shellcheck is already installed in the system by default.
+          # Install python dependencies:
+          make install
+
+      - name: Run tests
+        run: make test

.gitignore

@@ -1,8 +1,2 @@
-.DS_Store
-.*.swp
-!.gitignore
-TODO
 __pycache__
 *.egg-info/
-/build/
-/dist/

MANIFEST.in

@@ -1,2 +1,2 @@
-recursive-include tutor_meili/patches *
-recursive-include tutor_meili/templates *
+recursive-include tutor_typesense/patches *
+recursive-include tutor_typesense/templates *

Makefile

@@ -1,31 +1,21 @@
 .DEFAULT_GOAL := help
-.PHONY: docs
-SRC_DIRS = ./tutor_meili
-BLACK_OPTS = --exclude templates ${SRC_DIRS}
+.PHONY: test install format lint help
 
-# Warning: These checks are not necessarily run on every PR.
-test: test-lint test-types test-format  # Run some static checks.
+test: lint  ## Run all tests
 
-test-format: ## Run code formatting tests
-	black --check --diff $(BLACK_OPTS)
+install: ## Install python dependencies (it's recommended to activate a virtualenv first)
+	pip install -e .[dev]
+	@which shellcheck > /dev/null || (echo "'shellcheck' is not available. Please manually install shellcheck to run tests." && exit 1)
 
-test-lint: ## Run code linting tests
-	pylint --errors-only --enable=unused-import,unused-argument --ignore=templates --ignore=docs/_ext ${SRC_DIRS}
-
-test-types: ## Run type checks.
-	mypy --exclude=templates --ignore-missing-imports --implicit-reexport --strict ${SRC_DIRS}
+lint: ## Run code linting tests
+	black --check --diff tutor_typesense
+	pylint --errors-only --enable=unused-import,unused-argument --ignore=templates --ignore=docs/_ext tutor_typesense
+	mypy --exclude=templates --ignore-missing-imports --implicit-reexport --strict tutor_typesense
+	shellcheck tutor_typesense/templates/typesense/tasks/typesense/init.sh
 
 format: ## Format code automatically
-	black $(BLACK_OPTS)
-
-isort: ##  Sort imports. This target is not mandatory because the output may be incompatible with black formatting. Provided for convenience purposes.
-	isort --skip=templates ${SRC_DIRS}
-
-changelog-entry: ## Create a new changelog entry.
-	scriv create
-
-changelog: ## Collect changelog entries in the CHANGELOG.md file.
-	scriv collect
+	isort tutor_typesense
+	black tutor_typesense
 
 ESCAPE = 
 help: ## Print this help

README.rst

@@ -1,80 +1,87 @@
-Meilisearch for Open edX (Tutor Plugin)
+Typesense for Open edX (Tutor Plugin)
 =======================================
 
-This is a plugin for `Tutor <https://docs.tutor.edly.io>`_ 18 (Open edX "Redwood" release) that provides Meilisearch to the platform, so it can be used as a search engine to power content search.
-
-⭐️ This plugin isn't needed with Tutor 19+ (Open edX Sumac+), as `Meilisearch functionality is now built in <https://github.com/overhangio/tutor/pull/1141>`_. ⭐️ 
+This is a plugin for `Tutor <https://docs.tutor.edly.io>`_ 20 (Open edX "Teak" release) that provides Typesense to the platform, so it can be used as a search engine to power content search.
 
 Installation
 ------------
 
 Currently, you need to clone this repo from GitHub then install it into your tutor virtual environment with::
 
-    pip install -e ./tutor-contrib-meilisearch
+    pip install -e ./tutor-contrib-typesense
 
 Then, to enable this plugin, run::
 
-    tutor plugins enable meilisearch
+    tutor plugins enable typesense
 
 If you have an already running platform, initialize this plugin with a command like the following::
 
-    tutor [local|dev|k8s] do init --limit=meilisearch
+    tutor [local|dev|k8s] do init --limit=typesense
 
 Or use ``tutor [local|dev|k8s] launch -I`` to re-launch the platform (takes much longer).
 
 Configuration
 -------------
 
-- ``MEILISEARCH_INDEX_PREFIX`` (default: ``"tutor_"``)
-- ``MEILISEARCH_PUBLIC_HOST`` (default: ``"meilisearch.{{ LMS_HOST }}"``)
-- ``MEILISEARCH_DOCKER_IMAGE`` (default: ``"docker.io/getmeili/meilisearch:v1.8``)
-- ``MEILISEARCH_MASTER_KEY`` The master key. Only required to generate the API key (default: auto-generated).
-- ``MEILISEARCH_API_KEY`` The API key (or tenant key) to use for this Open edX instance (default: auto-generated using the master key).
+- ``TYPESENSE_COLLECTION_PREFIX`` (default: ``"tutor_"``)
+- ``TYPESENSE_PUBLIC_HOST`` (default: ``"typesense.{{ LMS_HOST }}"``)
+- ``TYPESENSE_DOCKER_IMAGE`` (default: ``"docker.io/typesense/typesense:29.0"``)
+- ``TYPESENSE_BOOTSTRAP_API_KEY`` The initial admin API key to use when bootstrapping the Typesense server and to generate an api key for Open edX (default: auto-generated).
+- ``TYPESENSE_API_KEY`` The API key used by Open edX (default: auto-generated).
 
 These values can be modified with ``tutor config save --set PARAM_NAME=VALUE`` commands.
 
+Limitations
+-----------
+
+It's not recommended to run high availability (clustered) Typesense on Kubernetes. 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.
+
+This plugin does not support deploying a clustered Typesense server.
+
 Upgrading
 ---------
-If you upgrade this plugin or change the ``MEILISEARCH_DOCKER_IMAGE`` setting, you may get a new version of Meilisearch.
-In that case, the ``meilisearch`` Docker service will fail to start because the index format is from an older version.
-For large instances, you can follow the `Meilisearch update procedure <https://www.meilisearch.com/docs/learn/update_and_migration/updating#updating-a-self-hosted-meilisearch-instance>`_
-(basically, dump the index contents to a file, upgrade it, then restore from the data dump file). For development and
-smaller installations, the easier way is to follow this procedure::
+If you upgrade this plugin or change the ``TYPESENSE_DOCKER_IMAGE`` setting, you may get a new version of Typesense.
+According to `Typesense docs on updating <https://typesense.org/docs/guide/updating-typesense.html#typesense-self-hosted>`_,
+this upgrade happens automatically, and no manual actions are required.
 
-    tutor [local|dev] stop meilisearch
-    cd "$(tutor config printroot)/data/meilisearch"
-    mv data.ms "data.ms.$(date +%Y-%m-%d)"
-    tutor config save
-    tutor [local|dev] start -d meilisearch
-    tutor [local|dev] do init --limit=meilisearch
+DNS records
+-----------
 
-TODO
-----
+For production use, it is assumed that the ``TYPESENSE_PUBLIC_HOST`` DNS record points to your server.
 
-Currently, this plugin always deploys a new instance of Meilisearch. It should be modified to support using an existing external instance if desired.
+In development mode, Typesense is available at http://typesense.local.openedx.io:8108.
 
-DNS records
+Troubleshooting
+---------------
+
+TBD
+
+Development
 -----------
 
-For production use, it is assumed that the ``MEILISEARCH_PUBLIC_HOST`` DNS record points to your server.
+Set up a python virtual environment, then you can install dependencies and run the tests like:
 
-In development mode, Meilisearch is available at http://meilisearch.local.edly.io:7700.
+  make install
+  make test
 
-Web UI
-------
+After making some changes, you can run the auto formatter over the code for consistency:
 
-The Meilisearch web UI can be accessed at http(s)://<MEILISEARCH_PUBLIC_HOST>. For development, this is usually http://meilisearch.local.edly.io:7700/
+  make format
 
-An API key for accessing the UI can be obtained with::
 
-  tutor config printvalue MEILISEARCH_API_KEY
+Open edX integration
+--------------------
 
-Troubleshooting
----------------
+This plugin provides the following settings to Open edX components for integration:
 
-TBD
+- (common) ``TYPESENSE_ENABLED: bool = True`` - whether the Typesense backend is enabled
+- (common) ``TYPESENSE_COLLECTION_PREFIX: str = "the_configured_collection_prefix"`` - a prefix that the backend should use for all collections (the API key is scoped to this prefix)
+- (cms, lms) ``TYPESENSE_URL: str = "http://typesense:8108"`` - the internal url for accessing the Typesense API
+- (cms, lms) ``TYPESENSE_PUBLIC_URL: str = "http://(depends on TYPESENSE_PUBLIC_HOST)"`` - the public url to the Typesense API (for user searches on the frontend)
+- (cms, lms) ``TYPESENSE_API_KEY: str = "the api key"`` - an api key for the Open edX backend to make updates to Typesense collections
+- (lms) ``MFE_CONFIG["TYPESENSE_ENABLED"]: bool = True`` - for MFE's to know when to use Typesense logic
 
 License
 -------
 
-This work is licensed under the terms of the `GNU Affero General Public License (AGPL) <https://github.com/open-craft/tutor-contrib-meilisearch/blob/master/LICENSE.txt>`_.
+This work is licensed under the terms of the `GNU Affero General Public License (AGPL) <https://github.com/open-craft/tutor-contrib-typesense/blob/master/LICENSE.txt>`_.

mise.toml

@@ -0,0 +1,7 @@
+[env]
+# --seed instructs uv to include pip, setuptools, and wheel in the resulting venv
+# useful for compatibility with other scripts that call pip
+_.python.venv = { path = "venv", create = true, uv_create_args = ['--seed'] }
+
+[tools]
+python = "3.11"

pyproject.toml

@@ -1,16 +1,13 @@
 [project]
-name = "tutor-meilisearch"
+name = "tutor-typesense"
 dynamic = ["version"]
-description = "A Tutor plugin for search using Meilisearch"
+description = "A Tutor plugin for search using Typesense"
 readme = "README.rst"
 license = { file = "LICENSE.txt" }
-requires-python = ">=3.8"
+requires-python = ">=3.11"
 authors = [
-    { name = "Braden MacDonald", email = "braden@opencraft.com" },
-    { name = "Overhang.IO", email = "contact@overhang.io" },
 ]
 maintainers = [
-    { name = "Braden MacDonald", email = "braden@opencraft.com" },
 ]
 classifiers = [
     "Development Status :: 3 - Alpha",
@@ -25,23 +22,34 @@ classifiers = [
     "Programming Language :: Python :: 3.12",
 ]
 dependencies = [
-    "tutor>=17.0.0,<19.0.0",
+    "tutor>=20.0.0,<21.0.0",  # teak
 ]
 
 [project.optional-dependencies]
 dev = [
-    "tutor[dev]>=17.0.0,<19.0.0",
+    "tutor[dev]>=20.0.0,<21.0.0",  # teak
+    "black",
+    "isort",
+    "pylint",
 ]
 
 [project.entry-points."tutor.plugin.v1"]
-meilisearch = "tutor_meili.plugin"
+typesense = "tutor_typesense.plugin"
 
 [project.urls]
-Code = "https://github.com/open-craft/tutor-contrib-meilisearch"
+Code = "https://github.com/open-craft/tutor-contrib-typesense"
 Community = "https://discuss.openedx.org"
 Documentation = "https://docs.tutor.edly.io/"
 Homepage = "https://docs.tutor.edly.io/"
-"Issue tracker" = "https://github.com/open-craft/tutor-contrib-meilisearch/issues"
+"Issue tracker" = "https://github.com/open-craft/tutor-contrib-typesense/issues"
 
 [tool.setuptools.dynamic]
-version = {attr = "tutor_meili.__about__.__version__"}
+version = {attr = "tutor_typesense.__about__.__version__"}
+
+[tool.isort]
+profile = "black"
+src_paths = ["tutor_typesense"]
+extend_skip = ["templates"]
+
+[tool.black]
+exclude = "templates"