Ralph DCIM on Ubuntu 24.04 on Azure User Guide

Overview

Ralph is an open source DCIM (data centre infrastructure management) and asset management system. It models the physical estate the way an operations team actually thinks about it: data centres contain server rooms, server rooms contain racks, and racks contain hardware at specific U positions. Alongside that it tracks back office equipment through its whole lifecycle, plus licences, supports, domains and networks, and exposes all of it through a REST API.

Ralph is built and released by Allegro, Poland's largest e-commerce platform, which uses it to run its own data centre estate. Releases follow a dated cadence; this image ships the 20260902.1 release.

The cloudimg image delivers Ralph on Ubuntu 24.04, served over HTTPS, with an empty database and every secret generated on the first boot of your VM. Backed by 24/7 cloudimg support.

What is included:

• Ralph 20260902.1, run from the official upstream container image pinned by immutable digest, with gunicorn bound to 127.0.0.1:8000 only
• nginx serving the web interface over HTTPS on port 443 with a certificate generated for your VM; port 80 only redirects to HTTPS (plus a plain /healthz for load balancer probes)
• MySQL 8.0 and Redis 7, both from the Ubuntu archive and both on the loopback address only
• A background worker (ralph-rqworker) for Ralph's asynchronous jobs
• Ralph's full schema already migrated, with no data and no accounts — your estate starts empty
• No default login. Ralph's upstream packaging seeds a well-known ralph/ralph administrator; this image never creates it. Your VM generates its own administrator password, database passwords and Django secret key on first boot and writes them to a root-only file
• mysql, redis-server, docker, ralph, ralph-rqworker and nginx systemd services, enabled and active

Ralph is developed by Allegro and distributed under the Apache License 2.0. Ralph and Allegro are trademarks of their respective owners. cloudimg is not affiliated with or endorsed by Allegro; this image packages the unmodified open source software.

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) runs Ralph comfortably for a small estate; choose a larger size for tens of thousands of assets or many concurrent users. Network security group inbound rules: 22/tcp from your management network, 443/tcp for the web interface, and optionally 80/tcp, which only redirects to HTTPS.

Step 1: Deploy from the Azure Marketplace

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

Step 2: Deploy from the Azure CLI

Replace the placeholders with your own resource group, VM name and region.

az vm create \
  --resource-group my-resource-group \
  --name ralph-01 \
  --image cloudimg:ralph-ubuntu-24-04:default:latest \
  --size Standard_B2s \
  --admin-username azureuser \
  --generate-ssh-keys \
  --public-ip-sku Standard
az vm open-port --resource-group my-resource-group --name ralph-01 --port 443 --priority 1001

Step 3: Wait for first boot to finish

The first boot generates this VM's secrets, applies the database schema and creates your administrator account before the web interface is allowed to serve anything. It normally takes under a minute. Confirm it has finished:

sudo systemctl is-active ralph-firstboot.service
sudo test -f /var/lib/cloudimg/ralph-firstboot.done && echo "first boot complete"

Then confirm the whole stack is running. ralph is the application container, ralph-rqworker its background worker:

sudo systemctl is-active mysql redis-server docker ralph ralph-rqworker nginx

The image is pinned to an exact upstream digest rather than a floating tag, so every VM from this image runs byte-identical application code:

cat /etc/ralph/image-digest

Step 4: Retrieve your administrator password

Every VM generates its own credentials on first boot. They are written to /root/ralph-credentials.txt, readable only by root:

sudo stat -c '%a %U:%G %n' /root/ralph-credentials.txt
sudo cat /root/ralph-credentials.txt

The file contains your web address, the administrator username and password, the Ralph database credentials and the MySQL root password.

To read just the administrator login:

sudo grep -E '^RALPH_(URL|ADMIN_USER)=' /root/ralph-credentials.txt

Store the password in your own secret manager. Then sign in at https://<vm-public-ip>/ — the browser will warn about the self-signed certificate until you add your own in Step 9.

Step 5: Confirm the network surface

Only SSH and the two web ports are reachable from outside the VM. MySQL (3306), Redis (6379) and gunicorn (8000) are bound to the loopback address and cannot be reached from the network:

sudo ss -H -lnt | awk '{print $4}' | sort -u
curl -s -o /dev/null -w '%{http_code} -> %{redirect_url}\n' http://127.0.0.1/

Every address in that list other than 0.0.0.0:22, 0.0.0.0:80 and 0.0.0.0:443 is a loopback address. Alongside the three application services you will also see 127.0.0.53 and 127.0.0.54 on port 53, which are the system resolver, and one high-numbered 127.0.0.1 port belonging to containerd, which changes on every boot. None of them is reachable from outside the VM.

Port 80 answers only with a redirect to HTTPS, plus an unauthenticated /healthz endpoint for load balancer probes:

curl -s http://127.0.0.1/healthz

Step 6: Verify the deployment

The image ships a self-test that signs in through nginx with your VM's own administrator password, exactly as a browser does, and then proves that a wrong password and an anonymous request are both refused:

sudo /usr/local/sbin/ralph-selftest.sh

You can also check that Ralph's own published default account does not exist on your VM — it never does, because this image creates only your per-VM administrator:

sudo /usr/local/sbin/ralph-mysql -N -B -e \
  "SELECT COUNT(*) AS default_account_count FROM ralph_ng.accounts_ralphuser WHERE username='ralph'"

Step 7: Model your estate

Sign in at https://<vm-public-ip>/ with the username and password from Step 4. Ralph opens on a dashboard summarising your estate; it is empty on a new VM and fills in as you add hardware.

Build the physical hierarchy from the top down, using the Data Center menu:

1. Data Center — create one entry per site.
2. Server Room — create the rooms inside each data centre.
3. Rack — create racks inside each server room, setting the rack's height in U.
4. Data Center Asset — add hardware, choosing its model, status, service environment, rack and U position.

Assets are listed with their full physical path, so you can always see which data centre, server room, rack and U position a machine occupies:

Filtering the asset list by rack gives you that rack's contents — the inventory view an engineer needs before visiting the floor:

The Back Office menu tracks non-rack equipment (laptops, phones, monitors) through the same lifecycle, and Licenses, Supports and Domains attach contracts and entitlements to the assets they cover.

Step 8: Use the REST API

Ralph exposes its whole data model over a REST API, which is how most teams load an existing estate in bulk and keep it in sync. Authenticate with an API token, which you create in the web interface under your username, then My API token.

The API root lists every available endpoint:

curl -s -k https://127.0.0.1/api/ -H 'Accept: application/json' | head -c 400

With a token, list your data centre assets. Replace <your-api-token> with the token you generated:

curl -s -k https://127.0.0.1/api/data-center-assets/ \
  -H 'Authorization: Token <your-api-token>' \
  -H 'Accept: application/json' | head -c 400

The same API accepts POST to create assets and PATCH to update them, so an existing CMDB export can be loaded with a short script.

Step 9: Add your own DNS name and certificate

The image generates a self-signed certificate for your VM's addresses. For production, point a DNS name at the VM and install a real certificate.

Ralph validates the Host header of every request, so first add your DNS name to the allowed hosts and trusted origins. Edit /etc/ralph/conf.d/cloudimg.conf and append your name to both RALPH_ALLOWED_HOSTS and RALPH_CSRF_TRUSTED_ORIGINS (the latter needs the https:// scheme), then restart:

sudo sed -i 's#^RALPH_ALLOWED_HOSTS="\(.*\)"#RALPH_ALLOWED_HOSTS="\1,ralph.example.com"#' /etc/ralph/conf.d/cloudimg.conf
sudo sed -i 's#^RALPH_CSRF_TRUSTED_ORIGINS="\(.*\)"#RALPH_CSRF_TRUSTED_ORIGINS="\1,https://ralph.example.com"#' /etc/ralph/conf.d/cloudimg.conf
sudo systemctl restart ralph.service

Then obtain a certificate. With the DNS name resolving to the VM and port 80 reachable:

sudo apt-get update && sudo apt-get install -y certbot python3-certbot-nginx
sudo certbot --nginx -d ralph.example.com

Certbot updates the nginx server block and installs a renewal timer.

Step 10: Back up and restore

Everything you enter lives in the MySQL database, plus any uploaded files under /var/lib/ralph/media. Back up both.

sudo mysqldump --defaults-file=/etc/mysql/debian.cnf --single-transaction ralph_ng \
  | sudo tee /var/backups/ralph-$(date +%F).sql > /dev/null
sudo tar czf /var/backups/ralph-media-$(date +%F).tar.gz -C /var/lib/ralph media
sudo ls -la /var/backups/

/etc/mysql/debian.cnf holds this VM's own maintenance credential, so a scheduled dump needs no password in the crontab.

Restore by loading the dump back into an empty database and restarting the application:

sudo /usr/local/sbin/ralph-mysql -e "DROP DATABASE ralph_ng; CREATE DATABASE ralph_ng CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"
sudo /usr/local/sbin/ralph-mysql ralph_ng < <backup-dir>/ralph-2026-09-20.sql
sudo systemctl restart ralph.service ralph-rqworker.service </dev/null

This replaces the whole database, so run it only against a VM you intend to overwrite.

Step 11: Keep the VM patched

Ubuntu security updates are applied automatically by unattended-upgrades. Check for pending updates at any time:

sudo apt-get update && apt-get -s dist-upgrade | grep -c '^Inst ' || true

To move to a newer Ralph release, pull the new upstream image, repin the digest, apply any new migrations and restart. Replace the tag with the release you want:

sudo docker pull allegro/ralph:<version>
sudo docker image inspect allegro/ralph:<version> --format '{{index .RepoDigests 0}}' | sudo tee /etc/ralph/image-digest
sudo /usr/local/sbin/ralph-manage migrate --noinput
sudo systemctl restart ralph.service ralph-rqworker.service </dev/null

Take a backup (Step 10) before upgrading, and read the upstream release notes for the versions you are skipping.

Troubleshooting

The web interface does not answer. Check that first boot finished and the stack is up:

sudo systemctl is-active ralph-firstboot.service ralph nginx
sudo journalctl -u ralph-firstboot.service --no-pager | tail -20

nginx, ralph and ralph-rqworker deliberately refuse to start until first boot has generated this VM's secrets, so all three staying inactive normally means first boot failed. The log above will say why.

The application log. Ralph logs to the journal and to /var/log/ralph:

sudo journalctl -u ralph.service --no-pager | tail -20

A browser reports a CSRF or "Host" error after adding a DNS name. The name is missing from RALPH_ALLOWED_HOSTS or RALPH_CSRF_TRUSTED_ORIGINS; revisit Step 9 and restart ralph.service.

You lost the administrator password. Set a new one directly:

# prompts twice for <new-password>, then updates the account in place
sudo /usr/local/sbin/ralph-manage changepassword ralph_admin

Support

cloudimg provides 24/7 support for this image. Include the output of sudo systemctl is-active mysql redis-server docker ralph ralph-rqworker nginx and cat /etc/ralph/image-digest with any request.