Observability AWS

openGemini Time Series Database on AWS User Guide

| Product: openGemini on AWS

Overview

This image runs openGemini, the high performance open source distributed time series database purpose built for metrics, observability and Internet of Things telemetry. openGemini speaks the InfluxDB HTTP API: you write points in the Influx line protocol and query them back in InfluxQL, so existing metric writers, Telegraf outputs and Grafana InfluxQL data sources connect with minimal change. It is licensed under Apache 2.0, so there is no vendor lock in or licence ambiguity for commercial and SaaS deployments.

The openGemini single node server (ts-server) is installed under /usr/local/bin and runs as a dedicated unprivileged opengemini system account under a systemd service that starts it on boot and restarts it on failure. The time series store lives at /var/lib/opengemini, which is a dedicated, independently resizable EBS data volume, so the database is kept off the operating system disk.

openGemini ships with HTTP authentication disabled by default. This image turns it on: the config sets auth-enabled = true, and a unique admin password is generated on the first boot of every deployed instance, so two instances launched from the same Amazon Machine Image never share a password. The password is written to /root/opengemini-credentials.txt with mode 0600 so that only the root user can read it. The HTTP query and write API binds on port 8086, while the internal meta, store and RPC ports bind to the loopback interface only. The recommended security group opens SSH alone, so the database is not reachable from the internet until you deliberately add a scoped ingress rule or connect over an SSH tunnel.

Prerequisites

Before you deploy this image you need:

  • An Amazon Web Services account where you can launch EC2 instances
  • IAM permissions to launch instances, create security groups, and subscribe to AWS Marketplace products
  • An EC2 key pair in the target Region for SSH access to the instance
  • A VPC and subnet in the target Region, with a security group allowing inbound port 22 from your management network
  • The AWS CLI (version 2) installed locally if you plan to deploy from the command line

Step 1: Launch the Instance from the AWS Marketplace

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 openGemini. Select the cloudimg listing and choose Select, then Continue on the subscription summary.

Pick an instance type of m5.large or larger. Choose your EC2 key pair under Key pair (login). Under Network settings select your VPC and subnet, and either create or select a security group that opens port 22 from your management network. Leave the root volume at the default size or larger; the time series store is on a separate data volume.

Select Launch instance. First boot initialisation takes a few seconds after the instance state becomes Running and the status checks pass.

Step 2: Launch the Instance from the AWS CLI

The following block launches an instance from the cloudimg openGemini 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 as described above.

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

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.

Step 3: Connect to Your Instance

Connect over SSH using your key pair and the login user for your operating system variant.

OS variant SSH login user
Ubuntu 24.04 ubuntu 
ssh -i <key-name>.pem ubuntu@<public-ip>

Step 4: Retrieve the Admin Password

The openGemini admin password is unique to your instance and was generated on first boot. Read it as root:

sudo cat /root/opengemini-credentials.txt

The file lists the HTTP endpoint, the admin user (admin), the generated password and the default database (cloudimg). Keep this password somewhere safe.

Step 5: Confirm openGemini Is Running

Over SSH, confirm the service is active and that the HTTP API port is listening while the internal ports stay on loopback:

systemctl is-active opengemini
ss -tlnp | grep -E ':(8086|8088|8091|8092) '

You should see the service reported as active, the HTTP query and write API listening on 0.0.0.0:8086, and the meta and RPC ports (8088, 8091, 8092) bound to 127.0.0.1 only.

Step 6: Verify Authentication Is Enforced

openGemini answers the /ping liveness probe without credentials, but every query and write requires HTTP Basic authentication. Confirm that an unauthenticated query is rejected:

curl -s -o /dev/null -w 'unauthenticated query returned HTTP %{http_code}\n' \
  -G 'http://127.0.0.1:8086/query' --data-urlencode 'q=SHOW DATABASES'

A correctly hardened instance returns HTTP 401. A wrong password is refused the same way.

Step 7: Query openGemini with InfluxQL

Read the generated password into a shell variable and list the databases. The default cloudimg database is created on first boot.

PW=$(sudo grep '^OPENGEMINI_PASSWORD=' /root/opengemini-credentials.txt | cut -d= -f2-)
curl -s -u "admin:$PW" -G 'http://127.0.0.1:8086/query' \
  --data-urlencode 'q=SHOW DATABASES'

The response is JSON listing the databases, including cloudimg.

Step 8: Write and Read Points over the Line Protocol

Write a point in the InfluxDB line protocol to the cloudimg database, then read it back with an InfluxQL SELECT. This proves the full ingest and query round trip.

PW=$(sudo grep '^OPENGEMINI_PASSWORD=' /root/opengemini-credentials.txt | cut -d= -f2-)
TS=$(date +%s000000000)
curl -s -o /dev/null -w 'write returned HTTP %{http_code}\n' \
  -u "admin:$PW" -XPOST 'http://127.0.0.1:8086/write?db=cloudimg' \
  --data-binary "cpu,host=example value=0.64 ${TS}"
curl -s -u "admin:$PW" -G 'http://127.0.0.1:8086/query' \
  --data-urlencode 'db=cloudimg' \
  --data-urlencode 'q=SELECT * FROM cpu'

The write returns HTTP 204 and the query returns the cpu measurement with the value you wrote, confirming that ingest and query work end to end.

Step 9: Remote Access

The recommended security group opens SSH only, so the database is not exposed to the internet by default. To reach the HTTP API from your workstation, open an SSH tunnel and point your client at the tunnelled port:

ssh -L 8086:127.0.0.1:8086 ubuntu@<public-ip>

With the tunnel open, http://127.0.0.1:8086 on your workstation reaches openGemini on the instance, using the admin credentials. Alternatively, if you need direct network access, add a security group ingress rule for TCP 8086 scoped tightly to the source networks that write and query metrics, and keep authentication enforced. Do not open 8086 to the whole internet without TLS termination in front.

Step 10: Connect Grafana

Add openGemini to Grafana as an InfluxDB data source using the InfluxQL query language. Set the URL to the instance endpoint (over the tunnel, http://127.0.0.1:8086, or your scoped address), set the database to cloudimg, enable basic authentication, and enter user admin with the generated password. openGemini answers the InfluxDB HTTP query API, so existing InfluxQL dashboards and Telegraf InfluxDB outputs work against it.

Step 11: The Data Volume

The time series store lives on a dedicated EBS volume mounted at /var/lib/opengemini. This keeps the database off the operating system disk and lets you resize or snapshot it independently. Confirm the mount:

df -h /var/lib/opengemini

To grow the store, expand the EBS volume in the AWS console, then grow the filesystem on the instance with sudo resize2fs on the underlying device. The data, meta and wal subdirectories all live on this volume.

Step 12: Backup and Maintenance

Back up the database by snapshotting the /var/lib/opengemini EBS volume, which captures the entire time series store. Apply operating system security updates with sudo apt-get update && sudo apt-get upgrade and reboot when a new kernel is installed; openGemini starts automatically on boot. To change server settings, edit /etc/opengemini/openGemini.conf and run sudo systemctl restart opengemini.

Support

This image is published and supported by cloudimg. Support covers deployment, ingestion and retention tuning, InfluxDB line protocol and Grafana integration, credential management, TLS and storage. Contact cloudimg through the support channel listed on the AWS Marketplace listing.

All product and company names are trademarks or registered trademarks of their respective holders. Use of them does not imply any affiliation with or endorsement by them.