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.15.5/zulia-server-4.15.5.tar
tar xvf zulia-server-4.15.5.tar
rm zulia-server-4.15.5.tar
ln -s zulia-server-4.15.5 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).
# 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
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