From 92144e37717cfb0b6443c7e396c8d92678add4b3 Mon Sep 17 00:00:00 2001 From: Justin Mclean Date: Mon, 21 Sep 2026 12:41:30 +1000 Subject: [PATCH] docs: add the Docker Desktop workaround for 0.9.0 Docker Desktop rejects binding shard memory to a NUMA node, so 0.9.0 exits. Document IGGY_SHARDING_CPU_ALLOCATION=all under System requirements. --- content/docs/introduction/getting-started.mdx | 2 +- content/docs/introduction/quickstart.mdx | 2 +- content/docs/server/introduction.mdx | 3 ++- 3 files changed, 4 insertions(+), 3 deletions(-) diff --git a/content/docs/introduction/getting-started.mdx b/content/docs/introduction/getting-started.mdx index a5f54b7884..df9a4d3a71 100644 --- a/content/docs/introduction/getting-started.mdx +++ b/content/docs/introduction/getting-started.mdx @@ -5,7 +5,7 @@ description: "A first program with the low-level Rust SDK: create a stream and t ## Before we start -On Linux the server needs kernel 5.19 or newer. macOS has no kernel requirement. Under WSL2, run `wsl --update` first. See [System requirements](/docs/server/introduction#system-requirements) for the details. +On Linux the server needs kernel 5.19 or newer. macOS has no kernel requirement, but Docker Desktop on 0.9.0 needs one extra setting. Under WSL2, run `wsl --update` first. See [System requirements](/docs/server/introduction#system-requirements) for the details. This tutorial uses the **low-level Rust SDK** to show how things work under the hood - creating streams, topics, sending and polling messages step by step. This is great for understanding the fundamentals. diff --git a/content/docs/introduction/quickstart.mdx b/content/docs/introduction/quickstart.mdx index 06717b5414..1b43cb669c 100644 --- a/content/docs/introduction/quickstart.mdx +++ b/content/docs/introduction/quickstart.mdx @@ -5,7 +5,7 @@ description: "Run the Iggy server and send and receive your first message with t This page gets a server running and a message sent and received, in one file. To build separate producer and consumer applications step by step, see [Getting started](/docs/introduction/getting-started). For other languages, see the [SDK section](/docs/sdk/introduction). -On Linux the server needs kernel 5.19 or newer. macOS has no kernel requirement. See [System requirements](/docs/server/introduction#system-requirements). +On Linux the server needs kernel 5.19 or newer. macOS has no kernel requirement, but Docker Desktop on 0.9.0 needs one extra setting. See [System requirements](/docs/server/introduction#system-requirements). ## Start the server diff --git a/content/docs/server/introduction.mdx b/content/docs/server/introduction.mdx index f19c5aad94..9840fc7fcf 100644 --- a/content/docs/server/introduction.mdx +++ b/content/docs/server/introduction.mdx @@ -19,7 +19,8 @@ The server uses `io_uring` on Linux, which sets a minimum kernel version. - **Kernel 6.1 or newer is worth having.** It is the first version with the `kernel.io_uring_disabled` sysctl, so the startup diagnostics can tell you io_uring was disabled by policy instead of failing obscurely. See [Linux tuning](/docs/server/linux-tuning#runtime-access-and-process-limits). - **Ubuntu 22.04 LTS ships 5.15 and will not run the server.** Its hardware enablement kernel is new enough, and so are Ubuntu 24.04 LTS and Debian 12 as they ship. - **WSL2 often ships incomplete `io_uring`**, missing setup flags or operations even on a kernel that reports 5.19 or newer. Run `wsl --update` first. -- **macOS uses a polling backend** rather than `io_uring`, so this requirement does not apply there. +- **macOS uses a polling backend** rather than `io_uring` when the server runs natively, so this requirement does not apply there. +- **Docker Desktop needs one extra setting on 0.9.0.** Its Linux VM reports a single NUMA node but rejects binding memory to it, so the server exits with `failed to bind shard 0 memory to its NUMA node`. Add `-e IGGY_SHARDING_CPU_ALLOCATION=all` to the `docker run` command. Each shard stays pinned to its own core; only the memory binding is skipped, and on a single node it does nothing useful. The same applies to WSL2 and any other host with one NUMA node. Containers use the host's kernel, so it is the host that has to meet this requirement. See [Docker & Helm](/docs/server/docker#why-these-capabilities).