RackPeek on Ubuntu 24.04 on Azure User Guide

Overview

RackPeek gives you one place to document and manage your home lab and small-scale IT infrastructure as code: the racks and devices you run, servers and their CPUs, drives, GPUs and network cards, switches, routers, firewalls, access points and UPS units, the networks they sit on and the cables that connect them. Everything is stored in a single human-readable YAML file, so your estate is documented as code you can read, diff and version, and RackPeek turns that source of truth into physical and logical topology diagrams, Ansible inventories, SSH configs and hosts files.

RackPeek has no built-in authentication of its own, so the cloudimg image never exposes it directly. RackPeek runs as a container bound to the loopback connector 127.0.0.1:8080, and the only public listener is an nginx reverse proxy that terminates TLS and requires an HTTP Basic-auth password. Both the certificate and the password are generated uniquely on the first boot of every VM, so there is no default login and no two machines share a credential. The image also ships with a small worked example estate already loaded, so you can see real content the moment you sign in. Backed by 24/7 cloudimg support.

What is included:

• RackPeek 2.0.0 running as a container managed by Docker (pinned by image digest)
• Docker CE preinstalled from the official Docker apt repository
• The RackPeek web UI on :443 (TLS), fronted by nginx, with :80 redirecting to :443
• An nginx HTTP Basic-auth front door; RackPeek itself is published to the loopback interface only
• A per-VM TLS certificate and a per-VM Basic-auth password generated on first boot and recorded in a root-only file (username admin)
• A seeded example estate (two servers, a switch, a router, a firewall and an access point, with a real cable connection) so the UI shows real content immediately
• The bundled rpk command-line tool for automation and batch edits
• docker.service + nginx.service as systemd units, enabled and active
• An unauthenticated /healthz endpoint for Azure Load Balancer health probes
• 24/7 cloudimg support

Prerequisites

An active Azure subscription, an SSH key pair, and a VNet + subnet in the target region. Standard_B2s (2 vCPU / 4 GiB RAM) is a comfortable starting point. NSG inbound: allow 22/tcp from your management network and 443/tcp for the web UI (and 80/tcp if you want the automatic redirect to HTTPS). The web UI reveals your infrastructure layout, so restrict 443/tcp to trusted networks.

Step 1 - Deploy from the Azure Marketplace

Sign in to the Azure Portal, choose Create a resource, search the Marketplace for RackPeek 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), HTTPS (443) and HTTP (80). Then Review + create -> Create.

Step 2 - Deploy from the Azure CLI

az vm create \
  --resource-group <your-rg> \
  --name rackpeek \
  --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 rackpeek --port 80 --priority 1010
az vm open-port --resource-group <your-rg> --name rackpeek --port 443 --priority 1020

Step 3 - Connect to your VM

ssh azureuser@<vm-public-ip>

Step 4 - Confirm the services are running

systemctl is-active docker nginx
sudo docker ps --format 'table {{.Names}}\t{{.Status}}\t{{.Ports}}'
sudo ss -ltn | grep -E ':80 |:443 |:8080 '

Both services report active. Docker runs the rackpeek container bound to the loopback connector 127.0.0.1:8080; nginx owns the public ports 80 and 443. Note that 8080 is only ever bound to 127.0.0.1 - RackPeek is never reachable directly from the network.

Step 5 - Retrieve your web credentials

The Basic-auth password is generated uniquely on the first boot of your VM and written to a root-only file:

sudo cat /root/rackpeek-credentials.txt

This file contains RACKPEEK_USERNAME (always admin), RACKPEEK_PASSWORD and the URL to open. Store the password somewhere safe.

Step 6 - Confirm the health endpoint

nginx serves an unauthenticated health endpoint for load balancers and probes:

curl -k -s https://localhost/healthz

It returns ok. This endpoint never requires authentication, so it is safe for an Azure Load Balancer health probe. Everything else on :443 is behind Basic auth.

Step 7 - Understand the security posture

RackPeek has no login of its own, so the cloudimg image protects it at the front door instead of exposing an open management UI. RackPeek is published to the loopback interface only, and the single public entry point is nginx with TLS + Basic auth. Anonymous requests and the guessable default admin/admin are refused; only the per-VM password works. The command below reads your unique password from the credentials file, so you never have to type it:

PW=$(sudo grep '^RACKPEEK_PASSWORD=' /root/rackpeek-credentials.txt | cut -d= -f2-)
echo "anonymous        -> HTTP $(curl -k -s -o /dev/null -w '%{http_code}' https://localhost/)"
echo "default admin    -> HTTP $(curl -k -s -o /dev/null -w '%{http_code}' -u admin:admin https://localhost/)"
echo "per-VM password  -> HTTP $(curl -k -s -o /dev/null -w '%{http_code}' -u "admin:$PW" https://localhost/)"

Anonymous and admin/admin both return 401; only the per-VM password returns 200.

Step 8 - Sign in to the web UI

Browse to https://<vm-public-ip>/. Because the certificate is a per-VM self-signed certificate, your browser will warn about it the first time - accept the warning to continue (or install your own certificate, see Maintenance). Your browser then prompts for a username and password: enter admin and the password from Step 5.

The home page opens on a dashboard showing your totals and the physical topology of the seeded example estate - six devices with a real cable link between the NAS and the core switch.

Step 9 - Explore the inventory

Open Hardware or a device list such as Servers to see each device in detail. The seeded nas-01 server shows its CPU, an SSD and a four-port NIC; use Add Server and the + controls to record your own hardware.

Step 10 - Visualise the topology

Open Visualise for an auto-generated physical topology diagram (there is also a logical view). You can export the diagram as a PNG or as Mermaid to embed in your own documentation.

Step 11 - Edit the estate as YAML

RackPeek stores everything in one YAML file. Open Yaml to see the raw configuration, edit it in place, or import a file. This is your documentation-as-code source of truth, and it is what the CLI and exporters read.

Step 12 - Use the bundled rpk CLI

RackPeek ships a command-line tool, rpk, inside the container for automation and batch edits. Read the current inventory:

sudo docker exec rackpeek rpk servers summary
sudo docker exec rackpeek rpk switches summary

To add your own hardware from the CLI (this mutates the estate, so it is shown here for reference):

sudo docker exec rackpeek rpk servers add app-01
sudo docker exec rackpeek rpk servers cpu add app-01 --model "EPYC 7402" --cores 24 --threads 48
sudo docker exec rackpeek rpk servers nic add app-01 --type sfp+ --speed 25 --ports 2
sudo docker exec rackpeek rpk switches port add core-sw-01 --type sfp+ --speed 25 --count 4
sudo docker exec rackpeek rpk connections add app-01 0 0 core-sw-01 1 0
sudo docker exec rackpeek rpk --help          # full command reference

Maintenance

• Password: the Basic-auth password is set on first boot and stored in /root/rackpeek-credentials.txt. To rotate it, run sudo htpasswd -b /etc/nginx/.rackpeek-htpasswd admin '<new-password>' and update your record of it.
• TLS certificate: the image generates a per-VM self-signed certificate at /etc/nginx/ssl/. For production, replace it with a certificate for your own domain (for example one issued by your CA) and reload nginx, so browsers trust it without a warning.
• Backups: your entire estate is the single file /var/lib/rackpeek/config/config.yaml. Copy it somewhere safe (or keep it in version control) to back up your documentation.
• Upgrades: RackPeek runs from the pinned aptacode/rackpeek:v2.0.0 image (referenced by digest). To upgrade, pull a newer tag, sudo docker rm -f rackpeek and re-run it with the same -p 127.0.0.1:8080:8080 -v /var/lib/rackpeek/config:/app/config options; your YAML estate is preserved on the host volume.
• Security patches: unattended-upgrades remains enabled so the OS continues to receive security updates automatically.

Support

cloudimg provides 24/7 expert support for this image. Contact support@cloudimg.co.uk.