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

> How I run the official Luxir Linux binary in Docker on a Mac or Windows laptop, including ARM machines, without installing Linux or compiling C++.

Date: 2026-09-26.

## Subjects

- [Luxir](https://oppority.com/topics/luxir.md)
- [Hybrid search](https://oppority.com/topics/hybrid-search.md)
- [Guides](https://oppority.com/topics/guides.md)

## Also published at

- [DEV](https://dev.to/sjayesh/run-luxir-on-a-mac-or-windows-laptop-no-linux-no-c-k6l)
- [Medium](https://medium.com/@jayesh.shende/run-luxir-on-a-mac-or-windows-laptop-no-linux-no-c-e44a101fddcd)
- [LinkedIn](https://www.linkedin.com/pulse/run-luxir-mac-windows-laptop-linux-c-jayesh-shende-yesdf/)

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

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

1. Start Docker Desktop and wait until it is idle.
2. **Settings -> General -> Use Rosetta for x86/amd64 emulation** -> on.
3. **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:

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

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

PowerShell:

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

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

1. `Dockerfile`
2. `docker-compose.yml`
3. `books.ndjson`
4. `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.

```dockerfile
# 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.

```yaml
# 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.

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

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

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

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

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

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

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

```bash
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):

```bash
docker compose down
```

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

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

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

- [Download](https://luxir.org/download/)
- [Quickstart](https://luxir.org/docs/latest/guide/quickstart/)
- [HTTP API](https://luxir.org/docs/latest/guide/http-api/)
- [Operations](https://luxir.org/docs/latest/guide/operations/)
- [Release v0.1.0](https://github.com/luxir-search/luxir/releases/tag/v0.1.0)
- [Docker Desktop](https://docs.docker.com/desktop/)

## About this guide

**[Jayesh Shende](https://www.linkedin.com/in/mrjayeshshende/)** 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.