Mage AI on Ubuntu 24.04 on Azure User Guide

Overview

Mage AI is an open-source data pipeline tool for transforming and integrating data — a modern, developer-friendly alternative to Apache Airflow. Instead of writing DAGs by hand, you build pipelines from composable blocks (data loaders, transformers and exporters) in a visual, notebook-style editor with live output previews, then schedule them with built-in triggers. The cloudimg image installs Mage AI 0.9.79 into a Python virtualenv at /opt/mage/venv, runs it in standalone mode as a dedicated mage system user, binds the web UI to loopback behind an nginx reverse proxy on TCP 80 with HTTP Basic auth, persists the Mage project and all pipeline data on a dedicated Azure data disk, and generates a unique web password on the first boot of every VM. Backed by 24/7 cloudimg support.

What is included:

• Mage AI 0.9.79 in a Python virtualenv at /opt/mage/venv, run by the mage system user
• The visual pipeline editor and scheduler UI, fronted by nginx on :80
• nginx HTTP Basic auth (Mage's web UI has no built-in authentication by default) with a per-VM password in a root-only file
• WebSocket pass-through in nginx so the live editor and pipeline run output stream correctly
• A dedicated Azure data disk at /var/lib/mage holding the Mage project and all pipeline metadata — separate from the OS disk and re-provisioned with every VM
• mage.service + nginx.service as systemd units, enabled and active
• 24/7 cloudimg support

Prerequisites

An active Azure subscription, an SSH key pair, and a VNet + subnet in the target region. Standard_B2ms (2 vCPU / 8 GiB RAM) is a good starting point; scale up for heavier pipelines and concurrent runs. NSG inbound: allow 22/tcp from your management network and 80/tcp for the web UI (front with TLS for public exposure — see Enabling HTTPS).

Step 1 — Deploy from the Azure Marketplace

Sign in to the Azure Portal, choose Create a resource, search the Marketplace for Mage AI 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). Review the dedicated data disk on the Disks tab, then Review + create → Create.

Step 2 — Deploy from the Azure CLI

az vm create \
  --resource-group <your-rg> \
  --name mage-ai \
  --image <marketplace-image-urn> \
  --size Standard_B2ms \
  --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 mage-ai --port 80 --priority 1010

Step 3 — Connect to your VM

ssh azureuser@<vm-public-ip>

Step 4 — Confirm the services are running

systemctl is-active mage.service nginx.service

Both services report active. Mage starts its web server and scheduler in standalone mode and is ready to build pipelines.

Step 5 — Retrieve your web password

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

sudo cat /root/mage-ai-credentials.txt

This file contains mage.admin.user (admin) and mage.admin.pass, plus the URL for the web UI. Store the password somewhere safe.

Step 6 — Check the health endpoint

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

curl -s http://localhost/health

It returns ok.

Step 7 — Open the visual pipeline editor

Browse to http://<vm-public-ip>/ and sign in with the browser's HTTP Basic auth prompt as admin with the password from Step 5. Mage opens on the Pipelines dashboard, which lists every pipeline in the project and lets you create a new one with + New.

Opening a pipeline shows the notebook-style editor: each block (loader, transformer, exporter) is a cell with its own code and live output, and the block tree on the right shows how the blocks are wired together:

A data loader or transformer block holds Python (or SQL/R) code with an @data_loader / @transformer decorator; run the block to preview its output inline before wiring it into the pipeline:

The Triggers / Runs view schedules the pipeline and lists every run with its status, so you can monitor and re-run executions:

Step 8 — Confirm the API behind the auth wall

The Mage web server answers behind the same Basic auth. From the VM, a request without credentials is rejected and a request with the per-VM password is accepted:

curl -s -o /dev/null -w 'no-auth: %{http_code}\n' http://localhost/
curl -s -o /dev/null -w 'with-auth: %{http_code}\n' -u admin:<MAGE_ADMIN_PASSWORD> http://localhost/

The first prints 401; the second prints 200. This is the proof that nginx is enforcing authentication in front of Mage's auth-less web server.

Step 9 — Create your first pipeline

In the UI, click + New → Standard (batch) to scaffold a pipeline, then + Data loader → Python → API/Base template to add a loader block. Edit the block's @data_loader function, click the block's run button to preview the output, then add a Transformer block downstream and wire it in. Mage saves the pipeline definition to the project on the data disk automatically.

Step 10 — Inspect the project on the data disk

The Mage project (pipelines, blocks, metadata.yaml) lives under the data dir as the mage user:

sudo ls /var/lib/mage/default_repo

You see metadata.yaml, pipelines/, data_loaders/, transformers/ and data_exporters/ — the project Mage reads and writes as you build.

Step 11 — Confirm data lives on the dedicated disk

The Mage project and all pipeline data are stored on the dedicated Azure data disk so they survive OS changes and can be resized independently:

findmnt /var/lib/mage

The mount is backed by a separate Azure data disk captured into the image and re-provisioned on every VM.

Enabling HTTPS

The nginx reverse proxy terminates plain HTTP on port 80. For public exposure, put a certificate in front of it. The simplest path is to add a DNS name for the VM and use the companion cloudimg nginx-ssl-certbot image as a TLS reverse proxy, or install certbot and extend the existing nginx site with a listen 443 ssl; server block and your certificate paths. Keep Mage itself bound to loopback so the only public surface is the authenticated, TLS-terminated proxy. The existing nginx site already passes the WebSocket upgrade headers Mage needs, so the live editor keeps working over TLS.

Maintenance

• Configuration: the listener host/port and project path are set in /etc/default/mage. Edit it and sudo systemctl restart mage to apply changes.
• Backups: snapshot the /var/lib/mage data disk, or copy the default_repo project tree to Azure Blob Storage.
• Upgrades: activate the virtualenv (source /opt/mage/venv/bin/activate) and pip install --upgrade mage-ai, then sudo systemctl restart mage.
• 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.

Mage is a trademark of Mage Technologies, Inc. This image is produced by cloudimg and is not affiliated with or endorsed by the Mage project. Mage AI is distributed under the Apache License 2.0.