|
| 1 | +<!-- |
| 2 | +Licensed to the Apache Software Foundation (ASF) under one |
| 3 | +or more contributor license agreements. See the NOTICE file |
| 4 | +distributed with this work for additional information |
| 5 | +regarding copyright ownership. The ASF licenses this file |
| 6 | +to you under the Apache License, Version 2.0 (the |
| 7 | +"License"); you may not use this file except in compliance |
| 8 | +with the License. You may obtain a copy of the License at |
| 9 | +
|
| 10 | + https://www.apache.org/licenses/LICENSE-2.0 |
| 11 | +
|
| 12 | +Unless required by applicable law or agreed to in writing, |
| 13 | +software distributed under the License is distributed on an |
| 14 | +"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| 15 | +KIND, either express or implied. See the License for the |
| 16 | +specific language governing permissions and limitations |
| 17 | +under the License. |
| 18 | +--> |
| 19 | + |
| 20 | +# Apache IoTDB Installation Guide for AI Agents |
| 21 | + |
| 22 | +Install the latest stable Apache IoTDB all-in-one binary as a local single-node |
| 23 | +instance (one ConfigNode and one DataNode). |
| 24 | + |
| 25 | +## 1. Prepare |
| 26 | + |
| 27 | +- Use Linux, macOS, or Windows with WSL2, using Bash. |
| 28 | +- Require **JDK 17 or later**. Set `JAVA_HOME` and put `$JAVA_HOME/bin` on `PATH`. |
| 29 | +- Require `curl`, `jq`, `unzip`, `awk`, and either `sha512sum` or `shasum`. |
| 30 | +- Allow at least 4 GiB RAM and 1 GiB free disk. Use a path without spaces or |
| 31 | + non-ASCII characters and the same OS user for every IoTDB command. |
| 32 | +- Keep the default single-node ports available: `6667`, `10710`, `10720`, |
| 33 | + `10730`, `10740`, `10750`, and `10760`. |
| 34 | + |
| 35 | +## 2. Download and Verify |
| 36 | + |
| 37 | +Run the following blocks in one Bash session. The release number is resolved |
| 38 | +from Apache's release inventory, excluding release candidates and snapshots. |
| 39 | +If discovery fails, select the latest All-in-one release on the official |
| 40 | +[download page](https://iotdb.apache.org/Download/) and set `VERSION` manually. |
| 41 | + |
| 42 | +```bash |
| 43 | +set -euo pipefail |
| 44 | +for command in java javac curl jq unzip awk grep sed sleep; do |
| 45 | + command -v "$command" >/dev/null 2>&1 || { |
| 46 | + echo "Missing required command: $command" >&2 |
| 47 | + exit 1 |
| 48 | + } |
| 49 | +done |
| 50 | +if ! command -v sha512sum >/dev/null 2>&1 && ! command -v shasum >/dev/null 2>&1; then |
| 51 | + echo "Missing required command: sha512sum or shasum" >&2 |
| 52 | + exit 1 |
| 53 | +fi |
| 54 | +java -version |
| 55 | +javac -version |
| 56 | +JAVA_VERSION=$(java -version 2>&1 | awk -F '"' '/version/ {print $2; exit}') |
| 57 | +JAVA_MAJOR=${JAVA_VERSION%%.*} |
| 58 | +if [ "$JAVA_MAJOR" = "1" ]; then |
| 59 | + JAVA_MAJOR=${JAVA_VERSION#1.} |
| 60 | + JAVA_MAJOR=${JAVA_MAJOR%%.*} |
| 61 | +fi |
| 62 | +case "$JAVA_MAJOR" in |
| 63 | + ''|*[!0-9]*) echo "Cannot determine the JDK major version" >&2; exit 1 ;; |
| 64 | +esac |
| 65 | +if [ "$JAVA_MAJOR" -lt 17 ]; then |
| 66 | + echo "JDK 17 or later is required (found $JAVA_VERSION)" >&2 |
| 67 | + exit 1 |
| 68 | +fi |
| 69 | +mkdir -p "$HOME/iotdb" |
| 70 | +cd "$HOME/iotdb" |
| 71 | +if [ -z "${VERSION:-}" ]; then |
| 72 | + VERSION=$(curl -fsSL --retry 3 https://projects.apache.org/json/foundation/releases.json | |
| 73 | + jq -er '.iotdb | keys | |
| 74 | + map(select(test("^apache-iotdb-[0-9]+\\.[0-9]+\\.[0-9]+$")) | |
| 75 | + ltrimstr("apache-iotdb-")) | |
| 76 | + max_by(split(".") | map(tonumber)) // error("No stable IoTDB release found")') || { |
| 77 | + echo "Could not discover the latest release. Set VERSION manually and rerun this block." >&2 |
| 78 | + exit 1 |
| 79 | + } |
| 80 | +fi |
| 81 | +if [[ ! "$VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then |
| 82 | + echo "VERSION must be in the form major.minor.patch" >&2 |
| 83 | + exit 1 |
| 84 | +fi |
| 85 | +PACKAGE="apache-iotdb-${VERSION}-all-bin.zip" |
| 86 | +curl -fL --retry 3 -o "$PACKAGE" \ |
| 87 | + "https://www.apache.org/dyn/closer.lua/iotdb/${VERSION}/${PACKAGE}?action=download" |
| 88 | +curl -fsSL --retry 3 -o "$PACKAGE.sha512" \ |
| 89 | + "https://downloads.apache.org/iotdb/${VERSION}/${PACKAGE}.sha512" |
| 90 | + |
| 91 | +EXPECTED=$(awk '{print $1; exit}' "$PACKAGE.sha512") |
| 92 | +if command -v sha512sum >/dev/null 2>&1; then |
| 93 | + ACTUAL=$(sha512sum "$PACKAGE" | awk '{print $1}') |
| 94 | +else |
| 95 | + ACTUAL=$(shasum -a 512 "$PACKAGE" | awk '{print $1}') |
| 96 | +fi |
| 97 | +test "$ACTUAL" = "$EXPECTED" || { echo "SHA-512 mismatch" >&2; exit 1; } |
| 98 | +unzip -q -o "$PACKAGE" |
| 99 | +cd "apache-iotdb-${VERSION}-all-bin" |
| 100 | +export IOTDB_HOME="$PWD" |
| 101 | +``` |
| 102 | + |
| 103 | +## 3. Start |
| 104 | + |
| 105 | +Set explicit memory budgets for this small local instance. Keep the default |
| 106 | +loopback addresses and use the same OS user to start and stop IoTDB. |
| 107 | + |
| 108 | +```bash |
| 109 | +sed 's/^MEMORY_SIZE=.*/MEMORY_SIZE=512M/' conf/confignode-env.sh > conf/confignode-env.sh.tmp |
| 110 | +mv conf/confignode-env.sh.tmp conf/confignode-env.sh |
| 111 | +sed 's/^MEMORY_SIZE=.*/MEMORY_SIZE=1G/' conf/datanode-env.sh > conf/datanode-env.sh.tmp |
| 112 | +mv conf/datanode-env.sh.tmp conf/datanode-env.sh |
| 113 | +ulimit -n 65535 || true |
| 114 | +bash sbin/start-standalone.sh |
| 115 | +``` |
| 116 | + |
| 117 | +The start script launches both nodes in the background. Poll until one ConfigNode |
| 118 | +and one DataNode report `Running`; if startup fails, inspect the two node logs. |
| 119 | + |
| 120 | +```bash |
| 121 | +attempt=1 |
| 122 | +while [ "$attempt" -le 60 ]; do |
| 123 | + if cluster=$(bash sbin/start-cli.sh -h 127.0.0.1 -p 6667 -u root -pw root \ |
| 124 | + -sql_dialect table -e "SHOW CLUSTER" 2>&1) && |
| 125 | + grep -q 'ConfigNode.*Running' <<<"$cluster" && |
| 126 | + grep -q 'DataNode.*Running' <<<"$cluster"; then |
| 127 | + printf '%s\n' "$cluster" |
| 128 | + break |
| 129 | + fi |
| 130 | + if [ "$attempt" -eq 60 ]; then |
| 131 | + printf '%s\n' "$cluster" >&2 |
| 132 | + echo "IoTDB did not become ready within 120 seconds" >&2 |
| 133 | + exit 1 |
| 134 | + fi |
| 135 | + sleep 2 |
| 136 | + attempt=$((attempt + 1)) |
| 137 | +done |
| 138 | +``` |
| 139 | + |
| 140 | +## 4. Verify a Write and Query |
| 141 | + |
| 142 | +```bash |
| 143 | +bash sbin/start-cli.sh -h 127.0.0.1 -p 6667 -u root -pw root \ |
| 144 | + -sql_dialect table -e "CREATE DATABASE IF NOT EXISTS agent_install_check; |
| 145 | + USE agent_install_check; |
| 146 | + CREATE TABLE IF NOT EXISTS readings (device_id STRING TAG, value DOUBLE FIELD); |
| 147 | + INSERT INTO readings(time, device_id, value) VALUES (1, 'probe', 42.0); |
| 148 | + SELECT device_id, value FROM readings;" |
| 149 | +``` |
| 150 | + |
| 151 | +Success requires a returned row containing `probe` and `42.0`, with no SQL errors. |
| 152 | +The endpoint is `127.0.0.1:6667`; initial credentials are `root` / `root`. |
| 153 | +Change the password before enabling remote access. |
| 154 | + |
| 155 | +To stop it later, run from the installation directory: |
| 156 | + |
| 157 | +```bash |
| 158 | +bash sbin/stop-standalone.sh |
| 159 | +``` |
| 160 | + |
| 161 | +For production sizing and cluster deployment, see the |
| 162 | +[deployment guide](https://iotdb.apache.org/UserGuide/latest/Deployment-and-Maintenance/Cluster-Deployment_apache.html). |
0 commit comments