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

Address

Maryland USA