StarRocks on Ubuntu 24.04 on Azure User Guide

Overview

StarRocks is an open-source, massively parallel processing (MPP) analytical database built to answer aggregations, joins and group-by queries over very large tables in well under a second. It combines a vectorised execution engine, a cost-based optimiser and columnar storage, and it speaks the MySQL network protocol - so existing MySQL clients, drivers, BI tools and dashboards connect to it unchanged and familiar SQL works as written.

A StarRocks deployment has two cooperating roles. The Frontend (FE) parses SQL, plans queries and owns the cluster metadata. The Backend (BE) stores the data and executes the query fragments the FE hands it. As well as its own native tables, StarRocks can query data in place through external catalogs for Hive, Iceberg and Paimon.

The cloudimg image installs StarRocks 3.5.19 from the official upstream release archive, SHA-256 verified during the build, and runs it as a ready-to-use single-node all-in-one deployment: one FE and one BE on the same VM, both managed by systemd and restarted on failure. Backed by 24/7 cloudimg support.

What is included:

• StarRocks 3.5.19 (Apache-2.0), installed from the official upstream release archive and SHA-256 verified
• A single-node FE + BE deployment run by systemd, serving the MySQL protocol on port 9030
• A unique per-VM root password generated on first boot, established before the database is reachable from any network interface
• The internal FE and BE control ports restricted to the loopback interface by a host firewall applied on every boot
• Database storage on a dedicated 64 GiB Azure data disk at /var/lib/starrocks
• Frontend heap and Backend memory limits that adapt automatically to the size of the VM you run
• 24/7 cloudimg support

This is a database product. StarRocks serves the MySQL protocol on port 9030, but the Azure NSG opens port 22 only. The database port is not exposed to the internet by default - reach it over an SSH tunnel, or open it in your own NSG for trusted networks.

A note on the root account

Upstream StarRocks ships its built-in root account with no password at all. Unlike products that ship a published default string, there is nothing to rotate - the account is simply unauthenticated until a password is set.

This image never exposes that state. The database store is empty in the image, so your first boot is a genuine bootstrap, and the per-VM password is set inside a firewall window that keeps port 9030 unreachable from every network interface until the password is proven live. First boot deliberately stops the database rather than completing if the empty password would still be accepted. You can verify this yourself in Step 7.

A note on the Oracle external catalog

Upstream StarRocks bundles two Oracle-proprietary JDBC jars (ojdbc10 and orai18n) which are licensed under Oracle's own terms rather than an open-source licence. cloudimg removes both jars at build time, so this image carries no conditionally licensed component and is fully open-source licensed.

The practical consequence, stated plainly: the Oracle external catalog connector is not available on this image. Those two jars back that connector and nothing else. Everything else is unaffected - the MySQL protocol, native StarRocks tables, and the Hive, Iceberg and Paimon external catalogs all work normally. If you specifically need to query an Oracle database through a StarRocks external catalog, this image is not the right fit.

Prerequisites

An active Azure subscription, an SSH key pair, and a VNet + subnet in the target region. Standard_D4s_v5 (4 vCPU / 16 GiB RAM) is the recommended starting size - see Sizing for the reasoning and the measured figures. NSG inbound: allow 22/tcp from your management network. No inbound application ports are needed because the database is reached over the SSH tunnel.

Have a MySQL command-line client on the machine you connect from. StarRocks implements the mysql_native_password authentication plugin, so use a MySQL 8.0.30+ client or a MariaDB client. MySQL 9.0 and later clients removed that plugin and cannot connect - on macOS in particular, prefer mariadb-client over a 9.x mysql-client.

Step 1 - Deploy from the Azure Marketplace

Sign in to the Azure Portal, choose Create a resource, search the Marketplace for StarRocks by cloudimg, and select Create. On Basics pick your subscription, resource group, region and size (Standard_D4s_v5 or larger); under Administrator account choose SSH public key and paste your key; under Inbound port rules allow SSH (22) only. Then Review + create -> Create.

First boot initialisation generates your per-VM root password, starts the Frontend and Backend, registers the Backend with the Frontend and verifies the cluster actually answers a query. Allow a minute or so after the VM is running before the database accepts connections.

Step 2 - Deploy from the Azure CLI

az vm create \
  --resource-group <your-rg> \
  --name starrocks \
  --image <marketplace-image-urn> \
  --size Standard_D4s_v5 \
  --admin-username azureuser \
  --ssh-key-values ~/.ssh/id_ed25519.pub \
  --vnet-name <your-vnet> --subnet <your-subnet> \
  --public-ip-sku Standard

Step 3 - Connect to your VM

ssh azureuser@<vm-public-ip>

A welcome banner prints the most useful commands. StarRocks runs as two system services, starrocks-fe and starrocks-be.

Step 4 - Confirm the database is running

systemctl is-active starrocks-fe starrocks-be

Both services should report active:

active
active

The dedicated data disk holds the Frontend metadata and all Backend tablet data at /var/lib/starrocks:

df -h /var/lib/starrocks | tail -1

/dev/sdc         63G   80M   60G   1% /var/lib/starrocks

Step 5 - Retrieve your per-VM database password

The password is generated uniquely on this VM's first boot and written to a root-only file:

sudo cat /root/starrocks-credentials.txt

# StarRocks 3.5.19 — generated on first boot by starrocks-firstboot.service
# These credentials are unique to this VM. Store them somewhere safe.

starrocks.host=<your-vm-ip>
starrocks.port=9030
starrocks.root.user=root
starrocks.root.password=<your-unique-password>

The file is readable only by root:

ls -l /root/starrocks-credentials.txt

-rw------- 1 root root 831 Jul 20 08:33 /root/starrocks-credentials.txt

Step 6 - Connect and run SQL

Connect with any MySQL client. On the VM itself:

mysql -h 127.0.0.1 -P 9030 -uroot -p

Confirm the version:

mysql> SELECT current_version();

current_version()
3.5.19-7dd233e

Create a table, insert rows and query them back. StarRocks requires a distribution key on CREATE TABLE; on a single-node image set replication_num to 1:

CREATE DATABASE IF NOT EXISTS demo;
USE demo;
CREATE TABLE events (id INT, name VARCHAR(64), amount INT)
  DUPLICATE KEY(id)
  DISTRIBUTED BY HASH(id) BUCKETS 3
  PROPERTIES('replication_num'='1');
INSERT INTO events VALUES (1,'signup',100),(2,'purchase',250),(3,'signup',75);
SELECT * FROM demo.events ORDER BY id;

id  name    amount
1   signup  100
2   purchase    250
3   signup  75

An aggregate, which is the work StarRocks exists to do quickly:

SELECT name, COUNT(*) AS n, SUM(amount) AS total
FROM demo.events GROUP BY name ORDER BY total DESC;

name    n   total
purchase    1   250
signup  2   175

Step 7 - Verify the security posture

Confirm the empty password that upstream ships with is refused on your VM:

mysql -h 127.0.0.1 -P 9030 -uroot -e 'SELECT 1' >/dev/null 2>&1 \
  && echo "ACCEPTED - INSECURE, contact support" \
  || echo "REJECTED - correct, the empty password does not authenticate"

REJECTED - correct, the empty password does not authenticate

Run without the guard, the same connection prints the server's own refusal:

ERROR 1045 (28000): Access denied for user 'root' (using password: NO)

Confirm the two Oracle-proprietary jars are absent, and that the check is being made against a populated directory rather than an empty one:

ls /opt/starrocks/fe/lib/ | grep -icE 'ojdbc|orai18n'; ls /opt/starrocks/fe/lib/*.jar | wc -l

0
605

Zero Oracle jars, out of 605 jars present.

The internal Frontend and Backend ports are restricted to the loopback interface by a host firewall that is reapplied on every boot. Only port 9030 is serviceable from off the VM:

sudo iptables -S STARROCKS_LOCAL | head -3

-N STARROCKS_LOCAL
-A STARROCKS_LOCAL ! -i lo -p tcp -m tcp --dport 8030 -j DROP
-A STARROCKS_LOCAL ! -i lo -p tcp -m tcp --dport 9020 -j DROP

Step 8 - Reach the database from your workstation

The NSG opens port 22 only, so the database is not reachable from the internet. Forward the port over SSH:

ssh -L 9030:127.0.0.1:9030 azureuser@<vm-public-ip>

Then, from another terminal on your workstation:

mysql -h 127.0.0.1 -P 9030 -uroot -p

To connect BI tools directly instead, add an inbound NSG rule allowing 9030/tcp from your trusted network ranges only - never 0.0.0.0/0.

Sizing

The image adapts to the VM you run it on. The Frontend heap is computed at start time as 25% of total RAM (floor 1024 MiB) and the Backend memory limit is 70% of total RAM, so the same image is correctly proportioned on any size.

Measured on a 2 vCPU / 3916 MiB build VM after a full first boot, a service restart and an 81,920-row load:

State	Frontend (Java) RSS	Backend RSS	System memory used
Idle	412 MiB	383 MiB	1181 MiB
Under query load	437 MiB	412 MiB	1234 MiB

Those figures are the floor, not a recommendation. They come from a trivial dataset; StarRocks is an MPP analytical engine whose working set grows with the volume of data each query scans, and upstream guidance is 16 GiB or more per node.

Standard_D4s_v5 (4 vCPU / 16 GiB) is recommended for two reasons:

• Memory. On 16 GiB the Frontend receives a 4 GiB heap and the Backend an 11 GiB ceiling, which is real headroom for analytical scans rather than the bare minimum to start.
• CPU class. Analytical queries are sustained CPU work, which is precisely the workload a burstable B-series VM handles worst: burst credits deplete under continuous load and the node's performance collapses under exactly the queries the product exists to serve. D4s_v5 is non-burstable, so query performance stays predictable.

If your workload is light and intermittent, a burstable size will run correctly - the image is proven to boot and serve queries on 2 vCPU / 4 GiB - but size up before putting sustained analytical load on it.

Service management

systemctl status starrocks-fe starrocks-be

Restart the cluster (restart the Backend first, then the Frontend):

sudo systemctl restart starrocks-be
sudo systemctl restart starrocks-fe

Logs:

sudo journalctl -u starrocks-fe -f
sudo journalctl -u starrocks-be -f

StarRocks also writes its own logs under /opt/starrocks/fe/log and /opt/starrocks/be/log.

Troubleshooting

Queries return no rows, or hang, although CREATE TABLE succeeded. This is the classic single-node symptom of a Frontend that is up while the Backend is not serving. The Frontend accepts connections and answers DDL on its own, so a connection test alone will not reveal it. Check the Backend is genuinely alive:

mysql -h 127.0.0.1 -P 9030 -uroot -p -e "SHOW BACKENDS\G"

Read the Alive field specifically - the output contains several boolean columns and only Alive indicates the Backend is serving. If it is false, check systemctl status starrocks-be and the Backend log.

ERROR 1045 Access denied. Re-read the password from /root/starrocks-credentials.txt. It is unique to this VM and is not recoverable from anywhere else.

Client cannot authenticate at all. Your client is likely MySQL 9.0 or later, which removed the mysql_native_password plugin. Use a MariaDB client or a MySQL 8.0.30+ client.

The database did not come up on first boot. First boot fails closed on purpose: if the per-VM password could not be established it stops the database rather than leaving it reachable without one. Check sudo journalctl -u starrocks-firstboot.

Support

cloudimg provides 24/7 support with a guaranteed 24-hour response. Contact support@cloudimg.co.uk.