openGauss on Ubuntu 24.04 on Azure User Guide

Overview

openGauss is an enterprise-grade open-source relational database built on PostgreSQL foundations and hardened by Huawei for demanding transactional workloads. It provides standard SQL, ACID transactions, multi-version concurrency control and the mature relational model teams already know, in a database engineered for reliability and consistent performance under load.

The cloudimg image runs openGauss 5.0.0 as a ready-to-use standalone single-node deployment from the official upstream opengauss/opengauss container image, managed by systemd and restarted on failure. The database is licensed under the Mulan PSL v2, an OSI-approved permissive licence. Backed by 24/7 cloudimg support.

What is included:

• openGauss 5.0.0 (Mulan PSL v2), run from the official upstream container image
• A standalone single-node deployment managed by systemd, listening on port 5432
• A unique per-VM password for each built-in superuser, generated on first boot, with no fixed default credential ever present in the image
• Database storage on a dedicated 40 GiB Azure data disk at /var/lib/opengauss
• A fully patched Ubuntu 24.04 base with unattended security upgrades enabled
• 24/7 cloudimg support

This is a database product. openGauss serves its PostgreSQL-derived wire protocol on port 5432, 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 default credentials

The upstream openGauss image seeds two built-in superuser accounts, gaussdb (the documented default user) and opengauss (the initial account). This image never ships a fixed password for either. The database store is empty in the image, and on first boot the catalogue is created with a password generated uniquely for your VM, so no fixed default ever exists on your instance. Each superuser receives its own distinct per-VM secret, and first boot deliberately fails rather than completing if any built-in account would still accept an empty or a wrong password.

A note on the client

openGauss speaks a PostgreSQL-derived wire protocol but uses openGauss's own SHA256 authentication handshake, so a stock psql/libpq client cannot authenticate against it. Use gsql, the client bundled inside the openGauss container, which every command in this guide runs via sudo docker exec.

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 the recommended starting size, which gives an enterprise RDBMS real headroom. NSG inbound: allow 22/tcp from your management network. No inbound application ports are needed because the database is reached over the SSH tunnel.

Step 1 — Deploy from the Azure Marketplace

Sign in to the Azure Portal, choose Create a resource, search the Marketplace for openGauss by cloudimg, and select Create. On Basics pick your subscription, resource group, region and size (Standard_B2ms 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 database passwords, starts openGauss and bootstraps the catalogue with those passwords. Allow a minute or so after the VM is running before the database accepts queries.

Step 2 — Deploy from the Azure CLI

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

Step 3 — Connect to your VM

ssh azureuser@<vm-public-ip>

A welcome banner prints the most useful commands. openGauss runs as the system service opengauss, which manages the database container.

Step 4 — Confirm the database is running

sudo systemctl is-active opengauss docker

You should see both services active:

active
active

The dedicated data disk holds the container's storage — the database volume and the openGauss image — at /var/lib/opengauss:

findmnt -no SOURCE,TARGET,FSTYPE,SIZE /var/lib/opengauss

/dev/sda /var/lib/opengauss ext4   39.1G

Step 5 — Retrieve your per-VM database passwords

Each VM generates its own unique passwords on first boot and writes them to a root-only credentials file:

sudo cat /root/opengauss-credentials.txt

The file lists the host and port, the gaussdb superuser and its generated password, and the opengauss superuser and its own separate generated password. It is mode 0600 and owned by root. Store the passwords in your secrets manager. In the commands below, <GAUSSDB_PASSWORD> stands for the value of opengauss.gaussdb.password.

Step 6 — Connect with gsql and check the version

openGauss ships the gsql client inside the container. Connect on port 5432 as gaussdb with the per-VM password and check the version:

sudo docker exec opengauss env GAUSSHOME=/usr/local/opengauss LD_LIBRARY_PATH=/usr/local/opengauss/lib \
  /usr/local/opengauss/bin/gsql "host=127.0.0.1 port=5432 dbname=postgres user=gaussdb password=<GAUSSDB_PASSWORD>" \
  -t -c "SELECT version();" </dev/null

 (openGauss 5.0.0 build ) compiled at 2023-04-18 09:47:39 commit 0 last mr   on x86_64-unknown-linux-gnu, compiled by g++ (GCC) 7.3.0, 64-bit

A wrong password is rejected:

gsql: FATAL:  Invalid username/password,login denied.

Step 7 — Run SQL

openGauss uses standard SQL. Create a database and a table, insert rows, and run an aggregation:

sudo docker exec opengauss env GAUSSHOME=/usr/local/opengauss LD_LIBRARY_PATH=/usr/local/opengauss/lib \
  /usr/local/opengauss/bin/gsql "host=127.0.0.1 port=5432 dbname=postgres user=gaussdb password=<GAUSSDB_PASSWORD>" \
  -c "CREATE DATABASE demo;" </dev/null
sudo docker exec opengauss env GAUSSHOME=/usr/local/opengauss LD_LIBRARY_PATH=/usr/local/opengauss/lib \
  /usr/local/opengauss/bin/gsql "host=127.0.0.1 port=5432 dbname=demo user=gaussdb password=<GAUSSDB_PASSWORD>" \
  -c "CREATE TABLE events(id int primary key, kind varchar(32)); INSERT INTO events VALUES (1,'login'),(2,'click'),(3,'click');" </dev/null
sudo docker exec opengauss env GAUSSHOME=/usr/local/opengauss LD_LIBRARY_PATH=/usr/local/opengauss/lib \
  /usr/local/opengauss/bin/gsql "host=127.0.0.1 port=5432 dbname=demo user=gaussdb password=<GAUSSDB_PASSWORD>" \
  -c "SELECT kind, COUNT(*) AS n FROM events GROUP BY kind ORDER BY kind;" </dev/null

 kind  | n
-------+---
 click | 2
 login | 1
(2 rows)

The rows were written and aggregated by the same engine. Clean up the demo database when you are finished:

sudo docker exec opengauss env GAUSSHOME=/usr/local/opengauss LD_LIBRARY_PATH=/usr/local/opengauss/lib \
  /usr/local/opengauss/bin/gsql "host=127.0.0.1 port=5432 dbname=postgres user=gaussdb password=<GAUSSDB_PASSWORD>" \
  -c "DROP DATABASE demo;" </dev/null

Step 8 — The two built-in superusers

openGauss seeds two superuser accounts, each with its own distinct per-VM password:

• gaussdb — the documented default superuser. Use this account for your applications and day-to-day administration. Its password is opengauss.gaussdb.password.
• opengauss — the initial account created when the database was first initialised. Its password is opengauss.opengauss.password.

Both are full superusers. For application work, create a dedicated least-privilege role rather than using either superuser directly:

sudo docker exec opengauss env GAUSSHOME=/usr/local/opengauss LD_LIBRARY_PATH=/usr/local/opengauss/lib \
  /usr/local/opengauss/bin/gsql "host=127.0.0.1 port=5432 dbname=postgres user=gaussdb password=<GAUSSDB_PASSWORD>" \
  -c "CREATE ROLE app_user WITH LOGIN PASSWORD 'Choose-A-Strong-Passw0rd!';" </dev/null

Step 9 — Connect remotely over an SSH tunnel

Port 5432 is bound on the VM but not exposed publicly — this is the secure default. To reach the database from your workstation, open an SSH tunnel:

# On your workstation:
ssh -L 5432:127.0.0.1:5432 azureuser@<vm-public-ip>

Because clients must use gsql, the simplest remote workflow is an interactive shell inside the container:

sudo docker exec -it opengauss bash -lc 'gsql -d postgres -U gaussdb -W'

For production remote access, open port 5432 in your NSG only for trusted source ranges, or place the database behind a private NIC. Never expose the database port to the open internet.

Maintenance

• Persistence: the database store lives in a Docker volume on the dedicated data disk at /var/lib/opengauss, so your data survives reboots and the volume is independently resizable.
• Password: rotate the gaussdb password from a superuser session with ALTER ROLE gaussdb IDENTIFIED BY '<new-password>' REPLACE '<old-password>';. The initial opengauss account can only change its own password from its own session.
• Service control: sudo systemctl status opengauss, sudo systemctl restart opengauss. Logs are available with sudo journalctl -u opengauss and sudo docker logs opengauss.
• Password policy: openGauss enforces a strong-password policy (at least 8 characters with a mix of uppercase, lowercase, digits and special characters) and locks an account after repeated failed logins; unlock with ALTER ROLE <name> ACCOUNT UNLOCK;.
• Scaling: this image runs the standalone single-node configuration. For distributed or high-availability topologies, contact cloudimg support.
• 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.

openGauss is a trademark of Huawei Technologies Co., Ltd. PostgreSQL is a trademark of the PostgreSQL Community Association. This image is provided by cloudimg and is not affiliated with or endorsed by Huawei or the PostgreSQL Community Association.