Install
Zulia requires Java 21 or greater. Tested on Java 21 and Java 25. 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/4.11.0/zulia-server-4.11.0.tar
tar xvf zulia-server-4.11.0.tar
rm zulia-server-4.11.0.tar
ln -s zulia-server-4.11.0 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.
Add node(s) and start node(s)
cd zulia-server/bin
./zuliad --config ../config/zulia.yaml addNode
./zuliad --config ../config/zulia.yaml start
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
ExecStop=/usr/lib/zulia-server/bin/zuliad --config /etc/zulia.yaml stop
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