docs(getting-started-docker-compose): clarify macOS/Windows Docker Desktop data-dir step (#1124)

Operators on macOS and Windows following the docker-compose quickstart
hit `docker compose up` failures because the page tells them to run
`sudo chown -R 10000 data`, with only a very quiet inline comment
("this step might not be necessary on other than Linux platforms").

Docker Desktop handles uid remapping for bind mounts inside its Linux
VM, so the chown step is not only unnecessary on Desktop hosts, it
typically leaves `./data/...` in a state that prevents the bookie and
zookeeper containers from starting (they fail with permission errors
on their data directories).

Rework the step so the Linux path stays verbatim and add an explicit
`:::note macOS and Windows (Docker Desktop)` admonition that tells the
user to skip `chown` and, if they already ran it, to reset `./data`
before retrying `docker compose up`.

Applied to `docs/` (current) and versioned_docs for the three most
recent active LTS lines (3.3.x, 4.1.x, 4.2.x). Older versioned docs
are intentionally not backported.

Fixes apache/pulsar#23137

Author: singhvishalkr

docs/getting-started-docker-compose.md

@@ -126,14 +126,27 @@ services:
 
 ## Step 2: Create a Pulsar cluster
 
-As preparation, create data directories and change the data directory ownership to uid(10000) which is the default user id used in the Pulsar Docker container.
+As preparation, create the data directories that the `compose.yml` file will bind-mount into the Pulsar containers.
+
+On Linux, the mounted directories need to be owned by uid `10000` -- the default user inside the Pulsar Docker container -- so the containers can write to them:
 
 ```bash
 sudo mkdir -p ./data/zookeeper ./data/bookkeeper
-# this step might not be necessary on other than Linux platforms
 sudo chown -R 10000 data
 ```
 
+:::note macOS and Windows (Docker Desktop)
+
+On macOS and Windows, Docker Desktop runs containers inside a Linux VM and handles uid remapping for bind mounts for you, so the `chown -R 10000` step is not required and running it with `sudo` will typically fail or leave the files in a state that prevents `docker compose up` from starting cleanly (the bookie/zookeeper containers fail with permission errors on `./data/...`).
+
+If you see permission errors on startup, remove the `./data` directory (or reset its ownership to your user) and create it without `chown`:
+
+```bash
+mkdir -p ./data/zookeeper ./data/bookkeeper
+```
+
+:::
+
 To create a Pulsar cluster by using the `compose.yml` file, run the following command.
 
 ```bash

versioned_docs/version-3.3.x/getting-started-docker-compose.md

@@ -113,14 +113,27 @@ services:
 
 ## Step 2: Create a Pulsar cluster
 
-As preparation, create data directories and change the data directory ownership to uid(10000) which is the default user id used in the Pulsar Docker container.
+As preparation, create the data directories that the `compose.yml` file will bind-mount into the Pulsar containers.
+
+On Linux, the mounted directories need to be owned by uid `10000` -- the default user inside the Pulsar Docker container -- so the containers can write to them:
 
 ```bash
 sudo mkdir -p ./data/zookeeper ./data/bookkeeper
-# this step might not be necessary on other than Linux platforms
 sudo chown -R 10000 data
 ```
 
+:::note macOS and Windows (Docker Desktop)
+
+On macOS and Windows, Docker Desktop runs containers inside a Linux VM and handles uid remapping for bind mounts for you, so the `chown -R 10000` step is not required and running it with `sudo` will typically fail or leave the files in a state that prevents `docker compose up` from starting cleanly (the bookie/zookeeper containers fail with permission errors on `./data/...`).
+
+If you see permission errors on startup, remove the `./data` directory (or reset its ownership to your user) and create it without `chown`:
+
+```bash
+mkdir -p ./data/zookeeper ./data/bookkeeper
+```
+
+:::
+
 To create a Pulsar cluster by using the `compose.yml` file, run the following command.
 
 ```bash

versioned_docs/version-4.1.x/getting-started-docker-compose.md

@@ -126,14 +126,27 @@ services:
 
 ## Step 2: Create a Pulsar cluster
 
-As preparation, create data directories and change the data directory ownership to uid(10000) which is the default user id used in the Pulsar Docker container.
+As preparation, create the data directories that the `compose.yml` file will bind-mount into the Pulsar containers.
+
+On Linux, the mounted directories need to be owned by uid `10000` -- the default user inside the Pulsar Docker container -- so the containers can write to them:
 
 ```bash
 sudo mkdir -p ./data/zookeeper ./data/bookkeeper
-# this step might not be necessary on other than Linux platforms
 sudo chown -R 10000 data
 ```
 
+:::note macOS and Windows (Docker Desktop)
+
+On macOS and Windows, Docker Desktop runs containers inside a Linux VM and handles uid remapping for bind mounts for you, so the `chown -R 10000` step is not required and running it with `sudo` will typically fail or leave the files in a state that prevents `docker compose up` from starting cleanly (the bookie/zookeeper containers fail with permission errors on `./data/...`).
+
+If you see permission errors on startup, remove the `./data` directory (or reset its ownership to your user) and create it without `chown`:
+
+```bash
+mkdir -p ./data/zookeeper ./data/bookkeeper
+```
+
+:::
+
 To create a Pulsar cluster by using the `compose.yml` file, run the following command.
 
 ```bash

versioned_docs/version-4.2.x/getting-started-docker-compose.md

@@ -126,14 +126,27 @@ services:
 
 ## Step 2: Create a Pulsar cluster
 
-As preparation, create data directories and change the data directory ownership to uid(10000) which is the default user id used in the Pulsar Docker container.
+As preparation, create the data directories that the `compose.yml` file will bind-mount into the Pulsar containers.
+
+On Linux, the mounted directories need to be owned by uid `10000` -- the default user inside the Pulsar Docker container -- so the containers can write to them:
 
 ```bash
 sudo mkdir -p ./data/zookeeper ./data/bookkeeper
-# this step might not be necessary on other than Linux platforms
 sudo chown -R 10000 data
 ```
 
+:::note macOS and Windows (Docker Desktop)
+
+On macOS and Windows, Docker Desktop runs containers inside a Linux VM and handles uid remapping for bind mounts for you, so the `chown -R 10000` step is not required and running it with `sudo` will typically fail or leave the files in a state that prevents `docker compose up` from starting cleanly (the bookie/zookeeper containers fail with permission errors on `./data/...`).
+
+If you see permission errors on startup, remove the `./data` directory (or reset its ownership to your user) and create it without `chown`:
+
+```bash
+mkdir -p ./data/zookeeper ./data/bookkeeper
+```
+
+:::
+
 To create a Pulsar cluster by using the `compose.yml` file, run the following command.
 
 ```bash