Analytics Azure

Mathesar on Ubuntu 24.04 on Azure User Guide

Last updated: 2026-07-16 | Product: Mathesar on Ubuntu 24.04 LTS on Azure

Overview

This image runs Mathesar 0.12.0, an open source web application that gives your team a friendly, spreadsheet like way to browse, enter and edit the data in a PostgreSQL database, with no SQL required. Users work directly in real tables, build explorations (saved queries) to slice and summarise data, and manage schemas, columns, relationships and constraints from the browser, while everything stays in standard PostgreSQL underneath. A JSON-RPC API exposes the same operations for automation.

cloudimg delivers Mathesar fully installed the native way and reverse proxied behind nginx, with the gunicorn application server and its PostgreSQL 16 internal database already configured and managed by systemd, so a working data workspace is operational within minutes of launch.

What is included:

Mathesar 0.12.0 installed the official native (non Docker) way into /opt/mathesar, running in a self contained Python virtual environment
PostgreSQL 16 as Mathesar's internal metadata database, with its data directory on a dedicated data disk
gunicorn serving the Django application on 127.0.0.1:8000, fronted by nginx on port 80
Three systemd units enabled and active: postgresql@16-main, mathesar and nginx
Secure by default: no administrator account and no shared secret ship in the image. On first boot a unique Django secret key, a unique database password and a unique administrator account are generated and written to a root only file
A dedicated data disk holding the PostgreSQL data directory and uploaded files
A fully patched Ubuntu 24.04 LTS base with unattended security upgrades enabled
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 the recommended size for evaluation and small deployments; for larger datasets choose a size with more memory. NSG inbound: allow 22/tcp from your management network and 80/tcp for the web interface. Mathesar serves plain HTTP on port 80; for production or shared access, terminate TLS in front of it with your own domain (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 Mathesar 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 HTTP (80). Then Review + create then Create.

Step 2 - Deploy from the Azure CLI

az vm create \
  --resource-group <your-rg> \
  --name mathesar \
  --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

# Open the HTTP port so you can reach the web interface
az vm open-port --resource-group <your-rg> --name mathesar --port 80 --priority 900

Step 3 - Retrieve the per VM admin credentials

Nothing secret is baked into the image. On the very first boot, a one shot service (mathesar-firstboot.service) generates a fresh Django secret key, a fresh database password and a unique administrator account, all unique to your instance. It writes them to /root/mathesar-credentials.txt, readable only by root. SSH in as azureuser and read them:

sudo cat /root/mathesar-credentials.txt

# Mathesar - generated on first boot by mathesar-firstboot.service.
# These credentials are unique to THIS VM. Store them somewhere safe.

mathesar.url=http://20.127.70.55/
mathesar.admin.user=admin
mathesar.admin.pass=Rk8vQ2mL9wU4nZ7pB3hD6yX1

# Canonical keys consumed by the cloudimg smoke verifier + guide substitution:
MATHESAR_ADMIN_USER=admin
MATHESAR_ADMIN_PASSWORD=Rk8vQ2mL9wU4nZ7pB3hD6yX1

The mathesar-firstboot.service one shot is ordered before the application services, so the web UI only ever starts once every per VM secret has been generated. The values above are an example; your instance will have its own unique credentials.

The Mathesar first boot service is enabled and its script header describing the per VM secret rotation

Step 4 - Confirm the services are running

Check that PostgreSQL, the Mathesar application and nginx are all active:

sudo systemctl is-active postgresql@16-main mathesar nginx

All three report active. gunicorn binds to loopback only (127.0.0.1:8000) and nginx publishes the interface on port 80:

sudo ss -tlnp | grep -E ':80 |:8000 '

The three Mathesar services reporting active and the listening ports, nginx on 80 and gunicorn on 127.0.0.1:8000

Step 5 - Confirm the web endpoints

The sign in page is public and returns 200. Mathesar requires authentication for everything else, so an anonymous request to the application is redirected to the login page and the JSON-RPC API rejects unauthenticated calls. This is the secure default.

curl -s -o /dev/null -w 'HTTP %{http_code}\n' http://localhost/auth/login/

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

The login page returning 200 and an anonymous request to the application redirected to the login page, the secure default

Step 6 - Sign in to the web UI

Browse to http://<vm-ip>/ and sign in as admin with the password from /root/mathesar-credentials.txt. Mathesar opens on the login page.

The Mathesar sign in page served on port 80

After signing in you land on the Databases home. A freshly deployed instance starts empty; the screenshots in this guide show Mathesar with an example connected database so you can see the interface populated. From here you connect an existing PostgreSQL database or create a new one to start working with your data.

The Mathesar Databases home after signing in, showing a connected database

Step 7 - Work with your data: schemas and tables

Open a database to see its schemas, each holding a set of tables. Mathesar shows the tables, explorations and forms defined in the schema, and lets you create new ones from the browser.

A Mathesar schema view listing its tables and explorations

Open a table to work with its data in the spreadsheet like grid. You can browse, filter, sort, group and edit records directly, follow relationships to related tables, and inspect and change the table's columns and constraints from the Inspector panel, all without writing SQL.

A Mathesar table open in the spreadsheet like data grid, showing real records and the Inspector panel

Step 8 - Use the JSON-RPC API

Mathesar exposes a JSON-RPC API at /api/rpc/v0/ that drives the same operations as the web UI, so you can automate schema and data management. Calls are authenticated with a Django session. The example below signs in, then lists the connected databases:

$ # sign in and keep the session cookie
$ curl -s -c jar.txt http://<vm-ip>/auth/login/ -o /dev/null
$ CSRF=$(awk '/csrftoken/{t=$7} END{print t}' jar.txt)
$ PASS=$(sudo grep '^MATHESAR_ADMIN_PASSWORD=' /root/mathesar-credentials.txt | cut -d= -f2-)
$ curl -s -c jar.txt -b jar.txt -e http://<vm-ip>/auth/login/ \
    --data-urlencode csrfmiddlewaretoken=$CSRF \
    --data-urlencode username=admin \
    --data-urlencode password=$PASS \
    http://<vm-ip>/auth/login/ -o /dev/null

$ # call a JSON-RPC method with the authenticated session
$ curl -s -b jar.txt -H 'Content-Type: application/json' -H "X-CSRFToken: $CSRF" \
    -e http://<vm-ip>/ \
    --data '{"jsonrpc":"2.0","method":"databases.configured.list","params":{},"id":1}' \
    http://<vm-ip>/api/rpc/v0/
connected databases: 1
 - mathesar_demo

The per VM administrator login proves end to end that your credentials work, and an unauthenticated JSON-RPC call is rejected. This is the same round trip the cloudimg image self checks on first boot:

The per VM admin credential round trip verified and an authenticated JSON-RPC call listing the connected database

Step 9 - Enable HTTPS with your own domain

Mathesar ships on plain HTTP on port 80 so it works immediately. For production, point a DNS record at the VM's public IP, add the hostname to ALLOWED_HOSTS in /opt/mathesar/.env, and terminate TLS with a certificate. A common approach is to place Caddy or nginx in front with a certificate from Let's Encrypt, or to put Azure Application Gateway in front of the VM. After editing /opt/mathesar/.env, restart the application:

$ sudo systemctl restart mathesar

Administration and support

The Mathesar application lives in /opt/mathesar, its environment (database connection, secret key and allowed hosts) in /opt/mathesar/.env, and its PostgreSQL data directory and uploaded files on the dedicated data disk at /var/lib/mathesar-data. Manage the service with sudo systemctl restart mathesar. To add another administrator, use the Mathesar admin pages under Settings in the web UI, or the Django management command shipped in the virtual environment.

This image is a repackaged open source software product with additional charges for cloudimg support services. Our engineers provide 24/7 support for deployment, upgrades, TLS termination, connecting your existing PostgreSQL databases, API automation and scaling. Mathesar is a trademark of its respective owner; use of the name here is purely to identify the software this image packages, and this image is not affiliated with or endorsed by the Mathesar project.