very fast at protocol indexer with flexible filtering, xrpc queries, cursor-backed event stream, and more, built on fjall
rust
fjall
at-protocol
atproto
indexer
1---
2title: getting started
3---
4
5## requirements
6
7hydrant is written in rust and requires the rust toolchain (including `cargo`), `make`, `cmake` for some dependencies. you will also need the clang toolchain and the [wild linker](https://github.com/wild-linker/wild).
8
9## building from source
10
11```bash
12cargo build --release
13```
14
15the binary will be at `target/release/hydrant`.
16
17to build with optional features (e.g. `backlinks`):
18
19```bash
20cargo build --release --features backlinks
21```
22
23see [build features](build-features.md) for the full list.
24
25## running
26
27set the required environment variables and run the binary:
28
29```bash
30export HYDRANT_DATABASE_PATH=./hydrant.db
31./target/release/hydrant
32```
33
34see [configuration](configuration.md) for all available variables. if a `.env` file exists in the working directory it will be loaded automatically.
35
36## reverse proxying
37
38it is **highly recommended** to run hydrant behind a reverse proxy (like nginx or caddy) if you intend to expose the XRPC or event stream APIs to the public. hydrant's API includes several management endpoints that do not require or support authentication. **you MUST NOT expose these management endpoints to the public internet.**
39
40### public endpoints (safe to proxy)
41
42- `/xrpc/*`: XRPC endpoints.
43- `/stream`: hydrant's ordered event stream.
44- `/stats`: general database statistics.
45- `/health` / `/_health`: health check.
46
47### management endpoints (keep private)
48
49- `/repos`: explicit repository tracking/resyncing/untracking.
50- `/filter`: management of NSID filter patterns.
51- `/ingestion`: manual control over component lifecycle (crawler, firehose, etc.).
52- `/crawler/sources`: management of crawler relays.
53- `/firehose/sources`: management of firehose relays.
54- `/pds/tiers`: rate-limit tier assignments.
55- `/db/train` / `/db/compact`: database maintenance tasks.
56- `*/cursors`: cursor management.
57- `/debug/*`: introspection and testing endpoints.