searchd

Searchd is an internal search server. It is a fork of Typesense (Copyright Typesense, Inc.) and, like upstream, is licensed under the GNU General Public License v3.0 (see LICENSE.txt). The HTTP API is compatible with Typesense, so the stock Typesense client libraries work against it: the server takes X-SEARCHD-API-KEY / X-SEARCHD-USER-ID and still accepts the upstream X-TYPESENSE-API-KEY / X-TYPESENSE-USER-ID names (as headers, query parameters and per-search keys in a multi_search body).

For how the server is put together, see DESIGN.md.

Unlike upstream, vector fields with num_dim >= 64 are stored as 2-bit RaBitQ codes instead of float32 (about 15x less memory at 768 dims; distances become estimates). See docs/rabitq.md.

Requirements

Docker only (Docker Desktop / OrbStack on macOS, or Docker Engine on Linux). Give the Docker VM at least 8 GB of RAM and 4 CPUs. Nothing else is installed on the host: the toolchain (gcc-10, lld, Bazel via bazelisk) lives in the toolchain stage of the root Dockerfile.

Build for the host's native architecture. Building amd64 under emulation on Apple Silicon is very slow.

Build

docker build -t searchd .                                   # runtime image (default target)
docker build --build-arg VERSION=1.2.3 -t searchd .         # stamp a version
docker build --build-arg BAZEL_FLAGS="--jobs=4" -t searchd . # lower parallelism if OOM-killed

The Bazel cache lives in a BuildKit cache mount, so rebuilds are incremental. A cold build takes roughly 20 minutes.

Run

cp .env.example .env              # set SEARCHD_API_KEY
docker compose up server          # listens on :8108, data in ./data
curl http://localhost:8108/health

Or without compose:

docker run --rm -p 8108:8108 -e SEARCHD_API_KEY=change-me -v "$PWD/data:/data" searchd

The server is configured through SEARCHD_* environment variables (for example SEARCHD_API_KEY, SEARCHD_DATA_DIR) or the equivalent command-line flags (--api-key, --data-dir, ...). Logs go to searchd.log in --log-dir; metrics in /metrics.json are prefixed searchd_.

Test

docker build --target test .                                # full C++ unit test suite
docker build --target test \
  --build-arg TEST_FLAGS="--test_output=errors --test_arg=--gtest_filter='CollectionTest.*'" .

For incremental work use the dev service: a toolchain shell with the repo mounted at /src and the Bazel cache in a named volume.

docker compose run --rm dev bash
docker compose run --rm dev bazel test //:searchd-test --test_arg=--gtest_filter='CollectionTest.*'

HTTP API tests live in test/api/ (bun, run in CI).

Attribution

Searchd is derived from Typesense, developed by Typesense, Inc. and contributors at https://github.com/typesense/typesense. Copyright and license notices in the source files are kept as required by the GPL-3.0.