Apache IoTDB

Sign in to the AWS Management Console, open the EC2 service, and select Launch instance. Under Application and OS Images, choose AWS Marketplace AMIs and search for Apache IoTDB. Select the SecureAnyCloud listing and choose Select, then choose Continue on the subscription summary.

Pick an instance type of t3.medium or larger. The single-node deployment runs two JVMs (the ConfigNode and the DataNode), so 4 GiB of memory is the practical minimum. Choose your EC2 key pair under Key pair (login).

Under Network settings, select your VPC and subnet. Create or select a security group that opens port 22 from your management network. Leave the root volume at the default size or larger.

Select Launch instance. First-boot initialisation runs once after the instance state becomes Running and the status checks pass. It waits for the database to come up, generates the per-instance root password and rotates the default, then writes the credentials file. The JVM start plus this rotation takes a minute or two on first boot.

Run the following command to launch an instance from the SecureAnyCloud Apache IoTDB Marketplace AMI into an existing subnet and security group. Replace <ami-id> with the AMI ID shown on the Marketplace listing, <key-name> with your EC2 key pair name, <subnet-id> with your subnet ID, and <security-group-id> with a security group that opens port 22 from your management network.

aws ec2 run-instances \
  --image-id <ami-id> \
  --instance-type t3.medium \
  --key-name <key-name> \
  --subnet-id <subnet-id> \
  --security-group-ids <security-group-id> \
  --tag-specifications 'ResourceType=instance,Tags=[{Key=Name,Value=apache-iotdb}]'

When the instance reaches the Running state and its status checks pass, note its public IP address or DNS name from the EC2 console or with aws ec2 describe-instances.

Connect over SSH using your key pair and the login user for your operating system variant. For Ubuntu 24.04, the login user is ubuntu.

ssh -i <key-name>.pem ubuntu@<public-ip>

A welcome banner prints the most useful commands. Retrieve the per-instance root password that first boot generated:

sudo cat /root/apache-iotdb-credentials.txt

That file contains the iotdb.root.password value for this instance and ready-to-paste examples for the SQL CLI and the REST API. The commands in the following steps read the password straight from this file, so you can run them as written.

Apache IoTDB runs as a system service that is enabled and started on boot. Confirm the service is active:

systemctl is-active iotdb

That prints active. For the full unit status, including the main process and the two JVMs (ConfigNode and DataNode), use:

systemctl status iotdb --no-pager

The database binds the client RPC port and the REST port; confirm they are listening on the instance:

ss -tlnp | grep -E '6667|18080'

Confirm the bundled JRE that runs the database:

/usr/lib/jvm/temurin-17-jre-amd64/bin/java -version

IoTDB ships a SQL command-line client under /opt/iotdb/sbin/start-cli.sh. It connects to the DataNode RPC on 127.0.0.1:6667 as user root.

The following commands read the per-instance password from the credentials file, create a couple of timeseries, write data points and query them back. First, create the schema:

PASS=$(sudo grep '^iotdb.root.password=' /root/apache-iotdb-credentials.txt | cut -d= -f2-) sudo -u iotdb /opt/iotdb/sbin/start-cli.sh -h 127.0.0.1 -p 6667 -u root -pw "$PASS" \
  -e "CREATE TIMESERIES root.factory.line1.temperature WITH DATATYPE=FLOAT,ENCODING=GORILLA;"

Insert a couple of readings, then query them back ordered by time:

PASS=$(sudo grep '^iotdb.root.password=' /root/apache-iotdb-credentials.txt | cut -d= -f2-) sudo -u iotdb /opt/iotdb/sbin/start-cli.sh -h 127.0.0.1 -p 6667 -u root -pw "$PASS" \
  -e "INSERT INTO root.factory.line1(time,temperature) VALUES(now(),73.4);"
sudo -u iotdb /opt/iotdb/sbin/start-cli.sh -h 127.0.0.1 -p 6667 -u root -pw "$PASS" \
  -e "SELECT temperature FROM root.factory.line1 ORDER BY time DESC LIMIT 5;"

To explore the database interactively, run sudo -u iotdb /opt/iotdb/sbin/start-cli.sh -h 127.0.0.1 -p 6667 -u root -pw '<password>'. Then type SQL statements such as SHOW DATABASES;, SHOW TIMESERIES;, SHOW DEVICES; and aggregation queries like SELECT count(temperature) FROM root.factory.line1;. Type quit; to exit.

IoTDB also exposes a REST API V2 on port 18080, enabled on this image. The /ping endpoint is an unauthenticated liveness probe that returns HTTP 200 with a success body while the service is up:

curl -s http://127.0.0.1:18080/ping

Data endpoints require HTTP Basic authentication with user root and the per-instance password. The following command reads the password, builds the Basic auth header and runs a query through POST /rest/v2/query:

PASS=$(sudo grep '^iotdb.root.password=' /root/apache-iotdb-credentials.txt | cut -d= -f2-)
curl -s -X POST http://127.0.0.1:18080/rest/v2/query \
  -H "Authorization: Basic $(printf 'root:%s' "$PASS" | base64 -w0)" \
  -H 'Content-Type: application/json' \
  -d '{"sql":"select temperature from root.factory.line1 order by time desc limit 5"}'

The response is a JSON document with the expression names, data types, timestamps and values. To ingest data over REST, post to POST /rest/v2/insertTablet with the same Basic auth header.

The REST port binds on the instance but is not reachable from the network, because the security group opens port 22 only. To expose it, open the port in the instance security group yourself and front it with your own TLS termination.

The entire time-series database lives on a dedicated EBS volume mounted at /var/lib/iotdb. Every ConfigNode and DataNode data, write-ahead-log, consensus and system directory sits here, off the operating system disk, so you can resize or snapshot the database independently. Confirm the mount with:

df -h /var/lib/iotdb

IoTDB stores sensor data in its purpose-built columnar TsFile format with high compression, so long-retention time series stay compact on disk.

To grow the volume, expand the EBS volume in the AWS console, then grow the filesystem on the instance with sudo resize2fs on the underlying device. Snapshot the volume for point-in-time backups of the database.

Point your applications at the instance to write and read time series at scale. The native session SDKs (Java, Python, C++, Go and others) connect to the DataNode RPC on port 6667 and are the highest-throughput path for ingestion. The REST API on 18080 suits lightweight HTTP clients.

Both authenticate as root with the per-instance password. You can create additional users and grant fine-grained privileges with CREATE USER and GRANT from the SQL CLI.

The RPC and REST ports bind to loopback and the instance respectively, and the security group opens only port 22, so decide your own exposure. Open the relevant port in the security group for trusted clients, or keep access on the instance and tunnel over SSH.