(iggy-website) branch main updated: docs: add the Docker Desktop workaround for 0.9.0 (#113)

[kr...@apache.org]

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 <jm...@apache.org>
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 <ju...@apache.org>
    Co-authored-by: Kranti Parisa <kr...@laserdata.com>
---
 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).