How to Install Elasticsearch | Axero Documentation

Important Notes

• This guide covers Elasticsearch 8.13.4, which is the currently supported version for Axero. Do not install a different major version (e.g., 9.x) unless confirmed compatible by Axero.
• Install only one Elasticsearch instance per server.
• Do not install Elasticsearch on the same drive as your Axero site files (Windows installations only).
• Ensure the Elasticsearch drive has at least 50% free space.
• Elasticsearch 8.x bundles its own Java runtime. You do not need to install a separate JDK, and existing Java installations will not conflict.
• For deployments with 1,000 or more users: Install Elasticsearch on a separate, dedicated server. We recommend a 64-bit Linux server (Ubuntu Server 22.04 LTS) with at least 8 vCPU, 16 GB RAM, and 100 GB SSD storage. The Axero application server remains on Windows; only the Elasticsearch server runs Linux. If using a Linux server, follow the official Elastic Linux installation guide and then skip to the Connect Elasticsearch to Axero step below.

How to Install

1. Uninstall Previous Version
   • Remove any existing Elasticsearch installation to avoid conflicts (see instructions).
2. Download Elasticsearch
   1. Download the Elasticsearch 8.13.4 installation file from the official Elastic website.
   2. Extract the contents to a directory on your server (e.g., C:\Elasticsearch).
3. Enable Security
   1. Open the C:\Elasticsearch\config\elasticsearch.yml file in a text editor.
   2. Add the following line to enable security:
      

      xpack.security.enabled: true

   3. By default, Elasticsearch is only accessible on localhost. To make Elasticsearch accessible on a server IP, uncomment and update network.host: 192.168.0.1 to your desired IP address.
   4. Save and close the file.
4. Adjust JVM Heap Size
   1. Go to C:\Elasticsearch\config\jvm.options.d and create a new file named heap.options in a text editor.
   2. In the new file, add the following lines to set the minimum and maximum heap size:
      

      -Xms2g
      -Xmx2g

   3. The heap size should be set to approximately 50% of your server's total RAM, up to a maximum of 31 GB. Always set both values (-Xms and -Xmx) to the same amount. For example, on a server with 16 GB RAM, use -Xms8g and -Xmx8g. The 2 GB value shown above is the minimum for small deployments.
   4. Save and close the file.
5. Install Elasticsearch Service
   1. Open Command Prompt as an administrator.
   2. Go to the Elasticsearch bin directory (e.g., cd c:\elasticsearch\bin) and run:
      

      elasticsearch-service.bat install

6. Configure the Elasticsearch Service
   1. Press Windows Key + R, type services.msc, and press Enter.
   2. Locate the Elasticsearch service.
   3. Right-click the service and select Properties.
   4. Set Startup type to Automatic and click OK.
   5. Right-click the service again and select Start.
7. Set Elasticsearch Password
   1. Wait a few minutes for the service to start.
   2. Open Command Prompt as an administrator.
   3. Go to the Elasticsearch bin directory (e.g., cd c:\elasticsearch\bin) and reset the password by running:
      

      elasticsearch-reset-password.bat -u elastic

   4. Record the displayed password for the next step.
8. Verify Elasticsearch Is Running
   1. Open a web browser on the Elasticsearch server and go to https://localhost:9200.
   2. If prompted for credentials, enter username elastic and the password from the previous step.
   3. You should see a JSON response containing the cluster name, version number (8.13.4), and a tagline of "You Know, for Search". If you see an error or the page does not load, check the Troubleshooting section below before proceeding.
9. Connect Elasticsearch to Axero
   1. In Axero, go to Control Panel > System > System Properties.
   2. Edit ElasticsearchUsername, enter elastic, and save.
   3. Edit ElasticsearchPassword, paste the password from the Set Elasticsearch Password step, and save.
   4. If Elasticsearch is on the same server as Axero, the default ElasticsearchServer value of localhost does not need to be changed. If Elasticsearch is on a separate server, edit ElasticsearchServer, enter the IP address or hostname of the Elasticsearch server, and save.
10. Finalize Installation
    1. Go to Control Panel > System > Advanced System Utilities and click Restart Site. The restart may take a few minutes.
    2. After the restart, click Rebuild Index. You'll see a success message when the indexing is complete:
       
    3. If you are upgrading Elasticsearch, also click Rebuild Activity Log Index.

Troubleshooting

• Service fails to start: Check the logs at C:\Elasticsearch\logs\elasticsearch.log for error details. Common causes include insufficient memory for the configured heap size or port 9200 already in use by another process.
• Port conflict: Elasticsearch uses port 9200 by default. If another application is using this port, stop the conflicting service or change the Elasticsearch port by adding http.port: 9201 to elasticsearch.yml. Update the ElasticsearchServer system property in Axero to include the new port.
• Connection refused from Axero: If Elasticsearch is on a separate server, ensure the firewall allows inbound connections on port 9200 and that network.host is set to the correct IP address in elasticsearch.yml.
• Certificate or SSL errors: Elasticsearch 8.x enables HTTPS by default. If you see certificate errors, you may need to add xpack.security.http.ssl.enabled: false to elasticsearch.yml for environments that do not require HTTPS between Axero and Elasticsearch.