Skip to content

Installation

Two things to install:

  1. an Elasticsearch node, with the analysis-icu plugin;
  2. 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).

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 .

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

The configuration stays in your clone

The YAML files are not copied into site-packages: they are read from the config/ directory of the checkout, on every invocation. Editing config/local.yml to change TARGET_COLLECTION, the excluded collections or the DTS endpoint takes effect immediately, with no reinstall — a plain pip install . is enough.

dots-es-cli [--config local|staging|prod] index

Run the commands from the root of the checkout, which is where config/ sits.

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.