|
| 1 | +# Quarkus demo: Hibernate Search Standalone + Elasticsearch and RESTEasy |
| 2 | + |
| 3 | +This is a CRUD service exposing a couple of endpoints over REST, |
| 4 | +with a front-end based on Angular so you can play with it from your browser. |
| 5 | + |
| 6 | +While the code is surprisingly simple, under the hood this is using: |
| 7 | + - RESTEasy to expose the REST endpoints |
| 8 | + - Hibernate Search Standalone + Elasticsearch to index entities in an Elasticsearch index |
| 9 | + - ArC, the CDI inspired dependency injection tool with zero overhead |
| 10 | + |
| 11 | +## Requirements |
| 12 | + |
| 13 | +To compile and run this demo you will need: |
| 14 | + |
| 15 | +- JDK 17+ |
| 16 | +- GraalVM |
| 17 | + |
| 18 | +In addition, you will need an Elasticsearch instance, or Docker to run it. |
| 19 | + |
| 20 | +### Configuring GraalVM and JDK 17+ |
| 21 | + |
| 22 | +Make sure that both the `GRAALVM_HOME` and `JAVA_HOME` environment variables have |
| 23 | +been set, and that a JDK 17+ `java` command is on the path. |
| 24 | + |
| 25 | +See the [Building a Native Executable guide](https://quarkus.io/guides/building-native-image) |
| 26 | +for help setting up your environment. |
| 27 | + |
| 28 | +## Building the demo |
| 29 | + |
| 30 | +Launch the Maven build on the checked out sources of this demo: |
| 31 | + |
| 32 | +> ./mvnw package |
| 33 | +
|
| 34 | +Note that running this command will start an Elasticsearch cluster and run the tests. |
| 35 | + |
| 36 | +## Running the demo |
| 37 | + |
| 38 | +### Live coding with Quarkus |
| 39 | + |
| 40 | +The Maven Quarkus plugin provides a development mode that supports |
| 41 | +live coding. To try this out: |
| 42 | + |
| 43 | +> ./mvnw quarkus:dev |
| 44 | +
|
| 45 | +In this mode you can make changes to the code and have the changes immediately applied, by just refreshing your browser. |
| 46 | + |
| 47 | + Hot reload works even when modifying your JPA entities. |
| 48 | + Try it! Even the Elasticsearch mapping will be updated on the fly. |
| 49 | + |
| 50 | +### Run Quarkus in JVM mode |
| 51 | + |
| 52 | +When you're done iterating in developer mode, you can run the application as a |
| 53 | +conventional jar file. |
| 54 | + |
| 55 | +First compile it: |
| 56 | + |
| 57 | +> ./mvnw package |
| 58 | +
|
| 59 | +Note that this command will start an Elasticsearch cluster to execute the tests. |
| 60 | +Thus your Elasticsearch containers need to be stopped. |
| 61 | + |
| 62 | +Next we need to make sure you have an Elasticsearch instance running |
| 63 | +(Quarkus automatically starts one for dev and test mode, but not for prod mode). |
| 64 | + |
| 65 | +To set up an Elasticsearch instance using Docker: |
| 66 | + |
| 67 | +> docker run -it --rm=true --name elasticsearch_quarkus_test -p 9200:9200 -p 9300:9300 -e "discovery.type=single-node" docker.elastic.co/elasticsearch/elasticsearch:8.12.0 |
| 68 | +
|
| 69 | +Then run the application: |
| 70 | + |
| 71 | +> java -jar ./target/quarkus-app/quarkus-run.jar |
| 72 | +
|
| 73 | + Have a look at how fast it boots. |
| 74 | + Or measure total native memory consumption... |
| 75 | + |
| 76 | +### Run Quarkus as a native application |
| 77 | + |
| 78 | +You can also create a native executable from this application without making any |
| 79 | +source code changes. A native executable removes the dependency on the JVM: |
| 80 | +everything needed to run the application on the target platform is included in |
| 81 | +the executable, allowing the application to run with minimal resource overhead. |
| 82 | + |
| 83 | +Compiling a native executable takes a bit longer, as GraalVM performs additional |
| 84 | +steps to remove unnecessary codepaths. Use the `native` profile to compile a |
| 85 | +native executable: |
| 86 | + |
| 87 | +> ./mvnw package -Dnative |
| 88 | +
|
| 89 | +After getting a cup of coffee, you'll be able to run this binary directly: |
| 90 | + |
| 91 | +> ./target/hibernate-search-standalone-elasticsearch-quickstart-1.0.0-SNAPSHOT-runner |
| 92 | +
|
| 93 | + Please brace yourself: don't choke on that fresh cup of coffee you just got. |
| 94 | + |
| 95 | + Now observe the time it took to boot, and remember: that time was mostly spent to generate the tables in your database and import the initial data. |
| 96 | + |
| 97 | + Next, maybe you're ready to measure how much memory this service is consuming. |
| 98 | + |
| 99 | +N.B. This implies all dependencies have been compiled to native; |
| 100 | +that's a whole lot of stuff. |
| 101 | + |
| 102 | +## See the demo in your browser |
| 103 | + |
| 104 | +Navigate to: |
| 105 | + |
| 106 | +<http://localhost:8080/> |
| 107 | + |
| 108 | +Have fun, and join the team of contributors! |
| 109 | + |
| 110 | +## Running the demo on Kubernetes |
| 111 | + |
| 112 | +To run the demo on Kubernetes, you will need to define resources: |
| 113 | + |
| 114 | +* A `Deployment` running the application's container image. |
| 115 | +* A `Service` and `Route` pointing to the application to expose it outside of the cluster. |
| 116 | +* A `Deployment` or `StatefulSet` running Elasticsearch. |
| 117 | +* A `Service` pointing to Elasticsearch to expose it to the application. |
| 118 | + |
| 119 | +Then, make sure the `Deployment` running the application uses |
| 120 | +environment variables that point to the Elasticsearch `Service`: |
| 121 | + |
| 122 | +```bash |
| 123 | +QUARKUS_HIBERNATE_SEARCH_ORM_ELASTICSEARCH_HOSTS=<ELASTICSEARCH_SERVICE_NAME>:9200 |
| 124 | +``` |
0 commit comments