Azimutt on Ubuntu 24.04 on Azure User Guide

Overview

Azimutt is an open source database schema exploration, design and documentation tool. It renders entity relationship diagrams for large, complex schemas, lets you search and navigate across tables, columns and relations, and connect to explore live data across relational and NoSQL databases, all through a modern web interface. The cloudimg image runs Azimutt the officially supported way, as the upstream container alongside its own bundled PostgreSQL metadata database, orchestrated by Docker Compose under systemd and fronted by nginx. Both images are pinned by digest and captured into the VM, so your instance starts in seconds. A unique administrator account, application secret and database password are generated for each VM on first boot, before the port is reachable, and self registration is locked to your own VM so nobody else can claim your instance before you sign in. Backed by 24/7 cloudimg support.

Azimutt is a trademark of its respective owner. This image is produced by cloudimg and is not affiliated with, endorsed by, or sponsored by Azimutt. It ships the free and open source MIT licensed self hosted application, unmodified, and requires no cloud account or licence key.

What is included:

• Azimutt (the MIT licensed self hosted application), pinned by image digest
• A bundled PostgreSQL 16 metadata database, pinned by image digest and reachable only inside a private Docker network (never published to a host port)
• Docker Engine (Docker CE) with Azimutt published to the loopback interface only, fronted by nginx on port 80
• azimutt.service, azimutt-firstboot.service and nginx.service as systemd units, enabled and active on boot
• A unique application secret, database password and administrator account generated per VM on first boot, never baked into the image
• Self registration locked to your own VM by default, so a public appliance cannot be seized by an outside sign up
• 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 for exploring schemas up to a few hundred tables; increase the size for very large schemas or many concurrent users. NSG inbound: allow 22/tcp from your management network and 80/tcp for the web interface. Azimutt serves plain HTTP on port 80; for production, put it behind TLS with your own domain (see the final section).

Step 1 - Deploy from the Azure Marketplace

1. In the Azure portal, choose Create a resource and search the Marketplace for the cloudimg Azimutt offer.
2. Select the plan, then Create.
3. On the Basics tab pick your subscription, resource group and region, name the VM, and select Standard_B2s (or larger).
4. Choose SSH public key authentication with admin username azureuser and provide your public key.
5. On the Networking tab, allow inbound 22/tcp from your management network and 80/tcp for the web interface.
6. Review and create. When the VM is running, note its public IP address.

Step 2 - Deploy from the Azure CLI

az vm create \
  --resource-group my-azimutt-rg \
  --name azimutt \
  --image cloudimg:azimutt:default:latest \
  --size Standard_B2s \
  --admin-username azureuser \
  --generate-ssh-keys \
  --public-ip-sku Standard

# Open the port the web interface needs (SSH is opened by default):
az vm open-port --resource-group my-azimutt-rg --name azimutt --port 80 --priority 900

Step 3 - Connect to your VM

Replace <vm-ip> with your VM's public IP address:

ssh azureuser@<vm-ip>

Step 4 - Confirm the services are running

Azimutt, its own bundled PostgreSQL, and nginx all come up automatically on first boot (first boot also runs the database migrations, which can take up to a minute the very first time). Confirm they are active:

sudo systemctl is-active docker azimutt-firstboot azimutt nginx

Expected output:

active
active
active
active

The stack runs as two containers on a private Docker network. PostgreSQL is never published to a host port; only Azimutt is published, and only to the loopback interface, with nginx in front on port 80:

ss -tln | grep -E ':(80|4000|5432) '

Step 5 - Secure by default: a unique admin and a locked registration path

Self hosted Azimutt has no seeded administrator, and by default anyone who reaches /register can create an account. On a public server that is a risk. The cloudimg image closes it. On first boot, before the port is reachable, a unique administrator account (and its own personal organisation) is created through Azimutt's own sign up code path, with a per VM password. Self registration is then locked: every new account's email must end with a random suffix unique to your VM, a suffix only someone with root access to your instance can read - so an outside visitor cannot register an account and claim your instance.

You can see the whole posture at a glance: a blank or wrong password is rejected, the per VM admin credential is accepted and reaches the authenticated dashboard, an anonymous request is denied, and a registration attempt with a foreign email address is blocked:

sudo /usr/local/sbin/azimutt-roundtrip.sh

Read your unique credentials (the file exists and is root only; its contents are never printed here):

sudo cat /root/azimutt-credentials.txt

The file holds your Azimutt URL, your admin email (ending in the per-VM lock suffix) and your admin password. Keep it safe.

Step 6 - Sign in to Azimutt

Open http://<vm-ip>/ in your browser. You are met with the Azimutt login screen: there is no anonymous access. Sign in with the admin email and the password from the credentials file.

Step 7 - Your organisation and your first project

After signing in you land on your personal organisation, ready to create your first project. Azimutt can start a project from a live database connection, a SQL structure file, a Prisma schema, JSON, or an empty canvas.

Choose From SQL structure and upload a .sql file with your schema (or drag and drop it - everything stays on your machine, nothing is uploaded anywhere else). Azimutt's parser handles most SQL dialects and reports exactly how many tables it found:

Step 8 - Explore the entity relationship diagram

Click Create project!, then Show all tables for an overview layout. Azimutt lays the tables out with their columns, types, primary keys (the key icon) and foreign keys (the linked-arrow icon), and draws the relationship lines between them. Click a coloured column icon to follow a relation, drag tables to rearrange the layout, and use the search bar to jump straight to a table or column in a much larger schema.

From here you can add notes on any table or column, group tables into custom layouts, and (with a live database connection) query and browse real data alongside the diagram. Save the project from the top bar to keep it in your organisation.

Step 9 - Invite your team

Because self registration is locked to your VM's own suffix, add a real teammate by creating their account with an email ending in that same suffix (visible in /root/azimutt-credentials.txt), either the same way the admin account was created or by inviting them from within the app once you are signed in. If you would rather allow open registration for a private, trusted network, edit REQUIRE_EMAIL_ENDS_WITH in /etc/azimutt/azimutt.env and restart the stack with sudo systemctl restart azimutt.

Step 10 - Production: your own domain with TLS

Azimutt serves plain HTTP on port 80. For production, point a DNS record at the VM, put Azimutt behind TLS, and set PHX_HOST in /etc/azimutt/azimutt.env to your domain so links use the right origin. A common approach is to add a certificate to nginx with Certbot:

sudo apt-get install -y certbot python3-certbot-nginx
sudo certbot --nginx -d schema.example.com

Then edit PHX_HOST in /etc/azimutt/azimutt.env to schema.example.com and restart the stack with sudo systemctl restart azimutt. See the Azimutt documentation for the full production checklist.

Support

Every cloudimg image includes 24/7 support. If you have any questions about deploying or operating Azimutt on Azure, contact the cloudimg team through the Azure Marketplace listing or at www.cloudimg.co.uk.