Observability Azure

Apache HertzBeat on Ubuntu 24.04 on Azure User Guide

| Product: Apache HertzBeat on Ubuntu 24.04 LTS on Azure

Overview

Apache HertzBeat is an open source, real time monitoring and alerting system from the Apache Software Foundation. It monitors servers, operating systems, databases, middleware, web sites, APIs, TLS certificates and fully custom endpoints without installing an agent, evaluates flexible threshold rules, and delivers alerts through more than thirty notification channels including email, Slack, Discord, Telegram and webhooks.

The cloudimg image installs Apache HertzBeat 1.8.0 from the official Apache binary distribution under /opt/hertzbeat, runs it as the dedicated hertzbeat system user on Java 17, and serves the web console and REST API on port 1157. It is a self contained single node: HertzBeat stores its metadata in an embedded H2 database and its metric history in embedded DuckDB, with an in memory real time queue, so there is no external database to provision.

Secure by default: the upstream distribution ships a well known default administrator (admin / hertzbeat) and a well known JWT signing key that is published in the public source. This image ships neither. A hertzbeat-firstboot.service oneshot runs once before the application starts and rotates both to unique, per VM random values, writing the generated admin password to a root only file. No two instances share a credential, and nothing sensitive is baked into the image.

What is included:

  • Apache HertzBeat 1.8.0 (Apache-2.0) under /opt/hertzbeat
  • Embedded H2 metadata database and embedded DuckDB metric history (no separate database to run)
  • hertzbeat.service running as the hertzbeat user on Java 17, serving the console and REST API on port 1157
  • hertzbeat-firstboot.service that rotates the console admin password and the JWT signing key per VM on first boot
  • Per VM admin password written to /root/hertzbeat-credentials.txt (mode 0600, root only)
  • OpenJDK 17 runtime, apt managed for security updates
  • Ubuntu 24.04 LTS base, fully patched
  • 24/7 cloudimg support, 24h response SLA

Prerequisites

An active Azure subscription, an SSH key pair, and a VNet with a subnet. Recommended VM size: Standard_B2s (2 vCPU, 4 GB RAM). HertzBeat is a Java service; 4 GB RAM is comfortable for a single node monitoring many endpoints, and you can scale up for larger fleets.

Step 1: Deploy from the Azure Portal

Search the Marketplace for Apache HertzBeat on Ubuntu 24.04, choose your VM size, and attach an NSG that allows TCP 22 (SSH) from your management network and TCP 1157 (the console and REST API) from the networks that need it. Put HertzBeat behind TLS in production (see the HTTPS section below).

Step 2: Deploy from the Azure CLI

RG="hertzbeat-prod"; LOCATION="eastus"; VM_NAME="hertzbeat-01"
GALLERY_IMAGE_ID="/subscriptions/<sub-id>/resourceGroups/azure-cloudimg/providers/Microsoft.Compute/galleries/cloudimgGallery/images/hertzbeat-ubuntu-24-04/versions/<version>"
SSH_KEY="$(cat ~/.ssh/id_rsa.pub)"
az group create --name "$RG" --location "$LOCATION"
az network vnet create -g "$RG" --name hertzbeat-vnet --address-prefix 10.90.0.0/16 --subnet-name hertzbeat-subnet --subnet-prefix 10.90.1.0/24
az network nsg create -g "$RG" --name hertzbeat-nsg
az network nsg rule create -g "$RG" --nsg-name hertzbeat-nsg --name allow-ssh --priority 100 \
  --source-address-prefixes "<your-mgmt-cidr>" --destination-port-ranges 22 --access Allow --protocol Tcp
az network nsg rule create -g "$RG" --nsg-name hertzbeat-nsg --name allow-console --priority 110 \
  --source-address-prefixes "<your-mgmt-cidr>" --destination-port-ranges 1157 --access Allow --protocol Tcp
az vm create -g "$RG" --name "$VM_NAME" --image "$GALLERY_IMAGE_ID" \
  --size Standard_B2s --storage-sku StandardSSD_LRS \
  --admin-username azureuser --ssh-key-values "$SSH_KEY" \
  --vnet-name hertzbeat-vnet --subnet hertzbeat-subnet --nsg hertzbeat-nsg --public-ip-sku Standard

Step 3: Connect via SSH

ssh azureuser@<vm-ip>

Step 4: Verify the service is running

HertzBeat runs as the hertzbeat system user and listens on port 1157 for both the web console and the REST API.

sudo systemctl is-active hertzbeat
sudo ss -tln | grep ':1157'
curl -s -o /dev/null -w 'GET / -> HTTP %{http_code}\n' http://127.0.0.1:1157/

The service reports active, the JVM is listening on :1157, and the console returns HTTP 200.

The hertzbeat.service active and running as a Java 17 service, listening on port 1157, with the DuckDB history store and website collector working

Step 5: Retrieve your per VM admin credentials

There is no shared default login. On first boot the image generated a unique administrator password for this VM and stored it in a root only file. Read it over SSH:

sudo cat /root/hertzbeat-credentials.txt 2>/dev/null || echo "credentials are generated on first boot"

The file lists the console URL and your unique admin password (mode 0600, owner root). Keep it safe; you can rotate it later from the console under Settings.

Step 6: Confirm the console and REST API are healthy

The web console and the REST API both answer on port 1157. The POST /api/account/auth/form endpoint exchanges your admin credentials for a JWT.

curl -s -o /dev/null -w 'console  -> HTTP %{http_code}\n' http://127.0.0.1:1157/
PW=$(sudo sed -n 's/^HERTZBEAT_ADMIN_PASSWORD=//p' /root/hertzbeat-credentials.txt 2>/dev/null)
curl -s -X POST http://127.0.0.1:1157/api/account/auth/form \
  -H 'Content-Type: application/json' \
  -d "{\"identifier\":\"admin\",\"credential\":\"${PW:-<admin-password>}\"}" \
  | python3 -c 'import sys,json;d=json.load(sys.stdin);print("REST auth OK, JWT issued" if d.get("data",{}).get("token") else "sign in with the password from /root/hertzbeat-credentials.txt")'

The console returns HTTP 200 and the REST API issues a JWT for the per VM admin password.

The HertzBeat web console returning HTTP 200 and the REST API issuing a JWT for the per VM admin credentials

Step 7: Sign in to the console

Open http://<vm-ip>:1157/ in your browser. Sign in with the username admin and the password from /root/hertzbeat-credentials.txt. HertzBeat only shows the "update the initial default password" banner for the upstream default, which this image has already rotated away, so your instance starts with a unique credential.

The Apache HertzBeat 1.8.0 sign in screen served on port 1157

After signing in you land on the dashboard, with monitor category cards across the top, a label overview and a real time status summary.

The Apache HertzBeat dashboard after sign in, showing the network, service and application monitor category cards and the status summary

Step 8: Add your first monitor

From the left menu open Monitors, click New Monitor and choose a monitor type such as Website. Enter the Target Host and Port, give the task a name, set the collection interval, then click OK. HertzBeat starts collecting immediately.

The HertzBeat Monitors list showing a website monitor in the Up state, collecting from its target on a fixed interval

Click the monitor to open its detail view. The real time detail shows the monitoring basics and the live collected metrics, such as the response time, and the historical charts tab plots them over time.

The HertzBeat monitor detail view showing the Up status, monitoring basics and live collected metrics including response time

Step 9: Self contained storage, no external database

HertzBeat runs as a single node using embedded storage, so there is nothing else to deploy. Metadata lives in an embedded H2 database and metric history in embedded DuckDB, both under /opt/hertzbeat/data.

grep -E 'jdbc:h2|store-path: data/history' /opt/hertzbeat/config/application.yml | sed 's/^ *//'
sudo ls -lh /opt/hertzbeat/data/ 2>/dev/null | grep -E 'hertzbeat|history' || echo 'data dir initialises on first boot'

The metadata H2 file and the DuckDB history store are configured under the data directory, which is captured into the image and carried onto every instance.

The application.yml showing the embedded H2 metadata store and embedded DuckDB history store, with the in memory real time queue and all external stores disabled

Step 10: How secure by default works

A hertzbeat-firstboot.service oneshot runs once, ordered before hertzbeat.service, and rewrites the shipped configuration with per VM secrets before the application ever starts.

systemctl is-enabled hertzbeat-firstboot.service
sudo stat -c '%n perms=%a owner=%U:%G' /root/hertzbeat-credentials.txt 2>/dev/null || echo 'credentials file is created on first boot'
apt-mark showhold

The first boot service is enabled for the next fresh instance, the credentials file is root only, and there are no held packages, so the OS security baseline is intact.

The hertzbeat-firstboot.service oneshot that rotates the console admin password and JWT signing key per VM before the application starts

Step 11: Enable HTTPS

Put HertzBeat behind a TLS reverse proxy in production. Install nginx, point a DNS record at your VM, then obtain a certificate with certbot and proxy port 443 to 127.0.0.1:1157:

sudo apt-get install -y nginx certbot python3-certbot-nginx
sudo certbot --nginx -d <your-domain> --agree-tos -m <your-email> --redirect

Configure the nginx server block to proxy_pass http://127.0.0.1:1157; and restrict the NSG so only nginx (ports 80 and 443) is reachable from the internet, keeping 1157 internal.

Managing the service

sudo systemctl status hertzbeat
sudo systemctl restart hertzbeat
sudo journalctl -u hertzbeat -f

HertzBeat logs to the journal and to /opt/hertzbeat/logs. Back up the instance by snapshotting the OS disk or copying /opt/hertzbeat/data while the service is stopped.

Support

cloudimg provides 24/7 support for this image via email and live chat: deployment, TLS termination, upgrades, notification integrations, custom monitor templates and performance tuning. Email support@cloudimg.co.uk.

This is a repackaged open source software product with additional charges for cloudimg support services. 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.