Docker packaging and runtime for hlquery.

Get hlquery running in Docker!

hlquery is a high-performance search engine written in C++ designed for fast full-text search and semantic search capabilities.

Prerequisites

• Docker installed and running
• Docker Compose installed (usually included with Docker)
• Port 9200 available, or set HOST_PORT to publish on a different host port

Installation

Quick Start (Recommended)

The easiest way to install and run hlquery:

$ cd docker
$ docker-compose up -d

This will:

• Clone the hlquery source code from GitHub
• Build the Docker image
• Start hlquery on http://localhost:9200

If port 9200 is already in use on the host:

$ HOST_PORT=9201 docker-compose up -d

This keeps hlquery listening on port 9200 inside the container while publishing it as http://localhost:9201 on the host.

Verify it's running (replace 9200 if you set HOST_PORT):

$ curl http://localhost:9200/health

Using the Bootstrap Script

Alternatively, use the automated bootstrap script:

$ cd docker
$ ./bootstrap.sh

The bootstrap script will build and start hlquery automatically.

Installation Methods

Method 1: Docker Compose (Recommended)

1. Navigate to the docker directory:

   $ cd docker

2. Start hlquery:

   $ docker-compose up -d

3. Check status:

   $ docker-compose ps
   $ docker-compose logs -f

Stop hlquery:

$ docker-compose down

Method 2: Docker Command

1. Build the image:

   $ cd docker
   $ docker build --build-arg VERSION=unstable -t hlquery:latest .

2. Run the container:

   $ docker run -d \
     --name hlquery \
     -p 9200:9200 \
     -v hlquery_data:/var/lib/hlquery \
     -v hlquery_logs:/var/log/hlquery \
     hlquery:latest

3. Check status:

   $ docker ps
   $ docker logs hlquery

Stop hlquery:

$ docker stop hlquery
$ docker rm hlquery

Configuration

Environment Variables

Configure hlquery using environment variables:

Variable	Default	Description
HLQUERY_PORT	9200	Port to listen on
HLQUERY_DATA_DIR	/var/lib/hlquery	Directory for data storage
HLQUERY_LOG_DIR	/var/log/hlquery	Directory for log files
HLQUERY_CONF_DIR	/etc/hlquery/conf	Directory for configuration files

The Docker image builds from https://github.com/hlquery/hlquery and defaults to the unstable branch. Override VERSION if you want a different branch, tag, or commit.

Example - Change port:

$ docker run -d \
  --name hlquery \
  -p 8080:8080 \
  -e HLQUERY_PORT=8080 \
  hlquery:latest

Custom Configuration Files

Mount your configuration directory:

Docker Compose:

volumes:
  - ./conf:/etc/hlquery/conf:ro

Docker command:

$ docker run -d \
  --name hlquery \
  -p 9200:9200 \
  -v /path/to/your/config:/etc/hlquery/conf:ro \
  hlquery:latest

What is /etc/hlquery/conf?

• /etc/hlquery/conf is a path inside the container (not your host /etc).
• Your host directory (for example ./conf) becomes /etc/hlquery/conf inside the container when mounted.

Example configs

This repo includes a minimal working example you can copy:

• etc/docker/conf/hlquery.conf
• etc/docker/conf/links.conf

Note: The container runs as user hlquery (UID 1000). If you mount read-write (without :ro), ensure files are readable/writable for UID 1000.

Change Port in Docker Compose

Set environment variables when starting Compose:

HOST_PORT=8080 HLQUERY_PORT=9200 docker-compose up -d

If you also want the service to listen on a different port inside the container:

HOST_PORT=8080 HLQUERY_PORT=8080 docker-compose up -d

Building Custom Images

Build from Source

$ cd docker
$ docker build -t hlquery:latest .

Build with Custom Options

$ docker build \
  --build-arg VERSION=latest \
  --build-arg BUILD_MODE=release \
  --build-arg WITH_JEMALLOC=0 \
  -t hlquery:latest .

Build Arguments

Argument	Options	Default	Description
VERSION	latest, main, 1.0.0, v1.0.0, branch/tag	latest	Git version to build
BUILD_MODE	release, debug, profile, sanitize	release	Build configuration
WITH_JEMALLOC	0, 1	0	Enable jemalloc allocator
WITH_TCMALLOC	0, 1	0	Enable tcmalloc allocator

Data Persistence

Volumes

hlquery uses Docker volumes for persistent storage:

Volume	Mount Point	Description
hlquery_data	/var/lib/hlquery	Collection data and indexes
hlquery_logs	/var/log/hlquery	Log files
hlquery_conf	/etc/hlquery/conf	Configuration files

Using Named Volumes (Default)

Docker Compose automatically creates named volumes. Data persists across container restarts.

Troubleshooting

Configuration errors after upgrading

The default Compose setup persists configuration in the hlquery_conf volume. If you upgrade to a newer image version and hit startup errors in links.conf or hlquery.conf, you may be running with an older persisted config.

Reset the persisted config volume and restart:

docker-compose down -v
docker-compose up -d --build

links.conf node role must be a single value

If you see an error like:

Invalid <node ...> entry in links.conf: Node role must be a single value ...

Make sure each <node ...> uses a single role= value:

• Cluster/distributed search: role="distributed" (aliases: search, master)
• Replication follower: role="slave" (alias: replica)

If you need both purposes for the same endpoint, add two <node ...> entries (one per role).

Using Bind Mounts

Mount host directories directly:

$ docker run -d \
  --name hlquery \
  -p 9200:9200 \
  -v /host/data:/var/lib/hlquery \
  -v /host/logs:/var/log/hlquery \
  hlquery:latest

Verifying Installation

Check Container Status

# Docker Compose
$ docker-compose ps

# Docker
$ docker ps | grep hlquery

Test Health Endpoint

$ curl http://localhost:${HOST_PORT:-9200}/health

View Logs

# Docker Compose
$ docker-compose logs -f

# Docker
$ docker logs -f hlquery

Common Commands

Start/Stop

# Start
$ docker-compose up -d

# Stop
$ docker-compose down

# Restart
$ docker-compose restart

Access Container Shell

# Docker Compose
$ docker-compose exec hlquery /bin/bash

# Docker
$ docker exec -it hlquery /bin/bash

Update hlquery

1. Pull latest code (if using a specific version):

   # Edit docker-compose.yml to change VERSION build arg

2. Rebuild and restart:

   $ docker-compose build
   $ docker-compose up -d

Troubleshooting

Container Won't Start

Check logs:

$ docker-compose logs
# or
$ docker logs hlquery

Common issues:

• Port already in use: Change port in docker-compose.yml or use -p flag
• Permission denied: Ensure volumes have correct permissions (UID 1000)
• Out of disk space: Clean up with docker system prune

Can't Connect to API

1. Verify container is running: docker ps
2. Check port mapping: docker port hlquery
3. Test from inside container: docker exec hlquery curl http://localhost:9200/health
4. Check firewall settings

Health Check Failing

1. Check container logs: docker logs hlquery
2. Manually test: docker exec hlquery hlquery-cli status
3. Increase startup time in docker-compose.yml:

   healthcheck:
     start_period: 60s

Production Deployment

For production, consider:

1. Use specific image tags instead of latest
2. Set resource limits (CPU, memory)
3. Use external volumes for better performance
4. Configure log rotation
5. Set up monitoring and alerts

See the Production Deployment section in the full documentation for detailed examples.

---

Search beyond keywords - Happy searching!