This is an automated email from the ASF dual-hosted git repository.
kparisa pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/iggy-website.git
The following commit(s) were added to refs/heads/main by this push:
new e5dc87f75 docs: add the Docker Desktop workaround for 0.9.0 (#113)
e5dc87f75 is described below
commit e5dc87f75a543eb417ba4e73ed280d5ad165607f
Author: Justin Mclean <[email protected]>
AuthorDate: Tue Oct 6 16:53:50 2026 +1100
docs: add the Docker Desktop workaround for 0.9.0 (#113)
The quickstart command does not start 0.9.0 on Docker Desktop: the VM
rejects binding shard memory to its NUMA node. `-e
IGGY_SHARDING_CPU_ALLOCATION=all` works around it.
Adds this to System requirements and points to it from the quickstart
and getting started pages.
Workaround for apache/iggy#4242.
Co-authored-by: Justin Mclean <[email protected]>
Co-authored-by: Kranti Parisa <[email protected]>
---
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 a5f54b788..df9a4d3a7 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 06717b541..1b43cb669 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 f19c5aad9..9840fc7fc 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).
