Run Luxir on a Mac or Windows laptop (no Linux, no C++)

Jayesh Shende — Sat, 26 Sep 2026 20:08:52 +0000

Luxir ships a Linux x86-64 binary. This post is how I run that build in Docker on a laptop that is not Linux, including ARM machines that have to emulate linux/amd64. Four files, docker compose up, then a small index and search. Good enough to try the API. Not how you measure production speed.

What is Luxir?

Luxir is a new open-source hybrid search engine. You put documents in. You ask for the ones that match words, numbers, maps, or vectors. It talks HTTP and JSON on port 9400, so curl is enough. There is also gRPC on 9401 for programs. Official site: luxir.org.

Yonik Seeley created it. He is the original author of Apache Solr and a longtime Lucene/Solr committer. Luxir is not Solr, Lucene, Elasticsearch, or OpenSearch. It is a separate C++ engine, Apache License 2.0, first public release 0.1.0 (September 2026). It is pre-1.0: APIs and on-disk format can still change.

What it does, in one list (from the project's own docs):

Full-text ranking (BM25), plus a small query language you can type by hand
Vector / kNN search, with filters applied inside the vector search
Hybrid ranking: lexical and vector in one request (rank fusion)
Facets and analytics on the same index view (counts, ranges, metrics)
Geo (box and radius), composed with the rest
No JVM. Native code. The pitch is more search per core, per gigabyte, and per dollar
Collections appear on first write. You can start without declaring a schema

If you already know Solr or Elasticsearch: think "one process, curl-first, text plus vectors plus facets," not "a cluster you assemble from plugins."

Why this guide exists

Luxir is new enough that most people have never heard of it. The official ready-made program is a Linux x86-64 download. If you evaluate search engines on a Mac or Windows laptop, you hit that wall before you ever send a query.

This page exists so you can try Luxir this afternoon without installing Linux, without compiling C++, and without treating Docker emulation as production. The engine is Yonik Seeley and contributors (luxir.org). This walkthrough is a community how-to around the official Linux binary, not a project release. If anything here disagrees with the official docs, follow the docs.

How-to facts


Software	Luxir 0.1.0 (Apache License 2.0), by Yonik Seeley and contributors
This page	Community Docker walkthrough (four files). Not an official image or download.
Written	27 September 2026
Host need	Docker that can run `linux/amd64` (native or simulated)
Ports	HTTP 9400, gRPC 9401
Time	About 20-40 minutes the first time (image download)

Can you run Luxir without Linux or C++?

Yes. The official 0.1.0 program is a Linux x86-64 v2 binary. You can run that same binary on a Mac or Windows PC if Docker can simulate linux/amd64 (Rosetta or QEMU on Apple Silicon and other ARM machines). You do not dual-boot Linux. You do not compile C++. You are not running a rewrite.

This is a laptop demo, not a production or benchmark setup. Official docs: luxir.org, HTTP API, operations.

Key takeaways

Luxir is a new C++ hybrid search engine (text, vectors, facets, geo) from Yonik Seeley. Site: luxir.org.
Official 0.1.0 binaries target Linux x86-64. Other chips use Docker platform simulation.
Four files in luxir-try: Dockerfile, docker-compose.yml, books.ndjson, search.json. Then docker compose up --build -d.
Health: http://127.0.0.1:9400/health -> {"status":"ok"}. Index with ?commit=true or search can be empty.
For production, use Linux x86-64 without emulation.

This guide assumes you already have Docker Desktop (or Docker Engine + Compose V2), a terminal, and curl. The part most people miss is platform simulation: Luxir's official binary is linux/amd64, so ARM hosts must emulate that platform, and Docker Desktop often needs a setting turned on first.

Commands: Unix-style curl below. In Windows PowerShell, use curl.exe (plain curl is often Invoke-WebRequest).

Part 1 - Enable linux/amd64 simulation (then confirm Docker)

Luxir 0.1.0 does not ship a native ARM build. The Compose file pins platform: linux/amd64. On an Intel/AMD machine that pin is a no-op. On Apple Silicon or Windows ARM, Docker must translate x86-64 (Rosetta on Mac, QEMU elsewhere). That is slower than native Linux. Fine for trying the API. Wrong for QPS numbers.

Apple Silicon (this is the setting people skip):

Start Docker Desktop and wait until it is idle.
Settings -> General -> Use Rosetta for x86/amd64 emulation -> on.
Apply & Restart if Docker asks.

If that checkbox is missing, update Docker Desktop. Without it, docker compose up often fails with exec format error, a crash loop, or a container that never becomes healthy.

Intel Mac or typical x86 Windows: no extra checkbox. Keep the linux/amd64 pin in Compose anyway so the same files work on an ARM laptop later.

Windows ARM: use Docker Desktop's amd64 emulation (usually WSL 2). If the engine never starts, emulation is off or incomplete.

Confirm the CLI:

docker version
docker compose version

You want a running Engine and Compose V2. Cannot connect to the Docker daemon means Desktop is still starting. docker compose: command not found means an old install; update Desktop rather than adding a random docker-compose binary.

Part 2 - Four files in `luxir-try`

mkdir -p ~/luxir-try && cd ~/luxir-try

PowerShell:

mkdir $HOME\luxir-try; cd $HOME\luxir-try

Save these four names exactly (Dockerfile with no extension):

Dockerfile
docker-compose.yml
books.ndjson
search.json

File 1 - `Dockerfile`

This file tells Docker: start from Ubuntu Linux, download the official Luxir 0.1.0 Linux x86-64 v2 program, and run it. v2 is the widest Intel/AMD tier. Use it under Mac emulation. Do not change it to v3 or v4 for a first try.

# Runtime image: official Luxir Linux x86-64 v2 binary.
# Always build and run as linux/amd64 (Rosetta/QEMU on Apple Silicon).
#
# Do not use this image for production performance numbers on ARM hosts.

FROM --platform=linux/amd64 ubuntu:22.04

ARG LUXIR_VERSION=0.1.0
ARG LUXIR_CPU_TIER=v2
ARG DEBIAN_FRONTEND=noninteractive

RUN apt-get update \
    && apt-get install -y --no-install-recommends ca-certificates curl tzdata \
    && rm -rf /var/lib/apt/lists/*

# v2 is the widest x86-64 tier and the one to use under Apple Silicon emulation.
RUN curl -fL --retry 3 \
      "https://github.com/luxir-search/luxir/releases/download/v${LUXIR_VERSION}/luxir-${LUXIR_VERSION}-linux-x86_64-${LUXIR_CPU_TIER}" \
      -o /usr/local/bin/luxir \
    && chmod +x /usr/local/bin/luxir

RUN groupadd --system luxir \
    && useradd --system --gid luxir --home-dir /var/lib/luxir --create-home luxir

USER luxir
WORKDIR /var/lib/luxir
EXPOSE 9400 9401
VOLUME ["/var/lib/luxir"]

HEALTHCHECK --interval=15s --timeout=3s --start-period=10s --retries=3 \
    CMD curl -sf http://127.0.0.1:9400/health || exit 1

ENTRYPOINT ["luxir"]
CMD ["--store.backend=fs", "--store.data-dir=/var/lib/luxir"]

File 2 - `docker-compose.yml`

This file tells Docker: build that Dockerfile as a linux/amd64 image, publish ports 9400 and 9401 on your laptop, and keep the search index in a named volume so data survives a restart.

# Luxir try-out. Forces linux/amd64 so Apple Silicon uses the official
# x86-64 binary (Rosetta/QEMU). Not for production capacity planning.
#
# From this folder:
#   docker compose up --build -d

services:
  luxir:
    image: luxir:try
    platform: linux/amd64
    build:
      context: .
      dockerfile: Dockerfile
      platforms:
        - linux/amd64
    ports:
      - "9400:9400"
      - "9401:9401"
    volumes:
      - luxir-data:/var/lib/luxir
    restart: unless-stopped

volumes:
  luxir-data:

File 3 - `books.ndjson`

Two documents. Each line is one JSON object. That format is called NDJSON (newline-delimited JSON). Luxir creates the books collection on the first write.

{"id":"1","title_t":"Dune","author_name":"Frank Herbert","year_i":1965}
{"id":"2","title_t":"Dune Messiah","author_name":"Frank Herbert","year_i":1969}

title_t is full text. year_i is an integer. author_name is a name field. You do not need to understand the schema yet.

File 4 - `search.json`

{"query":"author_name:herbert AND year_i:<1970","fields":["id","title_t","year_i"]}

Confirm: ls Dockerfile docker-compose.yml books.ndjson search.json

Part 3 - Ports 9400 and 9401

curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1:9400/health

000 or a connection error means the port is free. 200 means something (often an old Compose stack) is already bound; from this folder run docker compose down, or stop the other process.

Part 4 - Build and start

First run pulls Ubuntu plus about 80 MB for the Luxir binary.

docker compose up --build -d
docker compose ps
docker compose logs --tail 30

You should see: Built / Started, service luxir, image luxir:try, ports 9400-9401. Health may say starting for 10-20 seconds. Logs should show a Luxir banner, not a crash loop.

On Apple Silicon, docker compose ps should list linux/amd64. If the platform is arm64, the pin did not apply; do not continue until it does.

Pull or certificate errors: check the network and rerun the same up --build. Docker reuses layers.

Part 5 - Health

curl -sS http://127.0.0.1:9400/health

{"status":"ok"}

If the connect fails, docker compose ps and docker compose logs. If the container exits or restarts on ARM, go back to Part 1 (Rosetta / emulation).

Part 6 - Index two documents

commit=true publishes the write. Without it, search can return no hits.

curl -sS -X POST "http://127.0.0.1:9400/collections/books/_update?commit=true" \
  -H "Content-Type: application/x-ndjson" \
  --data-binary @books.ndjson

You should see: "status":"ok" and an update_version.

Part 7 - Search

curl -sS "http://127.0.0.1:9400/collections/books/_search?pretty" \
  -H "Content-Type: application/json" \
  --data-binary @search.json

You should see: two hits, Dune (1965) and Dune Messiah (1969).

More queries: Luxir's quickstart against http://127.0.0.1:9400.

Part 8 - Stop, start again, or wipe the data

Stay in luxir-try.

Stop Luxir (the program stops; your indexed books stay on disk):

docker compose down

Start again (no rebuild if the image already exists):

docker compose up -d

After it is healthy, the books collection is still there. You can jump to Part 7.

Wipe the index (only if you want a clean slate). This deletes the Docker volume luxir-data:

docker compose down -v

If something went wrong

Cannot connect to the Docker daemon - Desktop is not running yet.
docker compose: command not found - update Docker Desktop.
stat Dockerfile / no such file - wrong directory, or the file is Dockerfile.txt.
GitHub release curl hangs - network; open v0.1.0 in a browser, retry up --build.
port is already allocated - docker compose down or stop whatever owns 9400/9401.
exec format error, crash loop, or health never ok on ARM - Rosetta / amd64 emulation is off (Part 1). docker compose ps must show linux/amd64, not arm64.
Empty docs - missing commit=true, or you are hitting a different process on 9400.
PowerShell curl looks like HTML - use curl.exe.

Why `platform: linux/amd64` is required

Docker can store several CPU variants under one image name and pick one on pull. Luxir 0.1.0 only publishes a Linux x86-64 binary, so this Compose file forces linux/amd64.

On Apple Silicon or Windows ARM, that means simulation: Rosetta (Mac) or QEMU (typical Linux/Windows ARM). You run the real official binary. You do not get native ARM speed. Use the v2 CPU tier in the Dockerfile; v3/v4 need newer x86 instruction sets and are a poor first try under emulation.

Do not use this setup for production

For anything you would call production:

Use Linux x86-64 on a real machine or a same-architecture VM. No emulation.
Download the matching official binary from luxir.org/download, or follow Luxir's own container build.
Give the machine enough RAM to hold the index.
Add your own TLS and login. Luxir 0.1.0 has none. Do not put port 9400 on the public internet.
Treat the API and on-disk format as pre-1.0. They can change. Read the operations guide.

FAQ

What is Luxir, and who created it?

Luxir is an open-source hybrid search engine in C++ (full text, vectors, facets, geo). HTTP JSON on port 9400, gRPC on 9401. Yonik Seeley (original author of Apache Solr) and contributors. Apache License 2.0, version 0.1.0. luxir.org, github.com/luxir-search/luxir.

Is this an official Luxir Docker image?

No. This page is a community how-to. It downloads the official linux-x86_64-v2 binary from the v0.1.0 release and runs it in Ubuntu under Docker. It is not a project image and does not replace luxir.org/download. If this guide and the official docs disagree, follow luxir.org.

What do I turn on in Docker Desktop?

On Apple Silicon: Settings -> General -> Use Rosetta for x86/amd64 emulation. Apply & Restart. Intel/AMD hosts do not need that box; they already are amd64. Windows ARM needs Docker's amd64 emulation (usually WSL 2). After up, docker compose ps should show linux/amd64.

Can I run Luxir on a Mac or Windows PC without installing Linux?

Yes, if Docker can run linux/amd64 (natively or simulated). You still need Docker. You do not compile C++.

Which CPU do I need?

Native Intel/AMD, or ARM with platform simulation enabled. Use the v2 binary for a first try.

Why is my search empty after I index?

Include commit=true on the update (Part 6).

Should I use this for production or benchmarks?

No. Use Linux x86-64 without emulation. See luxir.org/download and the operations guide.

Sources and credit

Luxir is Yonik Seeley and contributors, Apache License 2.0. Engine behavior is defined at luxir.org.

About this guide

Jayesh Shende writes notes on search engines (Solr, OpenSearch, Luxir) while evaluating them. This walkthrough is a community how-to around the official binary, not a Luxir project publication. Corrections that match the official docs are welcome.

DEV Community: Jayesh Shende