Apache Iggy on Ubuntu 24.04 on Azure User Guide

Overview

Apache Iggy is a persistent message streaming platform written in Rust that moves millions of messages per second over TCP, QUIC and HTTP with very low latency and a small footprint. Producers publish messages to topics that are grouped into streams and partitions, and consumers read them with offsets and consumer groups, so you can build event driven pipelines, log and metric transport, and real time data flows. The cloudimg image ships the official Apache Iggy server and its web console as two managed services on Docker Engine, fronted by an nginx reverse proxy on port 80, on a hardened, fully patched Ubuntu 24.04 LTS base. A unique root password is generated on the first boot of every VM and the dev iggy/iggy credential is never set. Backed by 24/7 cloudimg support.

What is included:

• The official Apache Iggy 0.8.0 server (apache/iggy) run under systemd as iggy-server.service
• The official Apache Iggy web console 0.3.0 (apache/iggy-web-ui) run under systemd as iggy-web-ui.service
• An nginx reverse proxy on :80 serving the console and proxying the Iggy HTTP REST API at /api
• The Iggy TCP binary transport exposed on :8090 for client SDK applications
• A per VM root password generated on first boot and recorded in a root only file
• No shipped default login: the root user is created with a unique per VM secret, and the dev iggy/iggy credential and common weak guesses are all rejected
• A hardened, fully patched Ubuntu 24.04 LTS base with automatic security updates

Step 1 - Launch the VM

Launch the image from the Azure Marketplace in the portal: choose the cloudimg Apache Iggy on Ubuntu 24.04 LTS offer, pick a size (Standard_B2s is a fine starting point; size up for higher throughput), select or create a VNet, and allow inbound ports 22 (SSH), 80 (HTTP, the web console) and 8090 (the Iggy TCP transport) in the network security group. Restrict 22 and 8090 to trusted source ranges.

You can also deploy from the Azure CLI. Replace the resource group, image URN, size and admin user to suit your environment:

az vm create \
  --resource-group my-rg \
  --name apache-iggy \
  --image <marketplace-image-urn> \
  --size Standard_B2s \
  --admin-username azureuser \
  --generate-ssh-keys \
  --public-ip-sku Standard

Open ports 22, 80 and 8090 on the VM's network security group, restricting 22 and 8090 to your own address range.

Step 2 - Verify the services

SSH in as azureuser and confirm Docker, the Iggy server, the web console and nginx are all active. nginx serves the console on port 80 and the Iggy TCP transport listens on port 8090.

systemctl is-active docker iggy-server iggy-web-ui nginx

ss -tlnp | grep -E ':80 |:8090 ' | awk '{print $1, $4}' | sort -u

docker ps --format '{{.Names}}  {{.Image}}  {{.Status}}'

Step 3 - Retrieve the per VM root password

Every VM generates its own Iggy root password on first boot and writes it, along with the console URL and the API and TCP endpoints, to a root only credentials file. Read it with sudo:

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

curl -s -o /dev/null -w 'healthz -> HTTP %{http_code}\n' http://127.0.0.1/healthz

You sign in to the web console as user iggy with the IGGY_ROOT_PASSWORD from this file. The same credentials authenticate against the HTTP REST API and the TCP transport.

Step 4 - Sign in to the web console

Browse to http://<vm-public-ip>/. You are redirected to the sign in page. Enter username iggy and the password from Step 3, then click Login.

Step 5 - The overview dashboard

After signing in you land on the overview dashboard, which shows live server statistics: process and memory usage, uptime, and the number of streams, topics, partitions, segments, messages and connected clients.

Step 6 - Streams and topics

Open Streams from the left menu. A stream is a named container for topics; a topic holds messages across one or more partitions. Click New stream to create one, then Add Topic to add a topic with a partition count and compression setting. The example below shows an events stream with an orders topic spread across two partitions.

Step 7 - Inspect a topic and its partitions

Click a topic to inspect it. The topic view shows each partition with its current offset, segment count, message count and size, so you can see exactly how messages are distributed. Producers append messages to partitions and consumers read them by offset, individually or in consumer groups.

Step 8 - Manage streams from the command line

The image includes an iggy command that runs the version matched CLI bundled inside the running server container, so you can script stream, topic and message operations. Retrieve the password and manage your streams (the example creates a stream and topic, sends a few messages, then lists the streams):

PW=$(sudo grep '^IGGY_ROOT_PASSWORD=' /root/apache-iggy-credentials.txt | cut -d= -f2-)
sudo iggy -u iggy -p "$PW" stream create events >/dev/null 2>&1 || true
sudo iggy -u iggy -p "$PW" topic create events orders 2 none >/dev/null 2>&1 || true
sudo iggy -u iggy -p "$PW" message send events orders "order 1001 placed" "order 1002 shipped" "order 1003 delivered" >/dev/null 2>&1 || true
sudo iggy -u iggy -p "$PW" stream list

PW=$(sudo grep '^IGGY_ROOT_PASSWORD=' /root/apache-iggy-credentials.txt | cut -d= -f2-)
sudo iggy -u iggy -p "$PW" topic list events

Step 9 - Use the HTTP REST API

The Iggy HTTP REST API is proxied by nginx at /api, so applications and scripts can reach it on the same host and port as the console. Log in to obtain a bearer token, then call the API. This example lists the streams:

PW=$(sudo grep '^IGGY_ROOT_PASSWORD=' /root/apache-iggy-credentials.txt | cut -d= -f2-)
TOKEN=$(curl -s -H 'Content-Type: application/json' -d "{\"username\":\"iggy\",\"password\":\"$PW\"}" http://127.0.0.1/api/users/login | jq -r '.access_token.token')
curl -s -H "Authorization: Bearer $TOKEN" http://127.0.0.1/api/streams | jq -c '.[] | {id, name, topics_count, messages_count}'

From outside the VM, use http://<vm-public-ip>/api as the base URL. The unauthenticated GET /api/ping endpoint is handy for health checks and load balancer probes.

Step 10 - Connect a client application

Client SDK applications connect over the TCP binary transport on port 8090 using the same iggy username and per VM password. Point your producer or consumer at <vm-public-ip>:8090 and make sure the network security group allows inbound 8090 from your application's address range. The Rust, Python, Go, Node, C#, Java and other Iggy SDKs all speak this transport:

# Example connection settings for an Iggy SDK client
IGGY_TCP_SERVER = <vm-public-ip>:8090
IGGY_USERNAME   = iggy
IGGY_PASSWORD   = <the IGGY_ROOT_PASSWORD from Step 3>

Create a dedicated, least privilege Iggy user for each application from the console (Settings) or the API, rather than sharing the root credential.

Step 11 - No known or default credentials

Apache Iggy only creates its root user on the first server start with an empty data directory, and the cloudimg image sets a unique per VM password there on first boot. The dev iggy/iggy credential is never set. You can prove this with the built in round trip check, which confirms the per VM root signs in through the HTTP API while the iggy/iggy credential and common weak guesses are all rejected:

sudo bash /usr/local/sbin/apache-iggy-cred-roundtrip.sh

Where your data lives

Iggy stores all of its state (streams, topics, partitions and message segments, plus the users store) in a Docker named volume, iggy-data, mounted into the server container at /data. The volume persists across container restarts and VM reboots, so your streams and messages survive. Inspect it with:

docker volume inspect iggy-data --format '{{.Mountpoint}}'

Back up the volume with a standard file level backup of that path while the server is stopped, or use the Iggy tooling to snapshot server state.

Adding your own domain and TLS

The appliance serves plain HTTP on port 80. Because the console reaches the API on the same origin it was loaded from, you can front it with your own domain and a TLS certificate without changing any configuration inside the VM. Terminate TLS with Azure Application Gateway, an nginx or Caddy reverse proxy, or a managed load balancer with a certificate for your domain, and forward to port 80 on the VM.

Security notes

• Apache Iggy serves plain HTTP on port 80. For anything beyond a trusted network, put it behind your own TLS terminating reverse proxy or Azure Application Gateway with a certificate for your domain.
• The root password is unique per VM and the dev iggy/iggy credential and weak guesses are all rejected. Keep /root/apache-iggy-credentials.txt protected and create dedicated per application users rather than sharing the root credential.
• Only ports 22 (SSH), 80 (console and API) and 8090 (TCP transport) are exposed. The HTTP API and the console's Node port are bound to loopback and reached only through nginx. Restrict 22 and 8090 to trusted source ranges in the network security group.
• The base OS is fully patched at build time and keeps unattended security updates enabled for ongoing protection.

Support

This image is built and maintained by cloudimg with 24/7 support. Apache Iggy is free and open source software licensed under the Apache License 2.0. Apache Iggy is a trademark of The Apache Software Foundation; this image is provided by cloudimg and is not affiliated with or endorsed by the Apache Software Foundation or the Apache Iggy project.