G3W-SUITE on Ubuntu 24.04 on Azure User Guide

Overview

G3W-SUITE (also known as g3w-admin) is an open-source framework for publishing QGIS projects as interactive web maps and administering them from the browser. The cloudimg image installs the official g3w-suite/g3w-suite-docker production stack, pinned to the v3.11.0 release with every container image fixed by digest: the g3w-suite application (Django 4.2 + Gunicorn with QGIS Server 3.44 embedded in-process for map rendering), a PostgreSQL 16 database with the PostGIS extension, Redis for caching, and nginx as the web front door. Every secret - the PostgreSQL password, the Django admin password, the QGIS auth-DB master password and the tile-cache token - is generated uniquely on the first boot of every VM, and a fresh administrator account is seeded on a clean database. Backed by 24/7 cloudimg support.

What is included:

• The official G3W-SUITE v3.11.0 stack running under Docker (g3w-suite, postgis, redis and nginx), every image pinned by digest so it never silently upgrades
• QGIS Server 3.44 embedded in the application container, so QGIS projects render as OGC web maps (WMS/WMTS) with no separate map server to manage
• The g3w-admin console published on port 80; PostgreSQL, Redis and QGIS Server stay on the internal Docker network only
• A per-VM administrator account generated on first boot - a unique password recorded in a root-only file - so every VM is secured independently
• WEBGIS_PUBLIC_HOSTNAME resolved to your VM's reachable address at first boot, so CSRF-protected sign-in works out of the box
• The whole stack managed as one g3w-suite.service systemd unit, plus docker.service, both enabled

Prerequisites

• An Azure subscription
• An SSH key pair (ssh-keygen -t ed25519)
• A VM size of at least Standard_B2s (2 vCPU / 4 GiB) - the whole stack, including a live QGIS map render, fits in this footprint

Step 1 - Deploy from the Azure Marketplace

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

Step 2 - Deploy from the Azure CLI

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

az vm open-port --resource-group <your-rg> --name g3w-suite --port 80 --priority 1010

Step 3 - Connect to your VM

ssh azureuser@<vm-public-ip>

Step 4 - Confirm the stack is running

G3W-SUITE runs as a Docker Compose stack managed by a single systemd unit. On first boot the stack rotates every secret, sets its public hostname to your VM's address, recreates itself on a fresh database and seeds the admin account; the multi-container stack (which brings up PostgreSQL, runs the database migrations and loads QGIS Server) can take a minute or two to become fully healthy after the VM is created.

systemctl is-active g3w-suite.service

It reports active. You can list the running containers with:

sudo docker compose -f /var/lib/g3w-suite/docker-compose.yml ps

The whole stack is managed as one systemd unit - use sudo systemctl status g3w-suite and sudo systemctl restart g3w-suite to control every container together.

Step 5 - Retrieve your per-VM admin credentials

The admin password is generated uniquely on the first boot of your VM and written to a root-only file. Confirm the file exists (it is 0600, root-only):

sudo ls -l /root/g3w-suite-credentials.txt

Then read it to get your credentials:

sudo cat /root/g3w-suite-credentials.txt

The file contains g3w.url (the address to browse to), g3w.admin.username (admin), g3w.admin.console (the Django admin URL) and G3W_ADMIN_PASSWORD (for the web console). Store them somewhere safe.

Step 6 - Confirm the console is healthy

The g3w-admin console answers on port 80 (the login page returns HTTP 200):

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

You can confirm which ports are published - only SSH and the web console; PostgreSQL, Redis and QGIS Server stay on the internal Docker network:

sudo ss -tlnH | awk '{print $4}' | grep -E ':(22|80)$' | sort -u

Sign-in is CSRF-protected. This confirms the per-VM administrator authenticates (HTTP 302) while the upstream default admin/admin is rejected:

B=http://127.0.0.1; L=$B/en/login/
P=$(sudo grep '^G3W_ADMIN_PASSWORD=' /root/g3w-suite-credentials.txt | cut -d= -f2-)
login() { J=$(mktemp); curl -s -c $J -b $J -o /dev/null "$L"; \
  T=$(curl -s -c $J -b $J "$L" | grep -oE 'name="csrfmiddlewaretoken" value="[^"]+"' | head -1 | sed -E 's/.*value="([^"]+)".*/\1/'); \
  C=$(curl -s -c $J -b $J -o /dev/null -w '%{http_code}' -H "Referer: $L" -H "Origin: $B" \
      --data-urlencode "username=admin" --data-urlencode "password=$1" --data-urlencode "csrfmiddlewaretoken=$T" "$L"); \
  rm -f $J; echo "$C"; }
echo "default admin/admin -> HTTP $(login admin)  (200 = rejected)"
echo "per-VM admin       -> HTTP $(login "$P")  (302 = signed in)"

Step 7 - Confirm the pinned release

Every image is pinned by digest to the G3W-SUITE v3.11.0 stack so the appliance never silently upgrades:

sudo docker compose -f /var/lib/g3w-suite/docker-compose.yml config --images

Step 8 - Sign in to the web console

Browse to http://<vm-public-ip>/ and sign in with the username admin and the password from Step 5.

After signing in, the dashboard shows the administration console - your Cartographic Groups, Macro Cartographic Groups and Users, with a count of the map groups you have published.

Step 9 - Publish a QGIS project and view the web map

In QGIS Desktop, prepare a project (.qgs/.qgz). In the g3w-admin console, create a Cartographic Group (choose a name and a map projection), then add a QGIS Project to that group by uploading your .qgs file - G3W-SUITE reads the layers, styling and print layouts straight from the QGIS project. Open the published project to explore it in the WebGIS viewer: pan and zoom the map (rendered by the embedded QGIS Server), toggle layers in the tree, run searches, query features and print, all in the browser.

The full Django administration console (G3W-SUITE Raw Administration, linked from the dashboard) lets you manage every published project, group, user and permission, and shows each project with its active state and cartographic group.

Using a custom domain

The web map viewer builds its data URLs from the address you use to reach the VM. If you put a DNS name or a reverse proxy in front of G3W-SUITE, set WEBGIS_PUBLIC_HOSTNAME in /var/lib/g3w-suite/.env to that address and restart the stack:

sudo sed -i 's/^WEBGIS_PUBLIC_HOSTNAME=.*/WEBGIS_PUBLIC_HOSTNAME=maps.example.com/' /var/lib/g3w-suite/.env
sudo systemctl restart g3w-suite.service

Support

This image is maintained by cloudimg with 24/7 support. G3W-SUITE is published by Gis3W under the Mozilla Public License 2.0; cloudimg packages the official deployment stack and does not modify the upstream application.