From bf62192727f6924dbb2d63ac401526e4fce937c5 Mon Sep 17 00:00:00 2001 From: CritasWang Date: Mon, 7 Sep 2026 17:00:33 +0800 Subject: [PATCH 1/3] docs: add AI agent installation guide --- src/.vuepress/public/guide.md | 162 ++++++++++++++++++++++++++++++++++ src/Download/README.md | 2 + src/zh/Download/README.md | 2 + 3 files changed, 166 insertions(+) create mode 100644 src/.vuepress/public/guide.md diff --git a/src/.vuepress/public/guide.md b/src/.vuepress/public/guide.md new file mode 100644 index 000000000..59fab229e --- /dev/null +++ b/src/.vuepress/public/guide.md @@ -0,0 +1,162 @@ + + +# Apache IoTDB Installation Guide for AI Agents + +Install the latest stable Apache IoTDB all-in-one binary as a local single-node +instance (one ConfigNode and one DataNode). + +## 1. Prepare + +- Use Linux, macOS, or Windows with WSL2, using Bash. +- Require **JDK 17 or later**. Set `JAVA_HOME` and put `$JAVA_HOME/bin` on `PATH`. +- Require `curl`, `jq`, `unzip`, `awk`, and either `sha512sum` or `shasum`. +- Allow at least 4 GiB RAM and 1 GiB free disk. Use a path without spaces or + non-ASCII characters and the same OS user for every IoTDB command. +- Keep the default single-node ports available: `6667`, `10710`, `10720`, + `10730`, `10740`, `10750`, and `10760`. + +## 2. Download and Verify + +Run the following blocks in one Bash session. The release number is resolved +from Apache's release inventory, excluding release candidates and snapshots. +If discovery fails, select the latest All-in-one release on the official +[download page](https://iotdb.apache.org/Download/) and set `VERSION` manually. + +```bash +set -euo pipefail +for command in java javac curl jq unzip awk grep sed sleep; do + command -v "$command" >/dev/null 2>&1 || { + echo "Missing required command: $command" >&2 + exit 1 + } +done +if ! command -v sha512sum >/dev/null 2>&1 && ! command -v shasum >/dev/null 2>&1; then + echo "Missing required command: sha512sum or shasum" >&2 + exit 1 +fi +java -version +javac -version +JAVA_VERSION=$(java -version 2>&1 | awk -F '"' '/version/ {print $2; exit}') +JAVA_MAJOR=${JAVA_VERSION%%.*} +if [ "$JAVA_MAJOR" = "1" ]; then + JAVA_MAJOR=${JAVA_VERSION#1.} + JAVA_MAJOR=${JAVA_MAJOR%%.*} +fi +case "$JAVA_MAJOR" in + ''|*[!0-9]*) echo "Cannot determine the JDK major version" >&2; exit 1 ;; +esac +if [ "$JAVA_MAJOR" -lt 17 ]; then + echo "JDK 17 or later is required (found $JAVA_VERSION)" >&2 + exit 1 +fi +mkdir -p "$HOME/iotdb" +cd "$HOME/iotdb" +if [ -z "${VERSION:-}" ]; then + VERSION=$(curl -fsSL --retry 3 https://projects.apache.org/json/foundation/releases.json | + jq -er '.iotdb | keys | + map(select(test("^apache-iotdb-[0-9]+\\.[0-9]+\\.[0-9]+$")) | + ltrimstr("apache-iotdb-")) | + max_by(split(".") | map(tonumber)) // error("No stable IoTDB release found")') || { + echo "Could not discover the latest release. Set VERSION manually and rerun this block." >&2 + exit 1 + } +fi +if [[ ! "$VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then + echo "VERSION must be in the form major.minor.patch" >&2 + exit 1 +fi +PACKAGE="apache-iotdb-${VERSION}-all-bin.zip" +curl -fL --retry 3 -o "$PACKAGE" \ + "https://www.apache.org/dyn/closer.lua/iotdb/${VERSION}/${PACKAGE}?action=download" +curl -fsSL --retry 3 -o "$PACKAGE.sha512" \ + "https://downloads.apache.org/iotdb/${VERSION}/${PACKAGE}.sha512" + +EXPECTED=$(awk '{print $1; exit}' "$PACKAGE.sha512") +if command -v sha512sum >/dev/null 2>&1; then + ACTUAL=$(sha512sum "$PACKAGE" | awk '{print $1}') +else + ACTUAL=$(shasum -a 512 "$PACKAGE" | awk '{print $1}') +fi +test "$ACTUAL" = "$EXPECTED" || { echo "SHA-512 mismatch" >&2; exit 1; } +unzip -q -o "$PACKAGE" +cd "apache-iotdb-${VERSION}-all-bin" +export IOTDB_HOME="$PWD" +``` + +## 3. Start + +Set explicit memory budgets for this small local instance. Keep the default +loopback addresses and use the same OS user to start and stop IoTDB. + +```bash +sed 's/^MEMORY_SIZE=.*/MEMORY_SIZE=512M/' conf/confignode-env.sh > conf/confignode-env.sh.tmp +mv conf/confignode-env.sh.tmp conf/confignode-env.sh +sed 's/^MEMORY_SIZE=.*/MEMORY_SIZE=1G/' conf/datanode-env.sh > conf/datanode-env.sh.tmp +mv conf/datanode-env.sh.tmp conf/datanode-env.sh +ulimit -n 65535 || true +bash sbin/start-standalone.sh +``` + +The start script launches both nodes in the background. Poll until one ConfigNode +and one DataNode report `Running`; if startup fails, inspect the two node logs. + +```bash +attempt=1 +while [ "$attempt" -le 60 ]; do + if cluster=$(bash sbin/start-cli.sh -h 127.0.0.1 -p 6667 -u root -pw root \ + -sql_dialect table -e "SHOW CLUSTER" 2>&1) && + grep -q 'ConfigNode.*Running' <<<"$cluster" && + grep -q 'DataNode.*Running' <<<"$cluster"; then + printf '%s\n' "$cluster" + break + fi + if [ "$attempt" -eq 60 ]; then + printf '%s\n' "$cluster" >&2 + echo "IoTDB did not become ready within 120 seconds" >&2 + exit 1 + fi + sleep 2 + attempt=$((attempt + 1)) +done +``` + +## 4. Verify a Write and Query + +```bash +bash sbin/start-cli.sh -h 127.0.0.1 -p 6667 -u root -pw root \ + -sql_dialect table -e "CREATE DATABASE IF NOT EXISTS agent_install_check; + USE agent_install_check; + CREATE TABLE IF NOT EXISTS readings (device_id STRING TAG, value DOUBLE FIELD); + INSERT INTO readings(time, device_id, value) VALUES (1, 'probe', 42.0); + SELECT device_id, value FROM readings;" +``` + +Success requires a returned row containing `probe` and `42.0`, with no SQL errors. +The endpoint is `127.0.0.1:6667`; initial credentials are `root` / `root`. +Change the password before enabling remote access. + +To stop it later, run from the installation directory: + +```bash +bash sbin/stop-standalone.sh +``` + +For production sizing and cluster deployment, see the +[deployment guide](https://iotdb.apache.org/UserGuide/latest/Deployment-and-Maintenance/Cluster-Deployment_apache.html). diff --git a/src/Download/README.md b/src/Download/README.md index ffb7ede87..d806710ae 100644 --- a/src/Download/README.md +++ b/src/Download/README.md @@ -18,6 +18,8 @@ # Release version +Installation guide for AI agents (Markdown): install the latest stable release with JDK 17 or later. + diff --git a/src/zh/Download/README.md b/src/zh/Download/README.md index 678d46818..78d1a9395 100644 --- a/src/zh/Download/README.md +++ b/src/zh/Download/README.md @@ -18,6 +18,8 @@ # 发行版本 +面向 AI Agent 的安装指南（英文 Markdown）：使用 JDK 17 或以上版本，安装最新正式发行版。 +
From 09d0b09f8ce0f620065cd5bd3f3b14dd5d3dd944 Mon Sep 17 00:00:00 2001 From: CritasWang Date: Mon, 7 Sep 2026 17:34:08 +0800 Subject: [PATCH 2/3] docs: move AI agent install entry from Download to QuickStart Remove the guide.md link from the Download pages and add the copy-paste AI assistant prompt to chapter 1 of QuickStart_apache (latest and latest-Table, both English and Chinese). --- src/Download/README.md | 2 -- .../latest-Table/QuickStart/QuickStart_apache.md | 8 ++++++++ src/UserGuide/latest/QuickStart/QuickStart_apache.md | 8 ++++++++ src/zh/Download/README.md | 2 -- .../latest-Table/QuickStart/QuickStart_apache.md | 8 ++++++++ src/zh/UserGuide/latest/QuickStart/QuickStart_apache.md | 8 ++++++++ 6 files changed, 32 insertions(+), 4 deletions(-) diff --git a/src/Download/README.md b/src/Download/README.md index d806710ae..ffb7ede87 100644 --- a/src/Download/README.md +++ b/src/Download/README.md @@ -18,8 +18,6 @@ # Release version -Installation guide for AI agents (Markdown): install the latest stable release with JDK 17 or later. -
diff --git a/src/UserGuide/latest-Table/QuickStart/QuickStart_apache.md b/src/UserGuide/latest-Table/QuickStart/QuickStart_apache.md index d3cdf9a83..c8847b158 100644 --- a/src/UserGuide/latest-Table/QuickStart/QuickStart_apache.md +++ b/src/UserGuide/latest-Table/QuickStart/QuickStart_apache.md @@ -27,6 +27,14 @@ This document will guide you through methods to get started quickly with IoTDB. This guide will assist you in quickly installing and deploying IoTDB. You can quickly navigate to the content you need to review through the following document links: +Copy the prompt below to your AI assistant (Claude Code, Codex, DSH, Qoder, etc.), and it will automatically complete the installation for you. + +Prompt: + +```text +Help me install Apache IoTDB: https://iotdb.apache.org/guide.md +``` + 1. Prepare the necessary machine resources: The deployment and operation of IoTDB require consideration of various aspects of machine resource configuration. For specific resource configurations, please refer to [Database Resource](../Deployment-and-Maintenance/Database-Resources_apache.md) 2. Complete system configuration preparations: IoTDB's system configuration involves multiple aspects. For an introduction to key system configurations, please see [System Requirements](../Deployment-and-Maintenance/Environment-Requirements.md) diff --git a/src/UserGuide/latest/QuickStart/QuickStart_apache.md b/src/UserGuide/latest/QuickStart/QuickStart_apache.md index f70bc7b1b..b4860c74b 100644 --- a/src/UserGuide/latest/QuickStart/QuickStart_apache.md +++ b/src/UserGuide/latest/QuickStart/QuickStart_apache.md @@ -28,6 +28,14 @@ This document will guide you through methods to get started quickly with IoTDB. This guide will assist you in quickly installing and deploying IoTDB. You can quickly navigate to the content you need to review through the following document links: +Copy the prompt below to your AI assistant (Claude Code, Codex, DSH, Qoder, etc.), and it will automatically complete the installation for you. + +Prompt: + +```text +Help me install Apache IoTDB: https://iotdb.apache.org/guide.md +``` + 1. Prepare the necessary machine resources: The deployment and operation of IoTDB require consideration of various aspects of machine resource configuration. For specific resource configurations, please refer to [Database Resource](../Deployment-and-Maintenance/Database-Resources.md) 2. Complete system configuration preparations: IoTDB's system configuration involves multiple aspects. For an introduction to key system configurations, please see [System Requirements](../Deployment-and-Maintenance/Environment-Requirements.md) diff --git a/src/zh/Download/README.md b/src/zh/Download/README.md index 78d1a9395..678d46818 100644 --- a/src/zh/Download/README.md +++ b/src/zh/Download/README.md @@ -18,8 +18,6 @@ # 发行版本 -面向 AI Agent 的安装指南（英文 Markdown）：使用 JDK 17 或以上版本，安装最新正式发行版。 -
diff --git a/src/zh/UserGuide/latest-Table/QuickStart/QuickStart_apache.md b/src/zh/UserGuide/latest-Table/QuickStart/QuickStart_apache.md index 622df52a5..abcc9908b 100644 --- a/src/zh/UserGuide/latest-Table/QuickStart/QuickStart_apache.md +++ b/src/zh/UserGuide/latest-Table/QuickStart/QuickStart_apache.md @@ -27,6 +27,14 @@ 本篇文档将帮助您快速安装部署 IoTDB，您可以通过以下文档的链接快速定位到所需要查看的内容： +将下方提示词复制给你的 AI 助手（Claude Code、Codex、DSH、Qoder 等），它会自动完成安装。 + +提示词： + +```text +帮我安装 Apache IoTDB: https://iotdb.apache.org/guide.md +``` + 1. 准备所需机器资源：IoTDB 的部署和运行需要考虑多个方面的机器资源配置。具体资源配置可查看 [资源规划](../Deployment-and-Maintenance/Database-Resources_apache.md) 2. 完成系统配置准备：IoTDB 的系统配置涉及多个方面，关键的系统配置介绍可查看 [系统配置](../Deployment-and-Maintenance/Environment-Requirements.md) diff --git a/src/zh/UserGuide/latest/QuickStart/QuickStart_apache.md b/src/zh/UserGuide/latest/QuickStart/QuickStart_apache.md index 8b2e3cdb1..0761224bd 100644 --- a/src/zh/UserGuide/latest/QuickStart/QuickStart_apache.md +++ b/src/zh/UserGuide/latest/QuickStart/QuickStart_apache.md @@ -27,6 +27,14 @@ 本篇文档将帮助您快速安装部署 IoTDB，您可以通过以下文档的链接快速定位到所需要查看的内容： +将下方提示词复制给你的 AI 助手（Claude Code、Codex、DSH、Qoder 等），它会自动完成安装。 + +提示词： + +```text +帮我安装 Apache IoTDB: https://iotdb.apache.org/guide.md +``` + 1. 准备所需机器资源：IoTDB 的部署和运行需要考虑多个方面的机器资源配置。具体资源配置可查看 [资源规划](../Deployment-and-Maintenance/Database-Resources_apache.md) 2. 完成系统配置准备：IoTDB 的系统配置涉及多个方面，关键的系统配置介绍可查看 [系统配置](../Deployment-and-Maintenance/Environment-Requirements.md) From 88ce430e8102da80fac690de61b64fa5344628d4 Mon Sep 17 00:00:00 2001 From: CritasWang Date: Mon, 7 Sep 2026 17:34:11 +0800 Subject: [PATCH 3/3] ci: pin pnpm/action-setup to v6.0.10 commit SHA The organization action allowlist requires the exact commit SHA instead of a version tag. --- .github/workflows/site-build.yaml | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/.github/workflows/site-build.yaml b/.github/workflows/site-build.yaml index 46bc66b3b..0b45fbd3f 100644 --- a/.github/workflows/site-build.yaml +++ b/.github/workflows/site-build.yaml @@ -23,7 +23,7 @@ jobs: - uses: actions/checkout@v4 - name: Install pnpm - uses: pnpm/action-setup@v4 + uses: pnpm/action-setup@0977fd99725f1db4007ccb2928dbb4e90d06cc86 # v6.0.10 - name: Use Node.js 22 uses: actions/setup-node@v4 @@ -59,7 +59,7 @@ jobs: - uses: actions/checkout@v4 - name: Install pnpm - uses: pnpm/action-setup@v4 + uses: pnpm/action-setup@0977fd99725f1db4007ccb2928dbb4e90d06cc86 # v6.0.10 - name: Use Node.js 22 uses: actions/setup-node@v4 @@ -84,7 +84,7 @@ jobs: fetch-depth: 0 - name: Install pnpm - uses: pnpm/action-setup@v4 + uses: pnpm/action-setup@0977fd99725f1db4007ccb2928dbb4e90d06cc86 # v6.0.10 - name: Use Node.js 22 uses: actions/setup-node@v4