Skip to content

Update quick-start docs: fix error handling, update default version t… #3260

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
dataroaring wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Update quick-start docs: fix error handling, update default version t… #3260

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 15 additions & 1 deletion docs/gettingStarted/quick-start.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,7 +33,7 @@ chmod 755 start-doris.sh

### Step 2: Start the cluster

Run the script to start the cluster, using the `2.1.9` version by default
Run the script to start the cluster, using the `4.0.1` version by default

```shell
bash start-doris.sh
Expand Down Expand Up @@ -245,8 +245,22 @@ Download the corresponding binary installation package from the Apache Doris web
4 rows in set (0.10 sec)
```

## FAQs

**Q: How do I install Docker on Mac?**

A: Download and install [Docker Desktop](https://www.docker.com/products/docker-desktop/).

**Q: Mac: "Error: Docker environment not detected" after Docker Desktop is installed**

A: Create a symlink:

```shell
sudo ln -s /Applications/Docker.app/Contents/Resources/bin/docker /usr/local/bin/docker
```

**Q: Mac: "error getting credentials - err: exit status 1, out: \`\`"**

A: Remove the `credsStore` field in `~/.docker/config.json`.
Copy link

Copilot AI Jan 6, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The instruction to remove the credsStore field from ~/.docker/config.json degrades Docker's credential security by disabling the OS-backed credential store and causing registry logins to be stored in plaintext in the config file. An attacker or malware that can read this file (for example via backups, local compromise, or other leaks) can extract Docker registry credentials and gain unauthorized access to private images or push malicious ones. Instead of recommending unconditional removal of credsStore, consider documenting how to fix the credential helper configuration or clearly warn about the security impact and provide a safer workaround.

Copilot uses AI. Check for mistakes.


16 changes: 15 additions & 1 deletion i18n/zh-CN/docusaurus-plugin-content-docs/current/gettingStarted/quick-start.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,7 @@ chmod 755 start-doris.sh

### 第 2 步：启动集群

运行脚本，启动集群，默认使用`2.1.9`版本
运行脚本，启动集群，默认使用 `4.0.1` 版本

```shell
bash start-doris.sh
Expand Down Expand Up @@ -245,7 +245,21 @@ mysql -uroot -P9030 -h127.0.0.1 -e 'SELECT `host`, `alive` FROM backends()'
4 rows in set (0.10 sec)
```

## 常见问题

**Q: 如何在 Mac 上安装 Docker？**

A: 下载并安装 [Docker Desktop](https://www.docker.com/products/docker-desktop/)。

**Q: Mac: 安装 Docker Desktop 后仍提示 "Error: Docker environment not detected"**

A: 创建符号链接：

```shell
sudo ln -s /Applications/Docker.app/Contents/Resources/bin/docker /usr/local/bin/docker
```

**Q: Mac: "error getting credentials - err: exit status 1, out: \`\`"**

A: 删除 `~/.docker/config.json` 中的 `credsStore` 字段。

Comment on lines +264 to 265
Copy link

Copilot AI Jan 6, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

文档中建议删除 ~/.docker/config.json 中的 credsStore 字段，会关闭 Docker 的系统凭据存储机制，使仓库登录信息以明文形式保存在配置文件中，从而显著降低凭据安全性。能够读取该文件的攻击者或恶意程序（例如通过本地入侵或备份泄露）可以直接获取 Docker 仓库账号，进而未授权访问私有镜像或推送恶意镜像。建议不要无条件删除 credsStore，而是引导用户修复凭据助手配置，或在文档中明确说明安全影响并提供更安全的替代方案。

Suggested change
A: 删除 `~/.docker/config.json` 中的 `credsStore` 字段。
A: 此错误通常与 Docker 凭据助手（credential helper）配置异常有关，建议按以下顺序排查：
- 确认已正确安装并启动 Docker Desktop，必要时重新安装或升级到最新版本。
- 检查 `~/.docker/config.json` 中的 `credsStore` 或 `credHelpers` 配置，与当前系统和 Docker 版本是否匹配，可参考官方文档进行修复：
- https://docs.docker.com/engine/reference/commandline/login/#credentials-store
- 如需临时绕过凭据助手，可在**仅用于本地开发测试、且配置文件不包含敏感账号密码**的前提下，备份该文件后再调整配置。
:::caution 安全提示
不要随意删除 `~/.docker/config.json` 中的 `credsStore` 字段，否则 Docker 会将仓库登录信息以明文形式保存在该文件中。一旦本机或备份泄露，攻击者可能直接获取私有仓库账号，从而拉取或推送恶意镜像。生产环境或包含真实账号的环境中，请务必使用系统凭据存储或安全的凭据管理方案。
:::

Copilot uses AI. Check for mistakes.
25 changes: 23 additions & 2 deletions ...zh-CN/docusaurus-plugin-content-docs/version-3.x/gettingStarted/quick-start.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,12 +28,19 @@
chmod 755 start-doris.sh
```


### 第 2 步：启动集群

运行脚本，启动集群，默认使用`2.1.9`版本，可通过 -v 参数指定启动版本，如：
运行脚本，启动集群，默认使用 `4.0.1` 版本

```shell
bash start-doris.sh
```

可通过 -v 参数指定启动版本，如：

```shell
bash start-doris.sh -v 3.0.4
bash start-doris.sh -v 2.1.8
Copy link

Copilot AI Jan 6, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The example version used here should be a 3.x version (e.g., 3.0.4 as shown in the original) rather than 2.1.8, since this is the version-3.x documentation. Users reading the 3.x docs would expect to see examples using 3.x versions. Consider changing the example to use a 3.x version like "bash start-doris.sh -v 3.0.8".

Suggested change
bash start-doris.sh -v 2.1.8
bash start-doris.sh -v 3.0.8

Copilot uses AI. Check for mistakes.
```

### 第 3 步：使用 MySQL 客户端连接集群，并检查集群状态
Expand Down Expand Up @@ -238,7 +245,21 @@ mysql -uroot -P9030 -h127.0.0.1 -e 'SELECT `host`, `alive` FROM backends()'
4 rows in set (0.10 sec)
```

## 常见问题

**Q: 如何在 Mac 上安装 Docker？**

A: 下载并安装 [Docker Desktop](https://www.docker.com/products/docker-desktop/)。

**Q: Mac: 安装 Docker Desktop 后仍提示 "Error: Docker environment not detected"**

A: 创建符号链接：

```shell
sudo ln -s /Applications/Docker.app/Contents/Resources/bin/docker /usr/local/bin/docker
```

**Q: Mac: "error getting credentials - err: exit status 1, out: \`\`"**

A: 删除 `~/.docker/config.json` 中的 `credsStore` 字段。
Copy link

Copilot AI Jan 6, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

文档中建议删除 ~/.docker/config.json 中的 credsStore 字段，会关闭 Docker 的系统凭据存储机制，使仓库登录信息以明文形式保存在配置文件中，从而显著降低凭据安全性。能够读取该文件的攻击者或恶意程序（例如通过本地入侵或备份泄露）可以直接获取 Docker 仓库账号，进而未授权访问私有镜像或推送恶意镜像。建议不要无条件删除 credsStore，而是引导用户修复凭据助手配置，或在文档中明确说明安全影响并提供更安全的替代方案。

Copilot uses AI. Check for mistakes.

16 changes: 15 additions & 1 deletion ...zh-CN/docusaurus-plugin-content-docs/version-4.x/gettingStarted/quick-start.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,7 @@ chmod 755 start-doris.sh

### 第 2 步：启动集群

运行脚本，启动集群，默认使用`2.1.9`版本
运行脚本，启动集群，默认使用 `4.0.1` 版本

```shell
bash start-doris.sh
Expand Down Expand Up @@ -245,7 +245,21 @@ mysql -uroot -P9030 -h127.0.0.1 -e 'SELECT `host`, `alive` FROM backends()'
4 rows in set (0.10 sec)
```

## 常见问题

**Q: 如何在 Mac 上安装 Docker？**

A: 下载并安装 [Docker Desktop](https://www.docker.com/products/docker-desktop/)。

**Q: Mac: 安装 Docker Desktop 后仍提示 "Error: Docker environment not detected"**

A: 创建符号链接：

```shell
sudo ln -s /Applications/Docker.app/Contents/Resources/bin/docker /usr/local/bin/docker
```

**Q: Mac: "error getting credentials - err: exit status 1, out: \`\`"**

A: 删除 `~/.docker/config.json` 中的 `credsStore` 字段。

Comment on lines +264 to 265
Copy link

Copilot AI Jan 6, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

文档中建议删除 ~/.docker/config.json 中的 credsStore 字段，会关闭 Docker 的系统凭据存储机制，使仓库登录信息以明文形式保存在配置文件中，从而显著降低凭据安全性。能够读取该文件的攻击者或恶意程序（例如通过本地入侵或备份泄露）可以直接获取 Docker 仓库账号，进而未授权访问私有镜像或推送恶意镜像。建议不要无条件删除 credsStore，而是引导用户修复凭据助手配置，或在文档中明确说明安全影响并提供更安全的替代方案。

Suggested change
A: 删除 `~/.docker/config.json` 中的 `credsStore` 字段。
A: 该错误通常与 Docker 凭据助手（credential helper）配置异常有关，不建议直接删除 `credsStore`。可以按以下步骤排查：
1. 打开 `~/.docker/config.json`，确认其中的 `credsStore` 字段值（例如 `desktop`、`osxkeychain` 等）与本机已安装的凭据助手类型一致，必要时通过重新安装或升级 Docker Desktop 来修复该配置。
2. 参考 Docker 官方文档，检查并重新配置 Docker 凭据存储（Credentials store），确保仓库登录信息通过系统钥匙串或安全存储管理，而不是写入明文密码。
3. **仅在本地临时开发/测试环境、且确认不会在该环境中保存任何生产仓库或敏感镜像凭据时**，可以在了解风险的前提下临时删除 `config.json` 中的 `credsStore` 字段以绕过该问题。这样会导致后续登录的仓库凭据以明文形式保存在该文件中，存在泄露风险，不推荐在生产环境或包含敏感账号的环境中使用。

Copilot uses AI. Check for mistakes.
7 changes: 5 additions & 2 deletions static/files/start-doris.sh
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
#!/bin/bash

# Default version
DORIS_QUICK_START_VERSION="2.1.9"
DORIS_QUICK_START_VERSION="4.0.1"

# Parse parameters
while getopts "v:" opt; do
Expand Down Expand Up @@ -103,7 +103,10 @@ EOF
fi

# Start services
$COMPOSE_CMD -f docker-compose-doris.yaml up -d
if ! $COMPOSE_CMD -f docker-compose-doris.yaml up -d; then
echo "Error: Failed to start Doris cluster"
exit 1
fi

echo "Doris cluster started successfully, version: ${DORIS_QUICK_START_VERSION}"
echo "You can manage the cluster using the following commands:"
Expand Down
24 changes: 22 additions & 2 deletions versioned_docs/version-3.x/gettingStarted/quick-start.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,10 +33,16 @@ chmod 755 start-doris.sh

### Step 2: Start the cluster

Run the script to start the cluster. The default version is `2.1.9`. You can specify the startup version through the -v parameter, such as:
Run the script to start the cluster, using the `4.0.1` version by default

```shell
bash start-doris.sh -v 3.0.4
bash start-doris.sh
```

You can specify the startup version through the -v parameter, such as:

```shell
bash start-doris.sh -v 2.1.8
Copy link

Copilot AI Jan 6, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The example version used here should be a 3.x version (e.g., 3.0.4 as shown in the original) rather than 2.1.8, since this is the version-3.x documentation. Users reading the 3.x docs would expect to see examples using 3.x versions. Consider changing the example to use a 3.x version like "bash start-doris.sh -v 3.0.8".

Copilot uses AI. Check for mistakes.
```

### Step 3: Connect to the cluster using MySQL client and check the cluster status
Expand Down Expand Up @@ -239,8 +245,22 @@ Download the corresponding binary installation package from the Apache Doris web
4 rows in set (0.10 sec)
```

## FAQs

**Q: How do I install Docker on Mac?**

A: Download and install [Docker Desktop](https://www.docker.com/products/docker-desktop/).

**Q: Mac: "Error: Docker environment not detected" after Docker Desktop is installed**

A: Create a symlink:

```shell
sudo ln -s /Applications/Docker.app/Contents/Resources/bin/docker /usr/local/bin/docker
```

**Q: Mac: "error getting credentials - err: exit status 1, out: \`\`"**

A: Remove the `credsStore` field in `~/.docker/config.json`.


Comment on lines +264 to 266
Copy link

Copilot AI Jan 6, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The instruction to remove the credsStore field from ~/.docker/config.json degrades Docker's credential security by disabling the OS-backed credential store and causing registry logins to be stored in plaintext in the config file. An attacker or malware that can read this file (for example via backups, local compromise, or other leaks) can extract Docker registry credentials and gain unauthorized access to private images or push malicious ones. Instead of recommending unconditional removal of credsStore, consider documenting how to fix the credential helper configuration or clearly warn about the security impact and provide a safer workaround.

Suggested change
A: Remove the `credsStore` field in `~/.docker/config.json`.
A: This error usually indicates a problem with Docker's credential helper configuration. First, ensure Docker Desktop is up to date and that its credential helper is correctly installed and referenced in `~/.docker/config.json` (for example via the `credsStore` or `credHelpers` fields). You can reset or reinstall Docker Desktop and consult the [Docker credential store documentation](https://docs.docker.com/engine/reference/commandline/login/#credentials-store) to configure a working helper.
If you choose to temporarily remove the `credsStore` field as a workaround, be aware that Docker will then store registry credentials in plaintext in `~/.docker/config.json`. This degrades security and is not recommended for production or any environment with sensitive credentials; restore a secure credential helper as soon as possible.

Copilot uses AI. Check for mistakes.
16 changes: 15 additions & 1 deletion versioned_docs/version-4.x/gettingStarted/quick-start.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,7 +33,7 @@ chmod 755 start-doris.sh

### Step 2: Start the cluster

Run the script to start the cluster, using the `2.1.9` version by default
Run the script to start the cluster, using the `4.0.1` version by default

```shell
bash start-doris.sh
Expand Down Expand Up @@ -245,8 +245,22 @@ Download the corresponding binary installation package from the Apache Doris web
4 rows in set (0.10 sec)
```

## FAQs

**Q: How do I install Docker on Mac?**

A: Download and install [Docker Desktop](https://www.docker.com/products/docker-desktop/).

**Q: Mac: "Error: Docker environment not detected" after Docker Desktop is installed**

A: Create a symlink:

```shell
sudo ln -s /Applications/Docker.app/Contents/Resources/bin/docker /usr/local/bin/docker
```

**Q: Mac: "error getting credentials - err: exit status 1, out: \`\`"**

A: Remove the `credsStore` field in `~/.docker/config.json`.
Copy link

Copilot AI Jan 6, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The instruction to remove the credsStore field from ~/.docker/config.json degrades Docker's credential security by disabling the OS-backed credential store and causing registry logins to be stored in plaintext in the config file. An attacker or malware that can read this file (for example via backups, local compromise, or other leaks) can extract Docker registry credentials and gain unauthorized access to private images or push malicious ones. Instead of recommending unconditional removal of credsStore, consider documenting how to fix the credential helper configuration or clearly warn about the security impact and provide a safer workaround.

Copilot uses AI. Check for mistakes.