DHIS2 Text Query installation

This guide covers the installation of the DHIS2 Text Query service. The DHIS2 Text Query is a backend service and API for conversational analytics and visualization for DHIS2.

The service key is dhis2-text-query. The service port is 8094.

This guide assumes that a dedicated user for running the service called bao-admin exists.

JAR file

The service is available as a JAR file. The filename is dhis2-text-query.jar.

The JAR file should be installed in the following location.

/var/lib/dhis2-text-query/dhis2-text-query.jar

Create the directory manually and make bao-admin the owner.

sudo mkdir /var/lib/dhis2-text-query

sudo chown bao-admin:bao-admin /var/lib/dhis2-text-query

Place the JAR file in the previously created directory and make bao-admin the owner.

sudo cp dhis2-text-query.jar /var/lib/dhis2-text-query

sudo chown bao-admin:bao-admin /var/lib/dhis2-text-query/dhis2-text-query.jar

Systemd

The systemd service manager is used to manage the service process.

The systemd service file should be located in the /etc/systemd/system directory.

/etc/systemd/system/dhis2-text-query.service

Create the system service file with the following content.

sudo nano /etc/systemd/system/dhis2-text-query.service

[Unit]
Description = DHIS2 Text Query service

[Service]
Environment = "JAVA_HOME=/usr/lib/jvm/java-1.17.0-openjdk-amd64"
Environment="JAVA_OPTS=-Xms512M -Xmx1024M"
ExecStart = /bin/bash -c '${JAVA_HOME}/bin/java ${JAVA_OPTS} -jar /var/lib/dhis2-text-query/dhis2-text-query.jar'
User = bao-admin

[Install]
WantedBy = multi-user.target

To enable the services on boot, invoke the following command.

sudo systemctl enable dhis2-text-query

PostgreSQL

The service requires a PostgreSQL database. The minimum PostgreSQL version is 14.

sudo su postgres

psql

Create user.

create user dhis2textquery with password 'mypassword';

Create database.

create database dhis2textquery with owner dhis2textquery encoding 'utf8';

Configuration

The service is configured with a properties file called dhis2-text-query.conf.

The file should reside in the following location.

/opt/dhis2-text-query/dhis2-text-query.conf

Create a configuration file with the following content.

sudo mkdir /opt/dhis2-text-query

sudo nano /opt/dhis2-text-query/dhis2-text-queryy.conf

# ----------------------------------------------------------------------
# DHIS2 Text Query
# ----------------------------------------------------------------------

# ----------------------------------------------------------------------
# Database connection
# ----------------------------------------------------------------------

# Database connection URL
connection.url = jdbc:postgresql:dhis2textquery

# Database username
connection.username = dhis2textquery

# Database password (sensitive)
connection.password = mypassword

# ----------------------------------------------------------------------
# DHIS2
# ----------------------------------------------------------------------

# Base URL
dhis2.base_url = https://dhis2.mydomain.org

# ----------------------------------------------------------------------
# Google Gemini
# ----------------------------------------------------------------------

# API key (confidential)
google.gemini.api_key = xxxx

# Model, can be 'default', 'gemini-2.0-flash', 'gemini-2.5-flash'
google.gemini.model = gemini-2.5-flash

# ----------------------------------------------------------------------
# CORS
# ----------------------------------------------------------------------

# Origins from which to allow CORS
cors.allowed_origins = http://localhost,\
                       http://localhost:3000

Proxy

The service provides API endpoints. To make the API endpoints accessible, an HTTP proxy must be set up.

This is typically done by specifying a location block in nginx. In the nginx configuration file for DHIS2, immediately before the location block for DHIS2 itself, specify a location block for the service.

server {
  # ..
  # DHIS2 text query
  location /text-query/ {
    proxy_pass         http://127.0.0.1:8094/text-query/;
    proxy_set_header   Host                $host;
    proxy_set_header   X-Real-IP           $remote_addr;
    proxy_set_header   X-Forwarded-For     $proxy_add_x_forwarded_for;
    proxy_set_header   X-Forwarded-Proto   $scheme;
    proxy_set_header   X-Forwarded-Port    $server_port;
  }
}

Logging

The service uses the journalctl tool to view logs. To view log output, invoke the following command.

sudo journalctl -n 500 -f -u dhis2-text-query

Start

The service is started by invoking the following command.

sudo systemctl start dhis2-text-query

Stop

The service is stopped by invoking the following command.

sudo systemctl stop dhis2-text-query

Status

The service status is observed by invoking the following command.

sudo systemctl status dhis2-text-query