02 · START

Install

XERJ ships as a single static binary. No JVM, no installer, no package manager yet — download the tarball, verify the checksum, move the binary into place, write a 20-line config, start it as a systemd unit.

System requirements

OS: Linux (any distro — the Linux build is fully static musl, Alpine included), macOS (Apple Silicon arm64 / Intel x86_64), or Windows 10+ (x64 / ARM64).
RAM: 400 MB idle. 2 GB working set per active index. Scales linearly with segment resident set.
Disk: Any fs that supports fsync and mmap. Prefer SSD.
CPU: x86_64 with AVX2 or arm64 with NEON. The release build uses SIMD for hot paths.
Open files: 65536 ulimit is sufficient for most deployments.

Install with one command

The installer detects your OS and CPU, downloads the matching release from GitHub Releases, and verifies its SHA-256.

Linux / macOS (x86_64 and arm64):

$ curl -fsSL https://xerj.org/get | sh

Windows (x64 and ARM64, PowerShell):

> powershell -ExecutionPolicy Bypass -c "irm https://xerj.org/get.ps1 | iex"

Manual download

Every release publishes eight targets, each with a .sha256 alongside: x86_64/aarch64 × unknown-linux-musl (static, any distro), unknown-linux-gnu, apple-darwin, and pc-windows-msvc (.zip).

$ ver=$(curl -fsSL https://api.github.com/repos/xerj-org/xerj/releases/latest | sed -n 's/.*"tag_name": *"v\([^"]*\)".*/\1/p')
$ curl -fsSLO https://github.com/xerj-org/xerj/releases/download/v${ver}/xerj-${ver}-x86_64-unknown-linux-musl.tar.gz
$ curl -fsSLO https://github.com/xerj-org/xerj/releases/download/v${ver}/xerj-${ver}-x86_64-unknown-linux-musl.tar.gz.sha256
$ sha256sum -c xerj-${ver}-x86_64-unknown-linux-musl.tar.gz.sha256
$ tar xzf xerj-${ver}-x86_64-unknown-linux-musl.tar.gz
$ sudo install -m 0755 xerj-${ver}-x86_64-unknown-linux-musl/xerj /usr/local/bin/xerj
$ xerj --version

Write the config

The minimal config is three sections. Everything else uses defaults — see the config reference for the full key list.

# /etc/xerj/xerj.toml
[server]
rest_port    = 8080
bind_address = "0.0.0.0"
data_dir     = "/var/lib/xerj"

[auth]
enabled = true

With auth.enabled = true, the first start prints an auto-generated admin API key and writes it to <data_dir>/admin.key — every native-API request (including health) must send it. In-process TLS is not wired yet (rustls integration is on the roadmap) — terminate TLS at a reverse proxy (nginx/caddy) in front of ports 8080/9200 for now.

Run as a systemd unit

Create the service user first — StateDirectory then gives it /var/lib/xerj automatically:

$ sudo useradd -r -s /usr/sbin/nologin xerj

# /etc/systemd/system/xerj.service
[Unit]
Description=XERJ storage engine
Wants=network-online.target
After=network-online.target

[Service]
User=xerj
Group=xerj
StateDirectory=xerj
ExecStart=/usr/local/bin/xerj --config /etc/xerj/xerj.toml
Restart=on-failure
LimitNOFILE=65536
ProtectSystem=strict
ReadWritePaths=/var/lib/xerj

[Install]
WantedBy=multi-user.target

$ sudo systemctl daemon-reload
$ sudo systemctl enable --now xerj
$ sudo systemctl status xerj
$ curl -s -H "Authorization: ApiKey $(sudo cat /var/lib/xerj/admin.key)" \
    http://localhost:8080/v1/health

Docker

No published image yet — build it locally from engine/Dockerfile (the image defaults to --insecure --data-dir /data, right for CI and local dev):

$ docker build -t xerj:1.0.0-rc.1 engine/
$ docker run -d --name xerj \
    -p 8080:8080 -p 9200:9200 \
    -v xerj-data:/data \
    xerj:1.0.0-rc.1

Source · engine/README.md

◀ PREVQuickstart

NEXT ▶Migrate from ES