Skip to main content

Install the server

Celeriant is one Rust binary, Linux only: the storage engine runs on io_uring and Direct I/O. For development you run one standalone node; for production a two-node cluster.

Two install paths today. No prebuilt binaries are published.

  1. Container image at ghcr.io/celeriant/celeriant, amd64 and arm64, tagged per release (0.2.0) plus latest. Recommended; it is also the only path on macOS and Windows.
  2. Build from source.

Container​

docker run -d --name celeriant \
  --security-opt seccomp=unconfined \
  --ulimit memlock=-1:-1 \
  -p 10000:10000 \
  -v celeriant-data:/var/lib/celeriant \
  ghcr.io/celeriant/celeriant:0.2.0 \
  --standalone --data-root /var/lib/celeriant --num-shards 1

Docker's default seccomp profile blocks io_uring, so seccomp=unconfined is required. The unlimited memlock matches what the repo's own Compose stack and test image set for io_uring. The image's entrypoint is the server binary, so everything after the image name is server flags.

To build the image yourself, the repo's Dockerfile is two-stage: docker build -t celeriant .

Build from source​

git clone https://github.com/celeriant/celeriant-db
cd celeriant-db
cargo build --release -p celeriant
# binary at ./target/release/celeriant

The workspace is Rust edition 2024, so a toolchain of 1.85 or newer.

./target/release/celeriant \
  --standalone \
  --data-root /var/lib/celeriant \
  --num-shards 1

What the server checks at boot​

  • Direct I/O. It writes a deliberately misaligned block into --data-root. If the write succeeds, the filesystem is silently buffering instead of honouring O_DIRECT, and the server exits. It also exits if a 512-byte aligned write fails. Some encrypted filesystems fail the first check. XFS and ext4 enforce O_DIRECT; the repo's own cluster setup scripts format XFS.
  • Ports. It exits if the client port (default 10000) or the replication port (default 10001) is already taken, even in standalone mode.
  • Immutable settings. --num-shards, --timestamp-precision, --timestamp-epoch-offset-secs, --routing-rule, --reserve-coordinator-shard and the WAL compression settings are recorded in the data root on first start. Start again with a different value and the server refuses. --num-shards defaults to the CPU count, so pin it.

Metrics listen on port 9090 by default. Every flag also reads a CELERIANT_ environment variable (--data-root is CELERIANT_DATA_ROOT); see Configuration.

For a local two-node cluster with MinIO standing in for S3, Prometheus, Loki and Grafana, use the Compose stack in deploy/local-cluster: docker compose up -d --build. See Running a two-node cluster.

Next: install a client.