getting-started.md

Getting Started

Prerequisites

• Rust 1.99+ (edition 2024) -- install via rustup
• cargo (included with Rust)
• Docker (optional, for containerized deployment)

Building from Source

Clone the repository and build all crates:

cargo build --locked --workspace --exclude rusty-haystack

The rusty-haystack crate (Python bindings) is excluded because it is a PyO3 extension module: it is linked against a Python interpreter that only exists at import time, so cargo build cannot link it and fails with undefined _Py_* symbols. Build it with maturin instead — see Python Bindings for setup, or CONTRIBUTING.md for the full explanation.

To build only the CLI binary:

cargo build --locked -p rusty-haystack-cli --release

The binary is at target/release/haystack.

Running Tests

cargo test --locked --workspace --exclude rusty-haystack

This runs unit tests, integration tests and doctests for the selected crates.

Starting the Demo Server

The CLI includes a built-in demo dataset with building automation entities (sites, equips, points):

cargo run -p haystack-cli -- serve --demo --port 8080

Or with the release binary:

./target/release/haystack serve --demo --port 8080

The server starts on http://127.0.0.1:8080 by default.

First API Call

Query server info:

curl http://localhost:8080/api/about

List all operations:

curl http://localhost:8080/api/ops

Read all sites (Zinc format):

curl -X POST http://localhost:8080/api/read \
  -H "Content-Type: text/zinc" \
  -d 'ver:"3.0"
filter
"site"'

Read all sites (JSON format):

curl -X POST http://localhost:8080/api/read \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"meta":{"ver":"3.0"},"cols":[{"name":"filter"}],"rows":[{"filter":"site"}]}'

Navigate the entity tree:

curl -X POST http://localhost:8080/api/nav \
  -H "Content-Type: text/zinc" \
  -d 'ver:"3.0"
empty'

Using the CLI

Import entities from a Zinc file and print summary:

haystack import data/entities.zinc

Export entities to JSON:

cat data/entities.zinc | haystack export --format json

Validate entities against the Haystack ontology:

haystack validate data/entities.zinc

Explore the standard library:

haystack info --def ahu
haystack libs
haystack specs --lib ph

See CLI Reference for the full command reference.

Docker

Build the image:

docker build -t rusty-haystack .

Run with the demo dataset:

docker run -p 8080:8080 rusty-haystack serve --demo --port 8080

Run with a data file and user authentication:

docker run -p 8080:8080 \
  -v ./data:/data \
  rusty-haystack serve \
    --file /data/entities.zinc \
    --users /data/users.toml \
    --port 8080

See Configuration for details on the users TOML format.

Server with Authentication

1. Create a users file:

haystack user add admin --file users.toml --password s3cret --permissions read,write,admin
haystack user add viewer --file users.toml --password viewpass --permissions read

2. Start the server with auth:

haystack serve --demo --users users.toml --port 8080

3. Authenticate with the client CLI:

haystack client about --url http://localhost:8080/api -U admin -P s3cret
haystack client read "site" --url http://localhost:8080/api -U admin -P s3cret

Running Benchmarks

cargo bench -p haystack-core
cargo bench -p haystack-server

Results are saved to target/criterion/. See Benchmarks.md for published results.

Next Steps

• Architecture -- system design and core abstractions
• Server API -- full HTTP endpoint reference
• Client Library -- using HaystackClient in Rust code
• Configuration -- server setup, users, permissions