AKHQ for Apache Kafka 0.28.0

In the AWS Marketplace listing, choose Continue to Subscribe, then Continue to Configuration. Pick AKHQ for Apache Kafka 0.28.0 on Ubuntu 24.04 as the software version, select your Region, and choose Launch through EC2. Choose m5.large, your key pair and a security group as described above.

Alternatively, launch with the AWS CLI. Replace the values in angle brackets:

aws ec2 run-instances --region <region> --image-id <ami-id-from-the-listing> \
  --instance-type m5.large --key-name <your-key-pair> \
  --security-group-ids <your-security-group> --subnet-id <your-subnet> \
  --metadata-options HttpTokens=required,HttpEndpoint=enabled \
  --tag-specifications 'ResourceType=instance,Tags=[{Key=Name,Value=akhq}]'

First boot takes about a minute after the instance is running. The boot service generates the secrets and the certificate and formats the demo broker's storage. Then Kafka loads the demo data and AKHQ starts.

Connect over SSH with the key pair you launched with.

Version SSH user

AKHQ for Apache Kafka 0.28.0 on Ubuntu 24.04 ubuntu

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

Confirm that all four services are active and that the first-boot marker exists:

systemctl is-active akhq-firstboot kafka akhq nginx
sudo test -f /var/lib/sac/data/akhq-firstboot.done && echo FIRSTBOOT_DONE

All four units report active, and the first-boot marker is present:

active active active active FIRSTBOOT_DONE

List the listening ports. Only SSH and nginx listen on network ports. AKHQ (8080, 28081) and Kafka (9092, 9093) listen on the loopback address:

sudo ss -lntp | awk 'NR>1 {print $4, $6}' | grep -v '127.0.0.5' | sed -E 's/,pid=[0-9]+,fd=[0-9]+//g' | sort

0.0.0.0:22 users:(("sshd"),("systemd")) 0.0.0.0:443 users:(("nginx"),("nginx"),("nginx")) 0.0.0.0:80 users:(("nginx"),("nginx"),("nginx")) [::]:22 users:(("sshd"),("systemd")) [::]:443 users:(("nginx"),("nginx"),("nginx")) [::]:80 users:(("nginx"),("nginx"),("nginx")) [::ffff:127.0.0.1]:28081 users:(("java")) [::ffff:127.0.0.1]:8080 users:(("java")) [::ffff:127.0.0.1]:9092 users:(("java")) [::ffff:127.0.0.1]:9093 users:(("java"))

Read the credentials file as root. The file is readable by root only:

sudo cat /root/akhq-credentials.txt

The file contains the URL, the admin user and the admin password:

# AKHQ for Apache Kafka 0.28.0 on Ubuntu 24.04 - generated on first boot by akhq-firstboot.service.
# The admin password below is unique to this instance; none was baked into the image. Keep this file secret.
# Open AKHQ_URL in a browser and log in as AKHQ_ADMIN_USER. The certificate is self signed (minted on this
# instance): compare the SHA-256 fingerprint your browser shows with the one printed by
#
sudo openssl x509 -in /etc/nginx/ssl/akhq.crt -noout -fingerprint -sha256
# or install a CA-issued certificate in /etc/nginx/ssl. Change the served name:
sudo akhq-set-hostname <dns-name> AKHQ_URL=https://<public-ip>/ AKHQ_ADMIN_USER=admin AKHQ_ADMIN_PASSWORD=<AKHQ_ADMIN_PASSWORD>
# Re-verify the appliance:
sudo akhq-selfcheck Connect your own Kafka cluster: /etc/akhq/application.yml
# User guide: https://secureanycloud.com/stacks/akhq-for-apache-kafka-0-28-0/

The URL uses the instance's public IP address from the EC2 instance metadata, or the private address when the instance has no public one. The certificate also names the public DNS name and the private IP address. If you stop and start the instance without an Elastic IP, the boot service picks up the new address and issues a new certificate for it. To serve AKHQ under your own DNS name, see Step 9.

Print the certificate's SHA-256 fingerprint over SSH, so that you can check it in the browser in Step 5:

sudo openssl x509 -in /etc/nginx/ssl/akhq.crt -noout -fingerprint -sha256

sha256 Fingerprint=<sha256-fingerprint>

The certificate is self-signed and unique to this instance. Do not add it to your operating system's or browser's trust store. Compare the fingerprint instead, or replace the certificate with one from a certificate authority (Step 9).

Open https://<public-ip>/ in your browser. The browser warns that the certificate is self-signed. Open the certificate details, check that its SHA-256 fingerprint matches the one you printed in Step 4, and only then continue to the site. Log in as admin with AKHQ_ADMIN_PASSWORD.

The cluster named SecureAnyCloud is the preloaded demo broker. The topic list shows every topic with its message count, size, partitions and the consumer groups reading it. Open a topic to read its messages. AKHQ shows the key, timestamp, partition, offset and decoded value. You can sort, filter by partition or time, search, download results, produce a message or start a Live Tail.

Consumer Groups shows each group's state, coordinator, members and lag per topic. The demo group demo-consumer has read the first 20 orders and lags behind the 8 produced after it.

Nodes lists the brokers with their partition share. Open a node to see its full configuration.

Everything in the UI is also available as a JSON API under /api. Without a session, the API answers 401:

curl -sk -m 10 -o /dev/null -w '%{http_code}\n' -H 'Accept: application/json' https://127.0.0.1/api/sac/topic

401

Log in through the same form the browser uses, keep the session cookie, and call the API. On the instance, the commands use https://127.0.0.1/, because the instance serves all of its own names. From elsewhere, use your AKHQ_URL. The password goes to curl on standard input, never on the command line, and the cookie jar is removed at the end:

AKHQ_URL=https://127.0.0.1/
JAR=$(mktemp)
sudo sed -n 's/^AKHQ_ADMIN_PASSWORD=//p' /root/akhq-credentials.txt | tr -d '\n' \
  | curl -sk -m 20 -c "$JAR" -o /dev/null -w '%{http_code} %{redirect_url}\n' --data-urlencode username=admin --data-urlencode password@- "${AKHQ_URL}login" curl -sk -m 20 -b "$JAR" -H 'Accept: application/json' "${AKHQ_URL}api/sac/topic" | jq -r '.results[] | "\(.name) partitions=\(.partitions | length)"' curl -sk -m 20 -b "$JAR" -H 'Accept: application/json' "${AKHQ_URL}api/sac/group" | jq -c '.results[] | {id, state}' curl -sk -m 20 -b "$JAR" -H 'Accept: application/json' "${AKHQ_URL}api/sac/topic/demo-orders/data" | jq -r '.results[:3][] | "\(.key) \(.value)"' rm -f "$JAR"

A successful login answers 303 back to the UI with the session cookie set. A wrong password answers 303 to the login page with no cookie:

303 https://127.0.0.1/ui demo-orders partitions=3 demo-payments partitions=1 demo-users partitions=1 {"id":"demo-consumer","state":"Empty"} order-001 {"orderId":1001,"customer":"cust-02","item":"SKU-0037","qty":2,"amount":22.99,"status":"PLACED"} order-006 {"orderId":1006,"customer":"cust-07","item":"SKU-0222","qty":2,"amount":87.99,"status":"PLACED"} order-002 {"orderId":1002,"customer":"cust-03","item":"SKU-0074","qty":3,"amount":35.99,"status":"PLACED"}

Sessions last one hour. Log in again after that.

AKHQ reads its clusters from /etc/akhq/application.yml, which is owned by root and readable by the akhq group. Add a connection under akhq.connections, next to the demo SecureAnyCloud entry.

For Amazon MSK with SASL/SCRAM, use the cluster's bootstrap string from the MSK console (port 9096). The user and password are the ones stored in AWS Secrets Manager for the cluster:

akhq: connections: sac: properties: bootstrap.servers: "127.0.0.1:9092" my-msk: properties: bootstrap.servers: "b-1.mycluster.abc123.c2.kafka.us-east-1.amazonaws.com:9096,b-2.mycluster.abc123.c2.kafka.us-east-1.amazonaws.com:9096" security.protocol: SASL_SSL sasl.mechanism: SCRAM-SHA-512 sasl.jaas.config: org.apache.kafka.common.security.scram.ScramLoginModule required username="<msk-user>" password="<msk-password>";

For mutual TLS (MSK TLS client authentication on port 9094, or your own brokers), copy the keystore and truststore into /etc/akhq/ with owner root:akhq and mode 0640. Then add a connection like this:

my-mtls-cluster: properties: bootstrap.servers: "broker-1.example.internal:9094" security.protocol: SSL ssl.truststore.location: /etc/akhq/kafka.truststore.jks ssl.truststore.password: "<truststore-password>" ssl.keystore.location: /etc/akhq/kafka.keystore.jks ssl.keystore.password: "<keystore-password>" ssl.key.password: "<key-password>"

To add a schema registry or a Kafka Connect cluster, extend the same connection (schema-registry: {url: ...}, connect: [{name: ..., url: ...}]; see the AKHQ configuration documentation). Then restart AKHQ and watch the log as it comes up:

sudo systemctl restart akhq && sudo journalctl -u akhq -n 20 --no-pager

Notes:

• Amazon MSK IAM authentication is not available from this image. IAM authentication needs the instance-role credentials from the instance metadata service. This image blocks that service for AKHQ on purpose, which keeps a malicious or mistaken connection setting from reaching the instance's credentials. Use SASL/SCRAM or mutual TLS instead. MSK supports both alongside IAM on the same cluster.
• Keep micronaut.server.host at 127.0.0.1 and do not enable micronaut.server.ssl. Otherwise AKHQ's configuration check refuses to start. nginx already provides HTTPS.
• /etc/akhq/application.yml holds your cluster passwords. It is not world-readable, and it is the file to back up (Step 13).
• nginx refuses (400) any URL whose path carries an encoded /, ., \ or NUL, or a .. segment. Kafka topic names cannot contain those characters. However, a consumer group, connector or schema subject whose name contains / or \ cannot be opened in AKHQ through this front door.

The demo broker is a single-node Apache Kafka 4.4.0 (KRaft) on 127.0.0.1:9092, with its data in /var/lib/kafka/data and its settings in /etc/kafka/server.properties. Every instance formats its own fresh cluster at first boot. Kafka's command-line tools are in /opt/kafka/bin:

LOG_DIR=/tmp/kafka-cli KAFKA_JMX_OPTS=-Dcli=1 /opt/kafka/bin/kafka-topics.sh --bootstrap-server 127.0.0.1:9092 --list LOG_DIR=/tmp/kafka-cli KAFKA_JMX_OPTS=-Dcli=1 /opt/kafka/bin/kafka-consumer-groups.sh --bootstrap-server 127.0.0.1:9092 --describe --group demo-consumer

__consumer_offsets demo-orders demo-payments demo-users GROUP TOPIC PARTITION CURRENT-OFFSET LOG-END-OFFSET LAG CONSUMER-ID HOST CLIENT-ID demo-consumer demo-orders 0 6 9 3 - - - demo-consumer demo-orders 1 6 9 3 - - - demo-consumer demo-orders 2 8 10 2 - - -

The broker accepts connections from this instance only and has no authentication, so it is a sandbox, not a production cluster. You can delete the demo-* topics and the demo-consumer group at any time.

Once AKHQ points at your own cluster, you can remove the SecureAnyCloud connection from /etc/akhq/application.yml and switch the broker off. AKHQ does not depend on it:

sudo systemctl disable --now kafka && sudo systemctl restart akhq

Point a DNS record at the instance, then tell AKHQ to serve that name. This command does four things:

• Updates nginx.
• Issues a new self-signed end-entity certificate that names the host.
• Accepts https://<name> as an allowed origin, for the origin check and for the logout and Kafka Connect links.
• Updates the URL in the credentials file.

sudo akhq-set-hostname akhq.<your-domain>

The name is saved in /etc/sac/akhq-hostname and survives reboots.

For a certificate that browsers trust without a warning, use one from a certificate authority, such as your own CA or Let's Encrypt. Replace /etc/nginx/ssl/akhq.crt and /etc/nginx/ssl/akhq.key, keep the key mode 0600, and run sudo systemctl reload nginx.

Running akhq-set-hostname again later issues a new self-signed certificate over yours. Set the name first and install your certificate afterwards.

/etc/akhq/secrets.yml holds the session-signing secret and the users. Passwords are stored as SHA-256 hashes (passwordHash: SHA256). AKHQ also accepts BCRYPT.

Groups map users to AKHQ roles. The admin group has full access. For a read-only user, add a reader group to akhq.security.groups in application.yml (see the AKHQ security documentation) and give the user that group.

To change the admin password, run the block below. It reads the new password without echoing it. It writes the hash into secrets.yml and the password into the credentials file, through standard input and never the command line. Then it restarts AKHQ:

read -rsp 'New AKHQ admin password: ' P; echo printf '%s' "$P" | sudo python3 -I -c ' import hashlib, re, sys p = sys.stdin.read() h = hashlib.sha256(p.encode()).hexdigest() s = open("/etc/akhq/secrets.yml").read() s = re.sub(r"(password: \")[0-9a-f]{64}(\")", lambda m: m.group(1) + h + m.group(2), s, count=1) open("/etc/akhq/secrets.yml", "w").write(s) c = open("/root/akhq-credentials.txt").read() c = re.sub(r"(?m)^AKHQ_ADMIN_PASSWORD=.*$", lambda m: "AKHQ_ADMIN_PASSWORD=" + p, c) open("/root/akhq-credentials.txt", "w").write(c) ' unset P;
sudo systemctl restart akhq

To rotate the session-signing secret, run the block below. Every user is logged out:

sudo python3 -I -c ' import re, secrets s = open("/etc/akhq/secrets.yml").read() s = re.sub(r"(secret: \")[0-9a-f]{64}(\")", lambda m: m.group(1) + secrets.token_hex(32) + m.group(2), s, count=1) open("/etc/akhq/secrets.yml", "w").write(s) ' && sudo systemctl restart akhq

The secret must stay 64 hexadecimal characters. AKHQ's configuration check refuses anything else, including AKHQ's well-known built-in default.

akhq-selfcheck re-proves the whole appliance with this instance's credentials. It checks each of the following:

• HTTPS, and refusal of anonymous and HTTP Basic requests.
• The login with the right password and with a wrong one.
• The topic and consumer group APIs.
• That the session token is signed with this instance's own secret, and that a token signed with AKHQ's built-in default secret is refused.
• The redirect, and refusal of other host names, cross-origin requests and WebSocket upgrades.
• The loopback-only ports, and the metadata block inside every service.
• That the served certificate is this instance's end-entity certificate.
• The cross-site guard on the logout and Kafka Connect links. A same-origin request passes. Cross-site and same-site requests, links opened from outside the browser, and requests with no browser signal at all are refused.

Run it:

sudo akhq-selfcheck

AKHQ appliance self-check (https://<public-ip>/) [ok] HTTPS AKHQ login page -> 200 [ok] topic API without a session -> 401; HTTP Basic (even with the right password) -> 401 [ok] wrong password -> 303 back to the login page, no session cookie [ok] admin login with the per-instance password -> session; topic API -> 200 and lists demo-orders [ok] consumer-group API -> 200 and lists demo-consumer [ok] session token is HS256-signed with this instance's own secret (re-signed copy -> 200) [ok] tokens signed with AKHQ's built-in default secret or a random secret -> 401 [ok] port 80 -> 301 https://<public-ip>/; unknown Host -> 444; CONNECT refused; cross-origin POST -> 403; WebSocket upgrade -> 403 [ok] AKHQ (8080/28081) and Kafka (9092/9093) refuse the private address; AKHQ speaks no TLS (no SNI) itself [ok] instance metadata refused inside the akhq, kafka and nginx cgroups (loopback control 200) [ok] TLS certificate: end-entity (CA:FALSE, serverAuth, no certificate signing), names <public-ip>; SHA-256 fingerprint <sha256-fingerprint> [ok] cross-site GET guard: 13/13 (/logout); Kafka Connect restart/pause/resume/task-restart: 24/24 foreign, none or missing signals -> nginx 403 SELFCHECK OK - HTTPS (end-entity certificate), per-instance login and session secret, origin and cross-site guards, loopback-only AKHQ and Kafka, metadata block verified.

The self-check reads the demo broker's topics, so once you have switched the broker off (Step 8), it stops at that check.

The metadata block is a systemd IPAddressDeny rule on each service. You can see it in effect:

for u in akhq kafka nginx akhq-firstboot; do printf '%s: ' $u; systemctl show -p IPAddressDeny --value $u.service; done

akhq: 168.63.129.16/32 169.254.169.254/32 fd00:ec2::254/128 kafka: 168.63.129.16/32 169.254.169.254/32 fd00:ec2::254/128 nginx: 168.63.129.16/32 169.254.169.254/32 fd00:ec2::254/128 akhq-firstboot: 168.63.129.16/32 169.254.169.254/32 fd00:ec2::254/128

Check the AKHQ build provenance, the Java runtime and the Kafka client library:

sed -n '1,6p' /usr/share/doc/akhq/BUILD-PROVENANCE.txt /opt/akhq/jre/bin/java -version 2>&1 | sed -n 1p ls /opt/kafka/libs/kafka-clients-*.jar

AKHQ 0.28.0 - official upstream release jar (not rebuilt) source https://github.com/tchiotludo/akhq/releases/download/0.28.0/akhq-0.28.0-all.jar sha256 bb3c5f8ff52e67fa8b3324a6597664faa467dbe3b60c053e6d97304a6079b5ca (GitHub release asset digest) licence Apache License 2.0 (LICENSE from the 0.28.0 tag, sha256 55b6cb57c1485b07a544fec6cce494e916682f36977e8dbb1620de91d6eeca86) runtime Eclipse Temurin 25.0.5+8 JRE (6fac98f0c8202efc3135a9e9e42aa61963ec42d1c5cbb40caf231e7b14a24ef6), /opt/akhq/jre, used by AKHQ only netty-handler 4.2.13.Final (inside the jar) openjdk version "25.0.5" 2026-10-20 LTS /opt/kafka/libs/kafka-clients-4.4.0.jar

Known scanner finding. Vulnerability scanners report CVE-2026-75595 (GHSA-c4c3-7fpv-j4q5, a server name indication routing bypass in netty-handler) against the AKHQ 0.28.0 jar, which bundles netty-handler 4.2.13. The flaw cannot be reached on this image. It is in netty's TLS server name handling, and AKHQ here has no TLS listener at all.

AKHQ serves plain HTTP on 127.0.0.1 only, and nginx terminates TLS in front of it. AKHQ's configuration check refuses to start if TLS is ever switched on inside AKHQ. The fix is merged upstream (AKHQ pull request #3351) and arrives with the next AKHQ release, which SecureAnyCloud will publish as a new version of this listing.

Path What it is

/etc/akhq/application.yml AKHQ settings and your cluster connections

/etc/akhq/secrets.yml Session-signing secret and users (written at first boot)

/root/akhq-credentials.txt URL and admin password (root only)

/etc/kafka/server.properties, /var/lib/kafka/data Demo broker settings and data

/etc/nginx/sites-available/sac-akhq The HTTPS front door. The certificate and key are in /etc/nginx/ssl/

/usr/share/doc/akhq/ LICENSE and BUILD-PROVENANCE.txt

journalctl -u akhq AKHQ's log (also kafka, nginx, akhq-firstboot)

• Back up configuration only. AKHQ keeps no data of its own. Back up /etc/akhq (your connections, users and secret), /etc/sac and /etc/nginx/ssl. The demo broker's data is disposable.
• Patching and upgrades. Ubuntu security updates install automatically (unattended-upgrades), including the OpenJDK runtime the demo broker uses. AKHQ and its Java runtime live in /opt/akhq. To upgrade, launch the newer version from the listing and copy /etc/akhq across.
• Memory. AKHQ and the demo broker each run with a bounded Java heap (768 MB and 1 GB). An m5.large is comfortable. For large clusters with many topics, give AKHQ more heap in /etc/default/akhq (JAVA_OPTS) and use a larger instance.

• Restrict access. Limit TCP 443 in the security group to the networks your users browse from, and TCP 22 to your admin network. AKHQ can change and delete topics, offsets and data on the clusters it manages. Treat it as an administrative console, ideally reachable over a VPN or a private load balancer only.
• Use a trusted certificate. Serve AKHQ under your own DNS name with a certificate from a trusted CA (Step 9). Until then, check the self-signed certificate's fingerprint (Step 4) rather than adding it to a trust store.
• Manage users. Change the admin password if you share the credentials file, give other people their own users, and use read-only groups where you can (Step 10).
• Connect securely. Connect to your clusters with SASL/SCRAM or mutual TLS over TLS (Step 7), with a dedicated Kafka user whose ACLs match what AKHQ users should be able to do.
• Publish only nginx. Keep AKHQ on 127.0.0.1.