Apache HertzBeat on AWS User Guide

Overview

This image runs Apache HertzBeat, the open source real-time monitoring and alerting system from the Apache Software Foundation. HertzBeat provides agentless monitoring of servers, operating systems, databases, message and application middleware, web sites, APIs, TLS certificates, cloud-native workloads and fully custom endpoints, together with a flexible threshold and alarm engine and more than thirty notification channels including email, Slack, Discord, Telegram and webhooks.

The image is self-contained and runs as a single node. HertzBeat uses embedded storage for both its metadata (an embedded H2 database) and its metric history (embedded DuckDB), so there is no external database to provision. The application runs as a dedicated unprivileged hertzbeat system user on OpenJDK 17, managed by systemd for automatic restart and clean logging. The web console and REST API are served on port 1157. The embedded data tier lives on a dedicated EBS data volume mounted at /opt/hertzbeat/data, independently resizable and separate from the operating system disk.

The image is secure by default. On the first boot of every deployed instance a one-shot service generates a unique administrator password AND a unique JWT signing secret for that instance, replacing the well-known upstream defaults, and writes the admin password to /root/hertzbeat-credentials.txt with mode 0600. No shared or default credentials ship in the image.

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 and inbound port 1157 from the networks your operators will reach the HertzBeat console on
• 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 Apache HertzBeat. 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 allows inbound port 22 from your management network and inbound port 1157 from the networks your operators use. Leave the root volume at the default size or larger; the image adds a separate data volume for the embedded metadata and metric-history store automatically.

Select Launch instance. First boot initialisation takes under a minute 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 Apache HertzBeat 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 ports 22 and 1157 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> \
  --metadata-options "HttpTokens=required,HttpEndpoint=enabled" \
  --tag-specifications 'ResourceType=instance,Tags=[{Key=Name,Value=hertzbeat}]'

The image reads the instance public IP through EC2 IMDSv2 (a session token is fetched from the instance metadata service before the metadata is read), so the console URL written to the credentials file matches the address you reach the instance on.

Connecting to your instance

Connect over SSH as the default login user for your operating system variant, using the private key for the EC2 key pair you launched with. The SSH login user depends on the operating system of the AMI variant you launched:

The first boot service runs before the SSH daemon becomes ready, so the credentials file is always in place when you log in for the first time. Connect and read the per-instance administrator login in one session:

ssh <login-user>@<public-ip>
sudo cat /root/hertzbeat-credentials.txt

Step 3: Retrieve the Administrator Login

The administrator password is generated uniquely for your instance on first boot and written to a root-only file (/root/hertzbeat-credentials.txt). The file looks like this (the password shown here is an example - yours will differ):

# Apache HertzBeat - Per-Instance Credentials
# Generated: ...
#
# The console admin password below was randomly generated for THIS instance on
# first boot. The upstream default (admin/hertzbeat) and the upstream JWT signing
# key have BOTH been replaced with per-instance values - no shared secret ships.
#
HERTZBEAT_URL=http://<instance-public-ip>:1157/
HERTZBEAT_ADMIN_USER=admin
HERTZBEAT_ADMIN_PASSWORD=<admin-password>

You can confirm the service is running and listening on port 1157:

systemctl is-active hertzbeat.service

active

sudo ss -tlnp | grep 1157

LISTEN 0  100  *:1157  *:*  users:(("java",pid=11583,fd=446))

Step 4: First Sign-in

Open http://<instance-public-ip>:1157/ in your browser. You are presented with the HertzBeat sign-in page.

Sign in with the username admin and the password from /root/hertzbeat-credentials.txt. HertzBeat may show a reminder to change the initial password; because your instance already has a unique per-instance password, this is only a prompt - you can update it at any time under the account menu.

Step 5: Add Your First Monitor

From the left navigation choose Monitors, then New Monitor and pick a monitor type - for example a Website monitor to check an HTTP/HTTPS endpoint, or a Ping monitor to check host reachability. Enter the target host, a task name and the port, then choose OK. HertzBeat begins collecting on the schedule you set (60 seconds by default).

The Monitors list shows each monitor with its live status. A healthy target reports Up:

Click a monitor to open its real-time detail, which shows the collected metrics for the current cycle - for a website monitor, the response time and status:

Select the Monitor Historical Chart Detail tab on the same page to see the metric history charts, which are backed by the embedded DuckDB store on the data volume.

Step 6: Configure Thresholds and Alerts

Under Alerting you can define threshold rules and route alarms to notification channels:

• Threshold - create a rule against a monitored metric (for example, response time greater than a limit, or a target reporting Down), with a severity.
• Notification - configure the delivery channels (email, Slack, Discord, Telegram, webhook and more) and the recipients.
• Alarms - review triggered and resolved alarms.

When a rule fires, HertzBeat raises an alarm and delivers it through the configured channels.

Step 7: Embedded Storage and the Data Volume

HertzBeat on this image is a single self-contained node. Its metadata (monitor definitions, users, alarm rules) is held in an embedded H2 database, and its metric history is held in an embedded DuckDB store. Both live under /opt/hertzbeat/data, which is a dedicated EBS data volume:

findmnt -rno SOURCE,TARGET,FSTYPE /opt/hertzbeat/data

/dev/nvme1n1 /opt/hertzbeat/data ext4

Because the data tier is on its own volume, you can resize or snapshot it independently of the operating system disk. To grow it, modify the EBS volume in the EC2 console and then extend the filesystem with resize2fs on the device.

Step 8: Service Management

HertzBeat runs under systemd. Common operations:

sudo systemctl status hertzbeat            # health and recent log lines
sudo systemctl restart hertzbeat           # restart the service
sudo journalctl -u hertzbeat -n 50 --no-pager  # recent application log

The service is configured to restart automatically on failure and to start on boot.

Step 9: Put HertzBeat Behind HTTPS (optional)

The console is served over plain HTTP on port 1157. For production, front it with a reverse proxy that terminates TLS - for example nginx or a cloud load balancer - and restrict the security group so that only the proxy reaches port 1157. Point the proxy at 127.0.0.1:1157 and obtain a certificate for your domain (for example with certbot against your-domain). Then expose only 443 to your operators.

Step 10: Backups and Maintenance

Because all HertzBeat state lives under /opt/hertzbeat/data, back it up by snapshotting the EBS data volume, or by stopping the service and archiving the directory:

sudo systemctl stop hertzbeat
sudo tar czf /var/tmp/hertzbeat-data-backup.tgz -C /opt/hertzbeat data
sudo systemctl start hertzbeat

Keep the operating system patched with sudo apt-get update && sudo apt-get upgrade. The image ships fully patched at build time and runs unattended security upgrades.

Support

This image is published by cloudimg with 24/7 technical support by email and chat. We can help with deployment, monitor and alert design, notification-channel integration, storage and retention, backup and upgrade planning. Apache HertzBeat, HertzBeat and Apache are trademarks of The Apache Software Foundation. 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.