Skip to main content

Installation Guide

This guide explains how to install and build hlquery on GNU/Linux, FreeBSD, and macOS.

Prerequisites​

Before installing hlquery, ensure you have the necessary build tools installed on your system.

Debian/Ubuntu Systems​

sudo apt-get update
sudo apt-get install build-essential cmake

RedHat/CentOS/Fedora Systems​

sudo dnf install @development-tools cmake

macOS​

Install Xcode Command Line Tools for the C/C++ compiler and make, then use Homebrew for CMake:

xcode-select --install
brew install cmake

Optional: SSL/TLS Support​

If you want SSL/TLS support for HTTPS connections, install OpenSSL development libraries:

Debian/Ubuntu:

sudo apt-get install libssl-dev

RedHat/CentOS/Fedora:

sudo dnf install openssl-devel

macOS:

brew install openssl

Note: The configure script will automatically detect OpenSSL if available and enable SSL support.

Building from Source​

For most users, building from source is the most direct way to get the latest stable features and fixes.

Step 1: Get the Source​

Choose one of the following:

Option A (Recommended): Download the latest release ZIP

Download the latest release ZIP from the hlquery GitHub releases page, then extract it:

unzip hlquery-<version>.zip
cd hlquery-<version>/

Option B: Clone the latest stable branch

Clone the latest stable version of hlquery:

git clone --branch 1.0 git@github.com:hlquery/hlquery.git
cd hlquery/

Developer builds: If you want the newest changes (unstable), see the Development Installation Guide.

Step 2: Configure​

Run the configure script to prepare the build system:

./configure

For distro-style installs (Debian/Ubuntu or RPM families), use layout presets:

./configure --layout=debian
# or
./configure --layout=rpm

--layout=auto will detect the distro family from /etc/os-release and choose paths automatically.

Optional extras can be enabled at configure time:

./configure --enable-extras=all

In hlquery, "extras" means optional modules discovered under src/modules/extra. They are not built by default. ./configure --enable-extras=... adds the selected extra modules to the generated Makefile and stages their shared libraries in run/modules/ during make.

You can pass a comma-separated list such as --enable-extras=module_a,module_b or use --enable-extras=all to enable every extra currently present in src/modules/extra.

How it works:

  • ./configure scans src/modules/extra for extra modules.
  • A single-file extra is discovered as src/modules/extra/m_name.cpp and is enabled as m_name.
  • A multi-file extra is discovered as src/modules/extra/m_name/ and is enabled as m_name.
  • --enable-extras=all means "enable every extra discovered right now", not "turn on a built-in preset list".
  • Unknown names fail fast during ./configure so typos do not silently produce a partial build.
  • Enabled extras are built as shared objects under run/modules/.
  • During configure, helper symlinks are created under src/modules/ so the normal runtime/module loader can see the enabled extras without copying source files.

Examples:

# Enable every extra currently present under src/modules/extra
./configure --enable-extras=all

# Enable only specific extras
./configure --enable-extras=m_example,m_other

If src/modules/extra is empty, --enable-extras=all simply enables nothing. If you request a specific extra that does not exist, ./configure stops and prints the list of available extra names.

This script will:

  • Detect your system configuration
  • Check for required dependencies
  • Enable optional features (like SSL) if available
  • Generate the Makefile

Step 3: Build and Install​

Compile hlquery using make. We recommend using the -j flag to utilize multiple CPU cores for faster compilation, then run make install once to install the compiled binaries:

make -j4
make install

Tip: Adjust the number after -j based on your CPU cores:

  • -j4 uses 4 cores
  • -j8 uses 8 cores
  • -j$(nproc) uses all available cores (Linux)

The install target will:

  • Install the hlquery binaries already built by make
  • Install binaries and runtime files to the paths selected by ./configure
  • Set up configuration files in the configured config directory (run/conf for dev layout, /etc/hlquery for system/debian/rpm layouts)

If you change the enabled extras, run ./configure again before rebuilding so the generated Makefile and generated module symlinks match the selected module set.

Cleaning Build Artifacts​

make clean

make clean removes the normal build output and also removes extra-module artifacts, including:

  • shared libraries under run/modules/*.so
  • generated module symlinks under src/modules/
  • generated Makefile and include/core/config.h

That means after make clean, extra modules are no longer staged for runtime. Run ./configure --enable-extras=... again and rebuild if you still want them enabled.

Verifying Installation​

After installation, verify that hlquery is properly installed:

hlquery --version

You should see the hlquery version information.

Configuration​

hlquery uses hlquery.conf in the configured config directory:

  • Dev layout: run/conf/hlquery.conf
  • System/Debian/RPM layouts: /etc/hlquery/hlquery.conf

The default configuration should work for most use cases, but you can customize:

  • Network bindings: Change the default port (9200)
  • Logging: Configure log levels and output destinations
  • Performance: Adjust thread limits and resource usage
  • Authentication: Enable/disable authentication

See the Configuration Guide for detailed configuration options.

Running hlquery​

Starting the Server​

To start hlquery with the default configuration:

hlquery start

Note: hlquery runs in the background (daemon mode) by default.

Running in Foreground​

If you want to see the server output directly (useful for debugging), use the --nofork flag:

hlquery start --nofork

Stopping the Server​

To stop the running server:

hlquery stop

Checking Server Status​

Check if the server is running:

hlquery status

Or use the CLI tool:

hlquery-cli health
hlquery-cli stats

hlquery-cli does not provide a status subcommand. Use health for a quick check and stats for the detailed server view.

Default Port​

hlquery uses port 9200 by default. Make sure this port is available before starting the server. You can change the port in the configuration file if needed.

Next Steps​

Now that hlquery is installed and running:

  1. Test the installation: Try the Quick Start Guide
  2. Explore the API: Check out the API Reference
  3. Use the Web Interface: Set up the Web Interface for a graphical way to interact with hlquery
  4. Read the documentation: Browse the full API Documentation

Troubleshooting​

Build Errors​

If you encounter build errors:

  1. Ensure all dependencies are installed
  2. Check that you have a C++20 compatible compiler (GCC 10+ or Clang 10+)
  3. Review the error messages for missing libraries

Port Already in Use​

If port 9200 is already in use:

  1. Find the process using the port: 
    lsof -i :9200
    # or
    netstat -tulpn | grep 9200
  2. Either stop that process or change hlquery's port in the configuration file

Permission Errors​

If you get permission errors:

  1. Ensure you have write permissions in the run/ directory
  2. Check that the run/logs/ directory exists and is writable
  3. For production deployments, consider running as a dedicated user

Production Deployment​

For production deployments, consider:

  • Setting up SSL/TLS certificates for HTTPS
  • Configuring proper logging and monitoring
  • Setting up authentication
  • Using a process manager (systemd, supervisor, etc.)
  • Configuring firewall rules
  • Setting up backups for data persistence

See the Configuration Guide for production-ready settings.