Build and deploy the GuancheData Search Engine

GuancheData is packaged as a multi-module Maven project. A single mvn clean package command produces all the executable JARs that Docker Compose then picks up when building container images. Deployment is profile-driven: the main node runs the broker, backend services, and load balancer together, while additional nodes join the Hazelcast cluster by running only the backend profile. Follow the steps below to go from a fresh clone to a running cluster.

Navigate to the repository root

All Maven and Docker Compose commands must be run from the root of the repository, where the top-level pom.xml and docker-compose.yml live.

cd /path/to/GuancheData/stage_3

Build all service JARs

Compile and package every module in one pass from the root:

mvn clean package

This builds four modules — ingestion-service, indexing-service, search-service, and benchmarking — and places the shaded (fat) JARs in each module’s target/ directory. Docker Compose will copy these artifacts into the container images at startup; you do not need to run docker build separately.

Configure IP addresses in docker-compose.yml

Every xxx placeholder in docker-compose.yml must be replaced with a real IP address before the cluster starts.

The cluster will fail to form if any xxx placeholder remains. Search for all occurrences before proceeding:

grep -n "xxx" docker-compose.yml

The substitution rules are:

In HZ_PUBLIC_ADDRESS — use the host IP of the machine running that service.
In HZ_MEMBERS — use the host IP of the main node (the seed node for Hazelcast discovery). All services on all nodes should point here.
In BROKER_URL — use the host IP of the node running the broker profile (i.e., the main node).

Example after substitution (main node at 192.168.1.10):

ingestion-service:
  environment:
    HZ_PORT: "5701"
    HZ_PUBLIC_ADDRESS: 192.168.1.10:5701
    HZ_MEMBERS: 192.168.1.10:5701
    HAZELCAST_CLUSTER_NAME: SearchEngine
    BROKER_URL: tcp://192.168.1.10:61616
    REPLICATION_FACTOR: 2
    INDEXING_BUFFER_FACTOR: 2

indexing-service:
  environment:
    HZ_PORT: "5702"
    HZ_PUBLIC_ADDRESS: 192.168.1.10:5702
    HZ_MEMBERS: 192.168.1.10:5701
    HAZELCAST_CLUSTER_NAME: SearchEngine
    BROKER_URL: tcp://192.168.1.10:61616

search-service:
  environment:
    HZ_PORT: "5703"
    SERVICE_PORT: "7003"
    HZ_PUBLIC_ADDRESS: 192.168.1.10:5703
    HZ_MEMBERS: 192.168.1.10:5701
    HAZELCAST_CLUSTER_NAME: SearchEngine
    SORTING_CRITERIA: "frequency"

On each additional node, set HZ_PUBLIC_ADDRESS to that node’s own IP and keep HZ_MEMBERS pointing at the main node’s ingestion-service (<MAIN_NODE_IP>:5701).

Configure nginx.conf with search-service backend IPs

The Nginx load balancer proxies /search and /health requests to the search-service instances in the cluster. Before starting the loadbalancer profile, replace the <NODE_IP> placeholders in nginx.conf with the real IPs of every node running a search-service.

upstream search_backend {
    least_conn;

    server 192.168.1.10:7003 max_fails=10 fail_timeout=30s;
    server 192.168.1.11:7003 max_fails=10 fail_timeout=30s;

    keepalive 64;
}

Add one server line per search-service instance. Nginx uses a least-connections strategy and will automatically stop routing to a backend after 10 consecutive failures, with a 30-second recovery window.

For a single-node deployment, keep only one server line pointing at 127.0.0.1:7003 or the host’s LAN IP.

Start the cluster

Choose the deployment mode that matches your environment.

Single node
Multi-node

Start the broker, all backend services, and the load balancer together on one machine:

docker compose --profile backend --profile broker --profile loadbalancer up -d

This brings up the following containers:

Container	Profile	Description
`ingestion-service`	`backend`	Document crawler and datalake writer
`indexing-service`	`backend`	Async indexer consuming ActiveMQ messages
`search-service`	`backend`	HTTP search API (port 7003)
`activemq`	`broker`	ActiveMQ message broker (port 61616)
`nginx`	`loadbalancer`	Reverse proxy and load balancer (port 8080)

Main node — run the broker, backend, and load balancer:

docker compose --profile backend --profile broker --profile loadbalancer up -d

Each additional node — run the backend services only. These containers will join the existing Hazelcast cluster and connect to the broker on the main node:

docker compose --profile backend up -d

Each additional node needs its own copy of the repository with HZ_PUBLIC_ADDRESS set to its own IP. The HZ_MEMBERS and BROKER_URL values on additional nodes must point back to the main node. Maven does not need to be re-run on additional nodes if the JAR artifacts are already built and available.

Overview

Getting Started

Services

Operations

Build and deploy the GuancheData Search Engine

Build docs developers (and LLMs) love

Overview

Getting Started

Services

Operations

Documentation Index

Build docs developers (and LLMs) love