Skip to content

Habitus Frontend (viewer or GUI)

Jump to bottom
Keith Alcock edited this page Jan 9, 2025 · 1 revision

Introduction

There are multiple Habitus (or more accurately, Heuristics) applications with graphical user interfaces (GUIs) under development. Some versions and configurations are suitable for end users, especially those willing to be alpha and beta testers. This document describes how to install one such application, the one which looks like this:

image

Options

A growing number of options are available, so keep them in mind while reading further:

Installation

In the end, you will need to have downloaded the application and have a particular version of Java installed and various API keys configured for external services. The application and templates for the configuration files are available for download from the project's Box account. Links to pages where API keys can be obtained are included below. Not all keys are required if the corresponding functionality is not exercised. Java is a straightforward download and can be configured so as not to interfere with existing installations on your computer.

Download the Application

There are two different zip files available at Box. The first listed is specific to Windows and is almost the same as the second except that it has combined the jar file of the second with a Liberica Java distribution into an executable file built with launch4j. One should be able to double click on the extracted executable and not need to download Java for it. The second zip file does not include Java and the application is usually started with a simple command from the terminal window. Download the appropriate file and unzip it into a preferably empty directory/folder of your choosing. You should have the files

  • habitus-win.zip
    • habitus.exe
    • chatgpt-credentials.properties
    • elasticsearch-credentials.properties
    • mapsjsapi-credentials.properties
  • habitus-java.zip
    • habitus.jar
    • chatgpt-credentials.properties
    • elasticsearch-credentials.properties
    • mapsjsapi-credentials.properties

Configure the Services

Each of the properties files corresponds to an external service that provides the application with functionality that isn't built in. To access the services, one needs an API key similar to a password but assigned by the computer. In each case, the key should replace the placeholder in the files where it says apikey = placeholder. This can be achieved with a simple text editor.

  • elasticsearch-credentials.properties - This is the most important of the three and a "starter" key is pre-configured so that you can initially skip this step, but you might want to complete it later. The application accesses data that is stored in an Elasticsearch database. The data is not intended for the general public and requires an API key for access. Please contact the UA Habitus team for an Elasticsearch account and a key that will provide read access so that the application can get to the data. An CLU Lab server is used and there is no cost to users. When the application starts, it immediately collects some summary information for display in the database tab, so if you see information like that below, your key is working.

    image

    If there is a problem, you will likely see a stack trace in the console window with Caused by: org.elasticsearch.client.ResponseException: method [GET], host [https://elasticsearch.habitus.clulab.org:443], URI [/habitus/_search?pretty=true], status line [HTTP/1.1 401 Unauthorized].

  • chatgpt-credentials.properties - To use the chat tab in the application, one must have an API key. These are obtained from OpenAI and can involve costs. The software is using the gpt-4 model. If your key is incorrect, you will probably see a stack trace in the console window that includes the text Caused by: com.theokanning.openai.OpenAiHttpException: Incorrect API key provided: placeholder. You can find your API key at https://platform.openai.com/account/api-keys. but otherwise you will see a response from ChatGPT to a valid request in the grid tab:

    image

  • mapsjsapi-credentials.properties - Google provides mapping for the project. An account comes with a fairly large allotment of free queries. The key needed is for the Maps JavaScript API and instructions for it are fairly comprehensive and comprehensible. With a valid key, you should be able to see maps like this,

    image

    but without one, you will see a "map" that looks more like this:

    image

Install Java

The client software currently requires Java 11 or possibly higher with JavaFx included. If you downloaded the Windows version of this software, you should be good already. Otherwise, the required version of Java is likely not the version of Java that you have installed. It is recommended that you download a copy of the Liberica Java Runtime Engine (JRE, although the JDK will work as well) package for your platform (Windows, Mac, or Linux). Pick the "Full JRE" (or "Full JDK") for the right operating system and hardware architecture and prefer the TAR.GZ or ZIP distribution over anything with an installer, because it will be unzipped into a directory and used "as is" without other complications.

image

Download it to your habitus directory next to habitus.jaror move it there and unzip or un-tar.gz it. After the Java download file is removed and some containing directories removed, you might be left with these entries in the filesystem:

  • habitus.jar
  • chatgpt-credentials.properties
  • elasticsearch-credentials.properties
  • mapsjsapi-credentials.properties
  • jre-11.0.25-full

Make special note of the last one. Given the name, you would expect to find Java at jre-11.0.25-full/bin/java.

Execution

With the Windows version, just double click, but otherwise to start the habitus program, assuming the directory structure above, type the command

jre-11.0.25-full/bin/java -jar habitus.jar

There is a chance that you need to use backslashes instead of forward (depending on command interpreter) or to start the command with "./" or in extreme cases to modify the PATH environment variable so that the current directory is used before others. However, the command should be close to as simple as this one. Since Java was downloaded from the internet, the operating system, especially MacOS, may warn you with security concerns. Assuming that is a false alarm (e.g., after running a virus check), one way to get around it is to double click on jre-11.0.25-full/bin/java and there OK the program before trying again from the command line.

You should then see some diagnostic output in the console window, but hopefully also a GUI on relative short order. Be sure to visit tabs that confirm your API keys soon after installation.

From properties:
  JavaFX Version: [failed]
  JavaFX Runtime Version: [failed]
From VersionInfo:
  JavaFX Version: 11.0.25+1
  JavaFX Runtime Version: 11.0.25+1+b01

GET /habitus/_search {pretty=true}
{
  "size" : 0,
  "aggs" : {
    "datasets" : {
      "terms" : {
        "size" : 65536,
        "field" : "dataset",
        "order" : {
          "_key" : "asc"
Clone this wiki locally