This is an automated email from the ASF dual-hosted git repository.
lhotari pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/pulsar-site.git
The following commit(s) were added to refs/heads/main by this push:
new fe649ceee5b docs(getting-started-docker-compose): clarify
macOS/Windows Docker Desktop data-dir step (#1124)
fe649ceee5b is described below
commit fe649ceee5b38de23d61e59378982fbd52ce2f50
Author: Vishal Kumar Singh <[email protected]>
AuthorDate: Wed Apr 22 14:20:57 2026 +0530
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
---
docs/getting-started-docker-compose.md | 17 +++++++++++++++--
.../version-3.3.x/getting-started-docker-compose.md | 17 +++++++++++++++--
.../version-4.1.x/getting-started-docker-compose.md | 17 +++++++++++++++--
.../version-4.2.x/getting-started-docker-compose.md | 17 +++++++++++++++--
4 files changed, 60 insertions(+), 8 deletions(-)
diff --git a/docs/getting-started-docker-compose.md
b/docs/getting-started-docker-compose.md
index 7829ba2ceb4..cc62133f8ab 100644
--- a/docs/getting-started-docker-compose.md
+++ b/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
diff --git a/versioned_docs/version-3.3.x/getting-started-docker-compose.md
b/versioned_docs/version-3.3.x/getting-started-docker-compose.md
index 60614944207..cc869926690 100644
--- a/versioned_docs/version-3.3.x/getting-started-docker-compose.md
+++ b/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
diff --git a/versioned_docs/version-4.1.x/getting-started-docker-compose.md
b/versioned_docs/version-4.1.x/getting-started-docker-compose.md
index 7829ba2ceb4..cc62133f8ab 100644
--- a/versioned_docs/version-4.1.x/getting-started-docker-compose.md
+++ b/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
diff --git a/versioned_docs/version-4.2.x/getting-started-docker-compose.md
b/versioned_docs/version-4.2.x/getting-started-docker-compose.md
index 7829ba2ceb4..cc62133f8ab 100644
--- a/versioned_docs/version-4.2.x/getting-started-docker-compose.md
+++ b/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
