# Install and run

Install the haematite command, create a store and start the service.

Three steps: select the installed command, write a small configuration file, start the service with `--create`. The service runs in the foreground and never starts itself.

## 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


1. Put the installed bundle's bin directory on PATH and check the command answers. If the bundle is elsewhere, use that installed path.

**Terminal**

```bash
export PATH="/opt/haematite/ward-bundle/bin:$PATH"
haematite --help
```


2. 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.

**service.json**

```json
{
  "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
}
```


3. Create the store and start the service. `--create` needs a new, empty data directory.

**Terminal**

```bash
haematite serve --config service.json --create
```



## Restart later

Leave `--create` off when the store already exists.

**Terminal**

```bash
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.

**Terminal**

```bash
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](/haematite/getting-started/first-records/), then [connect an agent](/haematite/getting-started/connect-an-agent/) or [open Studio](/haematite/getting-started/studio-and-the-door/). The [configuration reference](/haematite/reference/configuration/) lists every accepted field.