Install and run — Ablative docs

Before you begin

You need a Unix machine and an operator bundle containing haematite and, for the query examples, haematite-jq. Put that bundle at its installed path. Building the repository requires Rust 1.89 or later and the pinned toolchain; the bundle steps below use existing binaries.

From crates.io

Installing from crates.io (0.21.0): From 0.21.0, haematite, haematite-query, haematite-jq and haematite-cli are published to crates.io. Install the command with cargo install haematite-cli --version 0.21.1 --bin haematite. Install the query worker with cargo install haematite-jq --version 0.21.0, and point query_worker at the installed haematite-jq path. haematite-query is a library dependency; it does not install an executable.

From an operator bundle

Put the installed bundle’s bin directory on PATH and check the command answers. If the bundle is elsewhere, use that installed path.
```
export PATH="/opt/haematite/ward-bundle/bin:$PATH"
haematite --help
```

Write a configuration file. It names the data directory, the socket, the service’s limits and, for --create, how the new store is laid out. The base limits are required. The create object is required for —create, and all six query fields are required together to enable queries. Point query_worker at an installed haematite-jq. The example numbers are explicit bounds, not built-in defaults. If you leave the socket out, the service uses the private runtime namespace of the operating system.

{
  "data_dir": "/var/lib/haematite/ward",
  "socket": "/run/haematite/ward.sock",
  "branch_cache_bytes_per_shard": 67108864,
  "max_frame": 4194304,
  "max_clients": 32,
  "max_page": 500,
  "timeout_ms": 30000,
  "create": {
    "shards": 4,
    "cache_bytes_total": 268435456,
    "executor_threads": 4
  },
  "query_worker": "/opt/haematite/ward-bundle/bin/haematite-jq",
  "query_time_ms": 30000,
  "query_memory_bytes": 67108864,
  "query_outputs_per_record": 10000,
  "query_scan_records": 10000,
  "query_max_running": 2
}

Create the store and start the service. --create needs a new, empty data directory.
```
haematite serve --config service.json --create
```

Restart later

Leave --create off when the store already exists.

haematite serve --config service.json

Check that it answers

Ask the running service for its collections. A new store has none yet, so the list comes back empty.

haematite call --config service.json collections.list \
  '{"selection":{"branch":"main"},"limit":20}'

If something goes wrong

--create is refused. Read the actual refusal. Restart without —create for an existing store, or choose a new data directory for a new store.
The socket’s directory is missing or too open. Create it with mkdir -m 0700.
endpoint_too_long. A socket path must be short, under about 100 characters on macOS. Put the socket in a short directory such as /run/haematite.
--create needs a create section. Add the create object from the example.
You see long-wait warnings. The service prints one when a wait exceeds the interval, 30 seconds by default. It is a warning, not a deadline, and the work continues.

Next step

Write your first records, then connect an agent or open Studio. The configuration reference lists every accepted field.