This repo shows how to integrate VIND in Spring Boot applications. It is not about the functionality of VIND itself, which is exhaustively described in the repo and the linked feature documentation. It contains a simple demo application including some best practices regarding development, testing, dependency management etc.
The demo shows how to create a simple search scenario using VIND. It indexes 3 documents on a local solr server and provides a simple API to issue queries.
- start local vind server:
docker-compose up - start application
./gradlew bootRun
The search webservice is described via Open API spec. Some simple request:
- Search for
first:curl -X GET "http://localhost:8080/search?q=first&limit=10" -H "accept: application/json" - Search for articles of the last 24 hours:
curl -X GET "http://localhost:8080/search?range=PAST_DAY&limit=10" -H "accept: application/json" - Search for articles with tag
cat:curl -X GET "http://localhost:8080/search?tag=cat&limit=10" -H "accept: application/json"
If you use VIND you use (currently) Solr, which mean that you have to deal with some Spring Magic (as Spring Boot has some support of Solr as well, which leads to version conflicts). Therefore:
- force the VIND related solr-core and solrj-core version (you can look this up in the VIND github repo easily)
- exclude Solr Auto Configuration for the application
@SpringBootApplication(exclude = SolrAutoConfiguration.class) - try to use embedded solr server with caution (see the paragraph about testing)
The simplest way to use a VIND search server is to outcheck a bean, like in VindConfiguration. In the demo case a local search server is linked.
The easiest way to run a local VIND server is to use the vind docker image.
The repository includes a docker-compose file that starts a solr server on localhost:8983/solr and creates a vind core named localdocs.
VIND includes a collection management tool, that allows to create and update vind collections with a single command line call. The tool is described here.
The demo shows how to index articles by using a simple document factory. Here the fields that are used for indexing are defined. In addition helper functions for mapping from and to VIND documents are implemented. The indexing istelf is triggered in application start (in the main).
The search is encapsulated in a service. The example shows how to use fulltext search, filters (term and time range) and how to generate facets.
A simple unit test is shown here. VIND provides a embedded server for testing. But be aware that you might end up in dependency hell if you want to use it for more complex test (that uses Spring Boot context e.g.). Therefore we suggest to use testcontainers.
In a special test we show how a specific VIND testcontainer (based on Docker testcontainers) can be used as a proper VIND backend for integration tests. This is the preferable usage, as there are quite some dependency issues with Embedded Solr and Spring Boot, as already mentioned. If you want to try the test and on mac, please be sure that docker is running. Note, that the testcontainer is currently only available as snapshot, but there will be a release soon.
In order to check the health of the VIND endpoint you can use the VIND built in status check and expose it as health indicator. In the demo you can check the endpoint on http://localhost:8082/actuator/health.