Link Search Menu Expand Document Documentation Menu
Documentation

Windows

The following sections describe installing Lucenia on Windows from a zip archive.

Generally speaking, the installation of Lucenia from a zip archive can be broken down into a few steps:

  1. Download and unpack Lucenia.
  2. (Optional) Test Lucenia.
    • Confirm that Lucenia is able to run before you apply any custom configuration.
    • This can be done without any security (no password, no certificates) or with a demo security configuration that can be applied by a packaged script.
  3. Configure Lucenia for your environment.
    • Apply basic settings to Lucenia and start using it in your environment.

The Windows Lucenia archive is a self-contained directory with everything needed to run Lucenia, including an integrated Java Development Kit (JDK). If you have your own Java installation and set the environment variable JAVA_HOME, Lucenia will use that installation if the LUCENIA_JAVA_HOME environment variable is not set. To learn how to set the LUCENIA_JAVA_HOME environment variable, see Step 3: Set up Lucenia in your environment.

Prerequisites

Make sure you have a zip utility installed.

Step 1: Download and unpack Lucenia

Perform the following steps to install Lucenia on Windows.

  1. Download the lucenia-0.1.0-windows-x64.zip archive.
  2. To extract the archive contents, right-click to select Extract All.

Step 2: (Optional) Test Lucenia

Before proceeding with any configuration, you should test your installation of Lucenia. Otherwise, it can be difficult to determine whether future problems are due to installation issues or custom settings you applied after installation. There are two quick methods for testing Lucenia at this stage:

  1. (Security enabled) Apply a generic configuration using the batch script included in the Windows archive.
  2. (Security disabled) Manually disable the Security implementation and test the instance before applying your own custom security settings.

The batch script will apply a generic configuration to your instance of Lucenia. This configuration defines some environment variables and also applies self-signed TLS certificates. Alternatively, you can choose to configure these yourself.

If you only want to verify that the service is properly configured and you intend to configure security settings yourself, then you may want to disable the Security implementation and launch the service without encryption or authentication.

A Lucenia node in its default configuration (with demo certificates and users with default passwords) is not suitable for a production environment. If you plan to use the node in a production environment, you should, at a minimum, replace the demo TLS certificates with your own TLS certificates and update the list of internal users and passwords. See Security configuration for additional guidance to ensure that your nodes are configured according to your security requirements.

Option 1: Test your Lucenia settings with security enabled

  1. Run the demo batch script from Command prompt or Powershell.

    1. Open Command Prompt by entering cmd or Powershell by entering powershell in the search box next to Start on the taskbar.
    2. Change to the top directory of your Lucenia installation. 
      cd \path\to\lucenia-0.1.0

    3. Run the batch script. Use the following command to specify a custom admin password: 
      > set LUCENIA_INITIAL_ADMIN_PASSWORD=<custom-admin-password>


      .\lucenia-windows-install.bat

  2. Open a new command prompt and send requests to the server to verify that Lucenia is running. Note the use of the --insecure flag, which is required because the TLS certificates are self-signed.

    • Send a request to port 9200: 
       curl.exe -X GET https://localhost:9200 -u "admin:<custom-admin-password>" --insecure

      You should get a response that looks like this:

       {
    "name" : "hostname-here",
    "cluster_name" : "lucenia",
    "cluster_uuid" : "7Nqtr0LrQTOveFcBb7Kufw",
    "version" : {
       "distribution" : "lucenia",
       "number" : <version>,
       "build_type" : <build-type>,
       "build_hash" : <build-hash>,
       "build_date" : <build-date>,
       "build_snapshot" : false,
       "lucene_version" : <lucene-version>,
       "minimum_wire_compatibility_version" : "2.15.0",
       "minimum_index_compatibility_version" : "2.0.0"
    },
    "tagline" : "[SEARCH]...on your terms"
 }
    • Query the plugins endpoint: 
       curl.exe -X GET https://localhost:9200/_cat/plugins?v -u "admin:<custom-admin-password>" --insecure

      The response should look like this:

       hostname lucenia-security                  0.1.0

Option 2: Test your Lucenia settings with security disabled

  1. Open the lucenia-0.1.0\config folder.
  2. Open the lucenia.yml file with a text editor.
  3. Add the following line to disable the Security plugin: 
    plugins.security.disabled: true

  4. Save the change and close the file.
  5. Navigate to the top directory of your Lucenia installation and open the lucenia-0.1.0 folder.
  6. Run the default by double-clicking the lucenia-windows-install.bat file. This opens a command prompt with an Lucenia instance running.
  7. Open a new command prompt and send requests to the server to verify that Lucenia is running. Because the Security plugin has been disabled, you will be sending commands using HTTP rather than HTTPS.
    • Send a request to port 9200: 
       curl.exe -X GET http://localhost:9200

      You should get a response that looks like this:

       {
    "name" : "hostname-here",
    "cluster_name" : "lucenia",
    "cluster_uuid" : "7Nqtr0LrQTOveFcBb7Kufw",
    "version" : {
       "distribution" : "lucenia",
       "number" : "0.1.0",
       "build_type" : "zip",
       "build_hash" : "77ef9e304dd6ee95a600720a387a9735bbcf7bc9",
       "build_date" : "2024-07-27T05:50:15.404072800Z",
       "build_snapshot" : false,
       "lucene_version" : "9.11.0",
       "minimum_wire_compatibility_version" : "2.15.0",
       "minimum_index_compatibility_version" : "2.0.0"
    },
    "tagline" : "[SEARCH]...on your terms."
 }
    • Query the plugins endpoint: 
       curl.exe -X GET http://localhost:9200/_cat/plugins?v

      The response should look like this:

       hostname lucenia-security                  0.1.0

To stop Lucenia, press Ctrl+C in Command Prompt or Powershell, or simply close the Command Prompt or Powershell window.

Step 3: Set up Lucenia in your environment

Users who do not have prior experience with Lucneia may want a list of recommended settings in order to get started with the service. By default, Lucenia is not bound to a network interface and cannot be reached by external hosts. Additionally, security settings are either undefined (greenfield install) or populated by default usernames and passwords if you ran the security demo script by invoking lucenia-windows-install.bat. The following recommendations will enable a user to bind Lucenia to a network interface.

The following recommended settings will allow you to:

  • Bind Lucenia to an IP or network interface on the host.
  • Set initial and maximum JVM heap sizes.
  • Define an environment variable that points to the bundled JDK.

If you ran the security demo script, then you will need to manually reconfigure settings that were modified. Refer to Security configuration for guidance before proceeding.

Before modifying any configuration files, it’s always a good idea to save a backup copy before making changes. The backup file can be used to revert any issues caused by a bad configuration.

  1. Open the lucenia-0.1.0\config folder.
  2. Open the lucenia.yml file with a text editor.
  3. Add the following lines: 
    # Bind Lucenia to the correct network interface. Use 0.0.0.0
# to include all available interfaces or specify an IP address
# assigned to a specific interface.
network.host: 0.0.0.0

# Unless you have already configured a cluster, you should set
# discovery.type to single-node, or the bootstrap checks will
# fail when you try to start the service.
discovery.type: single-node

# If you previously disabled the Security implementation in lucenia.yml,
# be sure to re-enable it. Otherwise you can skip this setting.
plugins.security.disabled: false

  4. Save your changes and close the file.
  5. Specify initial and maximum JVM heap sizes.
    1. Open the lucenia-0.1.0\config folder.
    2. Open the jvm.options file with a text editor.
    3. Modify the values for initial and maximum heap sizes. As a starting point, you should set these values to half of the available system memory. For dedicated hosts this value can be increased based on your workflow requirements.
      As an example, if the host machine has 8 GB of memory, then you might want to set the initial and maximum heap sizes to 4 GB: 
       -Xms4g
 -Xmx4g

    4. Save your changes and close the file.
  6. Specify the location of the included JDK.
    1. In the search box next to Start on the taskbar, enter edit environment variables for your account or edit the system environment variables. To edit the system environment variables, you need admin rights. User environment variables take precedence over system environment variables.
    2. Select Edit environment variables for your account or Edit the system environment variables.
    3. If the System Properties dialog opens, in the Advanced tab, select Environment Variables.
    4. Under User variables or System variables, select New.
    5. In Variable name, enter LUCENIA_JAVA_HOME.
    6. In Variable value, enter \path\to\lucenia-0.1.0\jdk.
    7. Select OK to close all dialogs.
350 characters left

Have a question? .