A production-grade development environment for building and testing Elasticsearch plugins with deep Lucene-level customization.
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
- Java 21 (matches Elasticsearch 8.15.0 requirements)
- Docker and Docker Compose
- Gradle (wrapper included)
Build the plugin, create a Docker image, and start Elasticsearch + Kibana:
./gradlew runOr on gradle tasts: elastic-source/Tasks/application/run
This will:
- Build all submodules
- Package the plugin as a ZIP
- Build a Docker image with the plugin installed
- Start Elasticsearch on
http://localhost:9200 - Start Kibana on
http://localhost:5601
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- Modular by Capability: Each submodule under
source/represents a logical capability - Single Plugin Entrypoint: Only
source/searchis the Elasticsearch plugin entrypoint - Classic Plugin Model: Outputs a ZIP-based Elasticsearch plugin with
plugin-descriptor.properties
- Add a new module: Create a directory under
source/and under the correct submodule with abuild.gradle.kts - Add to plugin: If it's a library module, add it as a dependency in
source/search/build.gradle.kts - Register components: Add token filters/queries in
ElasticSourcePlugin.java - Test: Run
./gradlew runand test via_analyzeor_searchAPIs
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"]
}
}
}
}
}'- Ensure Java 21 is installed and
JAVA_HOMEis set correctly - Check that Docker is running
- Verify Elasticsearch version compatibility in
gradle.properties
- Check logs:
./gradlew dockerLogs - Ensure ports 9200 and 5601 are not in use
- Try:
./gradlew dockerDownthen./gradlew dockerUp
- 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