Installation¶

Two things to install:

an Elasticsearch node, with the analysis-icu plugin;
the dots-es-cli package itself, which provides the indexing CLI (dots-es-cli) and the search API (dots-api).

1. Elasticsearch¶

The application needs an Elasticsearch node in version 8.12 or later, matching the client pinned in requirements.txt.

Install Elasticsearch¶

If your organisation already runs an Elasticsearch service, use it and skip straight to the ICU plugin below. Otherwise, install a node by following the official instructions for your platform — package repositories, archive or container:

→ Install Elasticsearch 8.12 (official documentation)

Check that the node answers:

curl http://localhost:9200

Install the ICU plugin¶

The folding analyzer declared in _global.conf.json uses icu_folding, so the analysis-icu plugin is mandatory — without it, index creation fails.

Warning

Run the commands below outside your virtual environment (deactivate first).

Existing installationDocker

Check whether ICU is already available:

uconv -V

Otherwise install the plugin:

path/to/elasticsearch_folder/bin/elasticsearch-plugin install analysis-icu

On a containerised node — replace dots-es with your container name:

docker exec dots-es bash -c "bin/elasticsearch-plugin install analysis-icu"
docker restart dots-es

2. Install `dots-es-cli`¶

The package is not published on PyPI: install it from the repository.

cd path/to/projects_folder/
git clone https://github.com/dots-suite/dots-cli-es.git
cd dots-cli-es

Make sure you are on Python 3.12, for example with pyenv:

pyenv shell 3.12

Create the virtual environment and install:

python3 -m venv your_venv_name
source your_venv_name/bin/activate
pip install .   # (use dev install below to update TARGET_COLLECTION to index)

This installs the dots_es package plus the dots-es-cli and dots-api console scripts.

A plain install freezes the YAML configuration

pip install . copies the package into site-packages, config/*.yml included — and that is the copy the CLI reads. Editing dots_es/config/local.yml in your clone to change TARGET_COLLECTION, the excluded collections or the DTS endpoint would then have no effect.

Use the editable install below if you need to adjust the configuration, or reinstall after every change.

For development (editable install and dev tooling):

pip install -e . -r requirements-dev.txt

requirements*.txt are generated

Dependencies are declared in pyproject.toml and compiled with pip-tools. Do not edit the requirement files by hand:

pip-compile pyproject.toml -o requirements.txt
pip-compile --extra dev pyproject.toml -o requirements-dev.txt

3. ThunderDots from a local checkout (optional)¶

thunderdots is a runtime dependency of the indexing CLI, pulled from PyPI by default. To develop against a local clone, install it in editable mode after the normal install:

pip install -e . -r requirements-dev.txt
pip install -e path/to/ThunderDots

Changes in the local repository then take effect immediately, without reinstalling.

Version specifier

The local version must satisfy the specifier declared in pyproject.toml (currently thunderdots>=0.1.dev,<0.2). A strict pin such as ==0.1.6 would conflict with a development snapshot like 0.1.dev37.

Verify which copy is in use:

pip show thunderdots

4. uWSGI (servers only)¶

For servers running Python apps behind Nginx:

pip list --local          # is uWSGI already there?
pip install uwsgi         # may require: pip install wheel

The WSGI application is flask_app:flask_app.

Next step¶

Head to the Quick start, or read the Configuration page first if you need to point the CLI at a different DTS endpoint.