From 5c3fdf2884e28d10b552fabe1bd357aa91449e82 Mon Sep 17 00:00:00 2001 From: "david.blasby" Date: Tue, 16 Apr 2024 12:40:06 -0700 Subject: [PATCH] Update docs for ElasticSearch - especially troubleshooting --- .../installing-from-source-code.md | 3 +- .../docs/install-guide/installing-index.md | 11 +- es/README.md | 100 ++++++++++++++---- es/docker-compose.yml | 1 + pom.xml | 15 +++ software_development/BUILDING.md | 9 +- software_development/README.md | 5 +- 7 files changed, 113 insertions(+), 31 deletions(-) diff --git a/docs/manual/docs/install-guide/installing-from-source-code.md b/docs/manual/docs/install-guide/installing-from-source-code.md index 8541a05ad9d..19ba7744492 100644 --- a/docs/manual/docs/install-guide/installing-from-source-code.md +++ b/docs/manual/docs/install-guide/installing-from-source-code.md @@ -64,8 +64,7 @@ cd core-geonetwork mvn clean install -DskipTests cd es -mvn install -Pes-download -mvn exec:exec -Des-start +docker-compose up cd web mvn jetty:run diff --git a/docs/manual/docs/install-guide/installing-index.md b/docs/manual/docs/install-guide/installing-index.md index e3ea8950d68..f593ee01853 100644 --- a/docs/manual/docs/install-guide/installing-index.md +++ b/docs/manual/docs/install-guide/installing-index.md @@ -49,8 +49,17 @@ GeoNetwork requires an [Elasticsearch](https://www.elastic.co/products/elasticse cd es mvn install -Pes-download ``` + + 3. **Modify**: Elasticsearch 8+ has security enabled by default. + + To disable this configuration for development, update the file `elasticsearch-/config/elasticsearch.yml` and MODIFY these EXISTING entries to `false`: + + ``` + xpack.security.enabled: false + xpack.security.enrollment.enabled: false + ``` - 3. **Start**: Use maven ``exec`` plugin to run Elasticsearch: + 4. **Start**: Use maven ``exec`` plugin to run Elasticsearch: ``` shell mvn exec:exec -Des-start diff --git a/es/README.md b/es/README.md index 0ef407c7f22..daedb917a80 100644 --- a/es/README.md +++ b/es/README.md @@ -6,7 +6,29 @@ This section describes several methods for configuring Elasticsearch for develop These configurations should not be used for a production deployment. -### Docker installation (Recommended) + +### Docker compose installation (Recommended) + +> [!CAUTION] +> Ensure you have at least 10% free disk space - see [Disk space threshold](#Disk-space-threshold) to disable this. + +1. Use docker compose with the provided [docker-compose.yml](docker-compose.yml): + + ``` + cd es + docker-compose up + ``` + +3. Check that it is running using your browser: + + * Elasticsearch: http://localhost:9200 + * Kibana: http://localhost:5601 + +### Docker installation + + +> [!CAUTION] +> Ensure you have at least 10% free disk space - see [Disk space threshold](#Disk-space-threshold) to disable this. 1. Use docker pull to download the image (you can check version in the :file:`pom.xml` file): @@ -26,38 +48,45 @@ These configurations should not be used for a production deployment. 3. Check that elasticsearch is running by visiting http://localhost:9200 in a browser -### Docker compose installation - -1. Use docker compose with the provided [docker-compose.yml](docker-compose.yml): - - ``` - cd es - docker-compose up - ``` - -3. Check that it is running using your browser: - - * Elasticsearch: http://localhost:9200 - * Kibana: http://localhost:5601 ### Maven installation Maven installation ensure you always are using the ``es.version`` version specified in ``pom.xml``. +> [!CAUTION] +> Ensure you have at least 10% free disk space - see [Disk space threshold](#Disk-space-threshold) to disable this. + 1. Maven can take care of the installation steps: * download * initialize collection * start -2. Use the following commands: +2. Use the following commands to download ES: ```shell script cd es - mvn install -Pes-download + mvn install -Pes-download + ``` + +3. Modify the Elastic Security Settings (for development) + + Elasticsearch 8 has security enabled by default. To disable this configuration for development, update the file `elasticsearch-/config/elasticsearch.yml` and MODIFY these EXISTING entries to `false`: + + ``` + xpack.security.enabled: false + xpack.security.enrollment.enabled: false + ``` + +4. Start ElasticSearch + + ```shell script mvn exec:exec -Des-start ``` -3. Check that elasticsearch is running by visiting http://localhost:9200 in a browser + +5. Check that elasticsearch is running by visiting http://localhost:9200 in a browser + + ## Manual installation @@ -66,7 +95,7 @@ and copy to the ES module, e.g., ``es/elasticsearch-8.11.3` 2. Disable the security - Elasticsearch 8 has security enabled by default. To disable this configuration for development, update the file `config/elasticsearch.yml` adding at the end: + Elasticsearch 8 has security enabled by default. To disable this configuration for development, update the file `elasticsearch-/config/elasticsearch.yml` and MODIFY these EXISTING entries to `false`: ``` xpack.security.enabled: false @@ -132,6 +161,25 @@ Don't hesitate to propose a Pull Request with the new language. # Troubleshoot +The first step is to look at the ES logs - there will often be some help regarding issues here. + +Second steps in checking on the ES health is to go to these ElasticSearch URLS: + +* http://localhost:9200/ This will tell you if ES is running and what version. +* http://localhost:9200/gn-records See the main GeoNetwork index +* http://localhost:9200/_cluster/health/ If your status is "red" then your ES is in trouble. + * http://localhost:9200/_cluster/allocation/explain might give an explaination of why the cluster is "red" + * "yellow" is expected on a single-node cluster (and is not necessarily a problem) + +The third step is to get more information from GeoNetwork: + +* http://localhost:8800/geonetwork/criticalhealthcheck +* http://localhost:8800/geonetwork/warninghealthcheck + + + +One of the most common issues is insufficient disk space available - see [Disk space threshold](#Disk-space-threshold). + ## Max number of fields Max number of fields: As we are using dynamic fields, when having a large number of records, the system may reach the maximum number of fields in Elasticsearch. In this situation, Elasticsearch is reporting: @@ -172,7 +220,7 @@ The other option is to increase `indices.query.bool.max_clause_count`. ## Disk space threshold -The server application will refuse to write new content unless there is enough free space available (by default 1/4 of your hard drive). +The server application will refuse to write new content unless there is enough free space available (by default 1/4 of your hard drive). This is often described as "disk_threshold". To turn off this check: @@ -187,3 +235,17 @@ To recover: ``` curl -XPUT -H "Content-Type: application/json" http://localhost:9200/_all/_settings -d '{"index.blocks.read_only_allow_delete": null}' ``` + +## Notes + +* GeoNetwork uses the ElasticSearch v8 library. This is compatible with ES v8 and v7.17.15. +* ES v8, by default, turns on security (username/password to connect to ES). The `xpack.security.*` options, used above, turns this off (no username/password required). If you have an ES username/password, you can configure GeoNetwork to use this with `-Des.username= -Des.password=`. To configure the ES docker container to use a specific ES password, add `- ELASTIC_PASSWORD=` to the docker-compose.yml `env` section. +* The `docker-compose.yml` mounts the directory `es-dashboards/data/index` into the ES container (to save the ES index over container restarts). However, you might want to reset this (`rm -rf es-dashboards/data/index`) if you change the docker container version. +* If there is a major problem with ES (i.e. GeoNetwork cannot connect to it), then the main GeoNetwork search webpage will display a yellow box saying "No search service available currently!". Suggestion is to go to http://localhost:9200/_cluster/health/ and http://localhost:9200/_cluster/allocation/explain for more details. GeoNetwork might give more information from http://localhost:8800/geonetwork/criticalhealthcheck and http://localhost:8800/geonetwork/warninghealthcheck +* You may go to the search website and see a red pop-up saying "Query returned an error. Check the console for details.". If this happens, open the Browser's devtools, and reload the page. Look at the Network and the Console for some details. This can be caused when there are no records in the ElasticSearch index - try to add some records to GeoNetwork and delete-and-reindex: + * When you first run GeoNetwork (with no records in the Geonetwork Index), you will get an ElasticSearch Query error on the main GeoNetwork search HTML page. This is normal - add more records to your GeoNetwork (i.e. go to "Admin Console" -> "Metadata and templates" and load the iso19139 samples) + * Use the admin tools to delete and re-index metadata (i.e. go to "Admin Console" -> "Tools" and then "Delete Index and Reindex") + + + + diff --git a/es/docker-compose.yml b/es/docker-compose.yml index cd255c6f531..12a087ae5ce 100644 --- a/es/docker-compose.yml +++ b/es/docker-compose.yml @@ -11,6 +11,7 @@ services: - "ES_JAVA_OPTS=-Xms512m -Xmx512m" - xpack.security.enabled=false - xpack.security.enrollment.enabled=false +# - ELASTIC_PASSWORD=changeme ulimits: memlock: soft: -1 diff --git a/pom.xml b/pom.xml index 455e6515a08..aeb95ff6566 100644 --- a/pom.xml +++ b/pom.xml @@ -1436,6 +1436,21 @@ jmeter + + macOS-M-series + + + mac + aarch64 + + + + darwin-aarch64 + kibana.sh + darwin-aarch64 + tar.gz + + macOS diff --git a/software_development/BUILDING.md b/software_development/BUILDING.md index 5abaf1db0cc..b72343d28da 100644 --- a/software_development/BUILDING.md +++ b/software_development/BUILDING.md @@ -88,15 +88,10 @@ GeoNetwork requires an Elasticsearch instance as an index. ``` cd es - mvn install -Pes-download + docker-compose up ``` -2. And run locally: - ``` - mvn exec:exec -Des-start - ``` - -3. For alternatives see [es/readme](../es/README.md). +2For alternatives see [es/readme](../es/README.md). ## Run Kibana diff --git a/software_development/README.md b/software_development/README.md index 94b0b7de045..c6367a9bc2b 100644 --- a/software_development/README.md +++ b/software_development/README.md @@ -37,10 +37,11 @@ Get GeoNetwork running - the short path: 2. Elasticsearch: ``` cd es - mvn install -Pes-download - mvn exec:exec -Des-start + docker-compose up ``` + See [es/readme](../es/README.md) for more ElasticSearch options (like running it locally) as well as troubleshooting. + 3. GeoNetwork web application: ``` cd web