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

Address

Maryland USA