Hoop on Ubuntu 24.04 on Azure User Guide

Overview

This image runs Hoop 1.117.1, the open source access gateway from hoophq, on Ubuntu 24.04 LTS. Hoop is a layer 7 gateway that sits between your people and your infrastructure: instead of handing out standing credentials, users connect through Hoop, which enforces access at the wire protocol level, records every session, and can route risky actions through review and approval. It brokers access to PostgreSQL, MySQL, SQL Server and MongoDB databases, SSH and RDP servers, Kubernetes and internal web apps, and keeps a full audit trail of who did what.

The pinned upstream gateway is run as the official hoophq/hoop container under a systemd service that starts it on boot and restarts it on failure, backed by a local PostgreSQL 16 database on the same VM. The gateway serves its web console and REST API on port 8009 and accepts agent connections over gRPC on port 8010. PostgreSQL is bound to loopback only and holds all gateway state.

What is included:

• Hoop 1.117.1 (official hoophq/hoop gateway image, pinned by digest), run by systemd
• The Hoop web console and REST API on :8009
• The agent gRPC endpoint on :8010 for enrolling access agents
• A per-VM administrative API key generated on first boot and recorded in a root-only file
• A per-VM PostgreSQL password generated on first boot
• PostgreSQL 16, bound to loopback, holding organizations, users, connections, agents and session audit logs
• postgresql.service, docker.service and hoopgateway.service as systemd units, enabled and active
• Local password authentication with no baked-in administrator account
• 24/7 cloudimg support

Prerequisites

An active Azure subscription, an SSH key pair, and a VNet plus subnet in the target region. Standard_B2s (2 vCPU / 4 GiB RAM) is a sensible starting point; size up for heavier use. NSG inbound: allow 22/tcp from your management network, 8009/tcp for the web console, and 8010/tcp for agent connections. Hoop serves plain HTTP on port 8009; for production, front it with your own domain and TLS and set the API URL accordingly (see the final step).

Step 1 - Deploy from the Azure Marketplace

Sign in to the Azure Portal, choose Create a resource, search the Marketplace for Hoop by cloudimg, and select Create. On Basics pick your subscription, resource group, region and size; under Administrator account choose SSH public key and paste your key; under Inbound port rules allow SSH (22), 8009 and 8010. Then Review + create then Create.

Step 2 - Deploy from the Azure CLI

az vm create \
  --resource-group <your-rg> \
  --name hoop \
  --image <marketplace-image-urn> \
  --size Standard_B2s \
  --admin-username azureuser \
  --ssh-key-values ~/.ssh/id_ed25519.pub \
  --vnet-name <your-vnet> --subnet <your-subnet> \
  --public-ip-sku Standard

az vm open-port --resource-group <your-rg> --name hoop --port 8009 --priority 1010
az vm open-port --resource-group <your-rg> --name hoop --port 8010 --priority 1020

Step 3 - Connect to your VM

ssh azureuser@<vm-public-ip>

Step 4 - Confirm the services are running

The gateway runs as the hoopgateway systemd service (a host-networked hoophq/hoop container) and talks to PostgreSQL on 127.0.0.1:5432. Confirm all three services are active and that the gateway is listening on its web (8009) and agent gRPC (8010) ports:

systemctl is-active postgresql docker hoopgateway
sudo ss -tlnp | grep -E ':8009|:8010' | awk '{print $4}' | sort -u

Expected output:

active
active
active
*:8009
*:8010

Step 5 - Retrieve your per-VM credentials

On the first boot of every VM, hoop-firstboot.service generates a unique PostgreSQL password and a unique administrative API key, creates the gateway database, and writes the access URLs and the API key into a root-only file. Read it with:

sudo cat /root/hoop-credentials.txt

There is no default or shared credential in the image: the web console uses local password authentication with no administrator baked in, and the API key is unique to this VM. The first user you register in the console (next steps) becomes your organization administrator. Store the API key somewhere safe.

Step 6 - Confirm the gateway health and admin API

The gateway exposes an unauthenticated health endpoint and an authenticated admin REST API. Confirm the health endpoint returns 200, then use the per-VM API key from the credentials file to call an admin endpoint (a wrong key is rejected with 401):

curl -s -o /dev/null -w 'healthz: %{http_code}\n' http://127.0.0.1:8009/api/healthz
API_KEY=$(sudo grep '^HOOP_API_KEY=' /root/hoop-credentials.txt | cut -d= -f2-)
curl -s -o /dev/null -w 'wrong key:  %{http_code}\n' -H 'Api-Key: bad|bad' http://127.0.0.1:8009/api/users
curl -s -o /dev/null -w 'per-VM key: %{http_code}\n' -H "Api-Key: ${API_KEY}" http://127.0.0.1:8009/api/users

Expected output:

healthz: 200
wrong key:  401
per-VM key: 200

Step 7 - Sign in and create your administrator

Browse to http://<vm-public-ip>:8009/. Because the image ships with no administrator, the first account you create becomes the administrator of your organization. Click Create one, register with an email and a strong password, then sign in.

Hoop points the browser console at the API URL it detects for this VM. On this image hoop-configure.service sets the API URL to the VM's public IP on every boot, so signing in over the Azure public IP works out of the box. If you reach Hoop through a different hostname (a DNS name, a load balancer or your own TLS proxy), set API_URL and GRPC_URL in /etc/hoop/hoop.env and run sudo systemctl restart hoopgateway.

Step 8 - Enroll an access agent

Hoop reaches the systems it protects through lightweight agents that dial the gateway's gRPC endpoint on port 8010. Open Agents from the left navigation, click Setup new Agent, and follow the instructions to run an agent (as a container or binary) with the agent key Hoop generates. Once the agent connects it shows as Online.

Step 9 - Register a connection

Open Resources and click Setup new Resource to register a connection - a database (PostgreSQL, MySQL, SQL Server, MongoDB), an SSH or RDP server, a Kubernetes cluster or a shell command - bound to one of your agents. Users then request access to the connection through Hoop rather than connecting directly, and every session is recorded and, optionally, sent for review before it runs.

Step 10 - Review the audit dashboard

Open Dashboard to see an overview of sessions executed, reviews sent and data redacted, and Sessions to browse the full immutable log of every command and query run through the gateway. This is the audit trail that lets you answer who accessed what, when, and what they did.

Step 11 - Production hardening

The image ships the fully functional gateway, console and API. For production:

• TLS and DNS: front Hoop with your own domain and a TLS-terminating reverse proxy or Azure Application Gateway, then set API_URL and GRPC_URL in /etc/hoop/hoop.env to the https:///grpc(s):// addresses and sudo systemctl restart hoopgateway.
• Single sign-on: switch AUTH_METHOD in /etc/hoop/hoop.env from local to oidc or saml and configure your identity provider to enforce SSO for console access.
• Reviews and guardrails: require approvals on sensitive connections and add guardrail rules and live data masking from the console.

Maintenance

• Back up your data: all gateway state - organizations, users, connections, agents and session audit logs - lives in the local hoopdb PostgreSQL database. Snapshot the OS disk, or use pg_dump hoopdb for logical backups.
• API URL: the API URL is set to the detected public IP on each boot. For a stable hostname or HTTPS, set API_URL/GRPC_URL in /etc/hoop/hoop.env and sudo systemctl restart hoopgateway.
• Security updates: unattended security upgrades are enabled, so the OS keeps itself patched. Reboot when a new kernel is installed.
• Upgrades: the gateway image is pinned for reproducibility; pull a newer hoophq/hoop tag and update the tag in /etc/systemd/system/hoopgateway.service when you choose to upgrade.

Support

cloudimg provides 24/7/365 expert technical support for this image. Contact support@cloudimg.co.uk. Hoop is licensed under the MIT License. This image is provided by cloudimg; additional charges apply for build, maintenance and 24/7 support.