Install

Zulia requires Java 25 or greater. Lucene 10.x has special optimizations for Java 21+.

Download latest version and extract

https://github.com/zuliaio/zuliasearch/releases

cd YOUR_INSTALL_DIR
wget https://github.com/zuliaio/zuliasearch/releases/download/5.1.2/zulia-server-5.1.2.tar
tar xvf zulia-server-5.1.2.tar
rm zulia-server-5.1.2.tar
ln -s zulia-server-5.1.2 zulia-server

OR Compile latest from code

cd YOUR_INSTALL_DIR
git clone git@github.com:zuliaio/zuliasearch.git
cd zuliasearch
./gradlew
# can replace wildcards below with actual file / dir names
cp zulia-server/build/distributions/zulia*tar .. 
cd ..
tar xvf zulia-server-*.tar
rm zulia-server-*.tar
ln -s zulia-server-* zulia-server

Edit Zulia Configuration

Edit zulia-server/config/zulia.yaml

Configuration Reference

# Network
serverAddress: localhost      # Address for inter-node communication (null = autodetect)
servicePort: 32191            # gRPC service port
restPort: 32192               # REST API port

# Storage
dataPath: /path/to/data/      # Directory for index data (default: "data")

# Cluster mode (requires MongoDB)
cluster: true                 # Enable cluster mode (default: false)
clusterName: "zulia"          # Cluster name (default: "zulia")
mongoServers:
  - hostname: 127.0.0.1
    port: 27017

# Performance
rpcWorkers: 0                 # Number of Netty event loop threads for gRPC (default: 0 = 2x CPU cores).
                              # Controls how many concurrent gRPC requests can be processed in parallel.
                              # Increase for high-throughput workloads with many concurrent clients.
responseCompression: false    # Enable gzip compression on gRPC responses (default: false).
                              # Reduces network bandwidth for large result sets at the cost of CPU.
                              # Only applies to gRPC; REST responses are not compressed by this setting.
defaultConcurrency: 1         # Default number of virtual threads for parallel segment search per shard.
                              # Can be overridden per index or per query. See Java Client docs.

# Debugging
debug: false                  # Force debug logging on all queries (default: false).
                              # Logs the Lucene query and rewritten query for each shard,
                              # and adds merge statistics (response count, total size, merge time)
                              # to the query completion log. Can also be enabled per query from the client.

# Aggregation
hitsPerConcurrentRequest: 10000   # Number of hits processed per unit of aggregation concurrency (default: 10000).
                                  # Controls how aggregation work is split across virtual threads.
maxFacetsCachedPerDimension: 4096 # Maximum number of facet values cached per dimension (default: 4096).

# Replication (cluster mode)
# Used when an index has replicas (numberOfReplicas > 0). Primary shards stream committed
# Lucene segments to replica nodes; these settings tune the transfer. See the Replication section below.
replicaResponseTimeout: 10          # Minutes; deadline on a single segment-file stream to a replica (default: 10).
                                    # Raise if force-merges or large vector segments cannot ship within 10 minutes.
replicationMaxBytesPerSec: 62914560 # Aggregate replication bandwidth cap leaving this node, in bytes/sec
                                    # (default: 62914560 = 60 MiB/s). Set to 0 to disable the cap.

# Health monitoring
# Configures the /health REST endpoint indicators and optional MongoDB health logging.
# health:
#   memoryThresholdPercent: 90.0      # Heap usage % above which memory reports DEGRADED (default: 90.0)
#   systemCpuThresholdPercent: 90.0   # System CPU % above which CPU reports DEGRADED (default: 90.0)
#   jvmCpuThresholdPercent: 80.0      # JVM CPU % above which CPU reports DEGRADED (default: 80.0)
#   writeToMongo: false               # Enable periodic health logging to MongoDB (default: false)
#   db: ""                            # MongoDB database for health logs (default: cluster name)
#   collection: "health"              # MongoDB collection for health logs (default: "health")
#   writeIntervalSeconds: 60          # Seconds between health log writes (default: 60)
#   ttlDays: 30                       # Days before health log entries expire (default: 30)

Add node(s) and start node(s)

cd zulia-server/bin
./zuliad --config ../config/zulia.yaml addNode
./zuliad --config ../config/zulia.yaml start

Replication

In cluster mode, set numberOfReplicas greater than 0 on an index to keep additional copies of each shard on other nodes. Primary shards stream their committed Lucene segments to the replicas, so replicas serve queries from local data and can take over if a primary node fails.

Replication is tuned with two node-level settings in zulia.yaml (shown in the configuration reference above):

  • replicaResponseTimeout - minutes allowed for a single segment-file stream to a replica (default 10).
  • replicationMaxBytesPerSec - aggregate replication bandwidth cap leaving the node, in bytes/sec (default 62914560, i.e. 60 MiB/s; 0 disables the cap).

The number of replicas is set per index and can be changed on a live index (see Java-Client or zuliaadmin updateIndex). Replica progress is monitored per shard and per replica via the Rest-Service endpoint. When rolling a Lucene upgrade, upgrade replica nodes first: a primary refuses to ship segments to a replica running an older Lucene version (it requires replicaVersion >= primaryVersion).

systemd script and future maintenance

Create systemd and environment file script

CHANGE User and Group to user/group that can write the directory given in zulia.yaml

nano /etc/default/zulia

ZULIAD_OPTS="-Xmx15g"

# save and exit

nano /lib/systemd/system/zuliad.service

[Unit]
Description=Zulia
After=syslog.target network.target remote-fs.target nss-lookup.target

[Service]
User=app
Group=app
Type=simple
WorkingDirectory= /usr/lib/zulia-server
ExecStart=/usr/lib/zulia-server/bin/zuliad --config /etc/zulia.yaml start
# No stop subcommand is needed: on `systemctl stop` systemd sends SIGTERM, which triggers a graceful node shutdown.
Restart=on-failure
EnvironmentFile=/etc/default/zulia
LimitFSIZE=infinity
LimitCPU=infinity
LimitAS=infinity
LimitMEMLOCK=infinity
LimitNOFILE=64000
LimitNPROC=64000

[Install]
WantedBy=multi-user.target


# save and exit

sudo systemctl daemon-reload
sudo systemctl enable zuliad.service

Address

Maryland USA