Installation

This guide covers how to install the django-haystack-opensearch package and its dependencies.

Prerequisites

Before installing django-haystack-opensearch, ensure you have:

Python 3.11 or higher
uv, pip, or pipx

Installation Methods

From PyPI with `pip`

pip install django_haystack_opensearch

From PyPI with `uv`

sh -c "$(curl -fsSL https://astral.sh/uv/install)"
uv add django_haystack_opensearch

From PyPI with `pipx`

pipx install django_haystack_opensearch

From Source

If you want to install from the latest development version:

git clone https://github.com/caltechads/django-haystack-opensearch.git
sh -c "$(curl -fsSL https://astral.sh/uv/install)"
cd <your-project-name>
uv add file://../django_haystack_opensearch

OpenSearch Plugins

Some advanced features of django-haystack-opensearch require specific plugins to be installed on your OpenSearch node.

Ingest Attachment Plugin

The File Content Extraction feature (backend.extract_file_contents()) requires the ingest-attachment OpenSearch plugin.

Installing via docker-compose

If you are using Docker, you can automate the installation of this plugin in your docker-compose.yml by overriding the container command:

services:
  opensearch:
    image: opensearchproject/opensearch:1
    command: >
      /bin/bash -c "
        if ! bin/opensearch-plugin list | grep -q ingest-attachment; then
          bin/opensearch-plugin install --batch ingest-attachment
        fi
        /usr/share/opensearch/opensearch-docker-entrypoint.sh
      "
    # ... rest of your configuration ...

Manual Installation

You can also install it manually using the opensearch-plugin utility:

bin/opensearch-plugin install ingest-attachment

AWS OpenSearch Service

If you are using AWS OpenSearch Service, you must associate the plugin with your domain using the Packages feature:

Associate the plugin to your domain via the AWS Management Console, AWS CLI, or SDKs using the Packages feature.
Go to the Packages section in the OpenSearch Service console.
Locate the ingest-attachment package that matches your OpenSearch engine version.
Associate it with your domain. AWS will deploy the plugin and restart the domain nodes if needed.
Verify the installation by calling the plugin list API on your cluster:
```
GET _cat/plugins?v
```
You should see ingest-attachment in the list once successfully installed.

Configuration

After installation, you should to configure the library for your specific environment. See Configuration for detailed configuration options.

Getting Help

If you encounter issues during installation:

Check the GitHub issues
Review the troubleshooting section above
Ensure your Python environment meets the prerequisites
Try installing in a virtual environment to isolate dependencies