Skip to content

About

A repo dedicated to building Elasticsearch plugins.

Resources

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

Elastic Source - Elasticsearch Plugin Development Infrastructure

A production-grade development environment for building and testing Elasticsearch plugins with deep Lucene-level customization.

Overview

This repository provides a modular infrastructure for developing Elasticsearch plugins. It supports:

  • Custom analysis components (tokenizers, token filters)
  • Custom query semantics and Lucene query rewriting
  • SpanQuery and payload-based logic
  • Query-time behavior dependent on analysis attributes

Quick Start

Prerequisites

  • Java 21 (matches Elasticsearch 8.15.0 requirements)
  • Docker and Docker Compose
  • Gradle (wrapper included)

One-Command Run

Build the plugin, create a Docker image, and start Elasticsearch + Kibana:

./gradlew run

Or on gradle tasts: elastic-source/Tasks/application/run

This will:

  1. Build all submodules
  2. Package the plugin as a ZIP
  3. Build a Docker image with the plugin installed
  4. Start Elasticsearch on http://localhost:9200
  5. Start Kibana on http://localhost:5601

Manual Steps

If you prefer to run steps individually:

# Build the plugin
./gradlew pluginBuild

# Build Docker image
./gradlew dockerBuild

# Start services
./gradlew dockerUp

# View logs
./gradlew dockerLogs

# Stop services
./gradlew dockerDown

Architecture

  • Modular by Capability: Each submodule under source/ represents a logical capability
  • Single Plugin Entrypoint: Only source/search is the Elasticsearch plugin entrypoint
  • Classic Plugin Model: Outputs a ZIP-based Elasticsearch plugin with plugin-descriptor.properties

Development Workflow

  1. Add a new module: Create a directory under source/ and under the correct submodule with a build.gradle.kts
  2. Add to plugin: If it's a library module, add it as a dependency in source/search/build.gradle.kts
  3. Register components: Add token filters/queries in ElasticSourcePlugin.java
  4. Test: Run ./gradlew run and test via _analyze or _search APIs

Testing the Plugin

Once Elasticsearch is running:

# Check plugin is installed
curl http://localhost:9200/_cat/plugins?v

# Test analysis
curl -X POST "http://localhost:9200/_analyze" -H 'Content-Type: application/json' -d'
{
  "tokenizer": "standard",
  "filter": ["xtype"],
  "text": "xray test xyz"
}'

# Create an index with the custom analyzer
curl -X PUT "http://localhost:9200/test_index" -H 'Content-Type: application/json' -d'
{
  "settings": {
    "analysis": {
      "analyzer": {
        "xtype_analyzer": {
          "tokenizer": "standard",
          "filter": ["xtype"]
        }
      }
    }
  }
}'

Troubleshooting

Build Issues

  • Ensure Java 21 is installed and JAVA_HOME is set correctly
  • Check that Docker is running
  • Verify Elasticsearch version compatibility in gradle.properties

Docker Issues

  • Check logs: ./gradlew dockerLogs
  • Ensure ports 9200 and 5601 are not in use
  • Try: ./gradlew dockerDown then ./gradlew dockerUp

Plugin Not Loading

  • Verify the plugin ZIP was built: ls -la build/distributions/
  • Check Elasticsearch logs in Docker: docker logs elasticsearch-plugin-lab
  • Ensure plugin version matches Elasticsearch version

About

A repo dedicated to building Elasticsearch plugins.

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages