BaseX

Search the Azure Marketplace for BaseX on Ubuntu 24.04 and choose Create. Pick your size, your authentication type and a network security group as described in Prerequisites.

The image brings its own 30 GiB data disk for BaseX. You can grow it later (Step 10).

RG="basex-prod"; LOCATION="eastus"; VM_NAME="basex-01" IMAGE_URN="sac1647283583153:basex-ubuntu-24-04:default:latest" az group create --name "$RG" --location "$LOCATION" az network nsg create -g "$RG" --name basex-nsg az network nsg rule create -g "$RG" --nsg-name basex-nsg --name allow-ssh --priority 100 \
  --source-address-prefixes "<your-mgmt-cidr>" --destination-port-ranges 22 --access Allow --protocol Tcp az network nsg rule create -g "$RG" --nsg-name basex-nsg --name allow-https --priority 110 \
  --source-address-prefixes "<your-client-cidr>" --destination-port-ranges 443 --access Allow --protocol Tcp
# Accept the Marketplace terms once per subscription (required before the first CLI deploy)
az vm image terms accept --urn "$IMAGE_URN"
az vm create -g "$RG" --name "$VM_NAME" --image "$IMAGE_URN" \
  --size Standard_B2s --admin-username azureuser --ssh-key-values ~/.ssh/id_rsa.pub \
  --nsg basex-nsg --public-ip-sku Standard

ssh azureuser@<vm-public-ip>

On first boot, the VM records its public IP address and generates the certificate and the admin password. Then BaseX and nginx start. BaseX is ready a few seconds after boot:

systemctl is-active sac-public-ip basex-firstboot basexhttp nginx
sudo test -f /var/lib/sac/data/basex-firstboot.done && echo FIRSTBOOT_DONE java -cp /opt/basex/BaseX.jar org.basex.BaseX -h 2>&1 | head -1 java -version 2>&1 | head -1

active active active active FIRSTBOOT_DONE BaseX 12.4 [Standalone] openjdk version "21.0.12.1" 2026-08-18

Only SSH and nginx listen on public addresses. The BaseX HTTP server (8984) and database server (1984) are on loopback:

sudo ss -Hlntp | awk '{print $4, $6}' | grep -v '127.0.0.5' | sed -E 's/,pid=[0-9]+,fd=[0-9]+//g' | sort

0.0.0.0:22 users:(("sshd"),("systemd")) 0.0.0.0:443 users:(("nginx"),("nginx"),("nginx")) 0.0.0.0:80 users:(("nginx"),("nginx"),("nginx")) 127.0.0.1:1984 users:(("java")) 127.0.0.1:8984 users:(("java")) [::]:22 users:(("sshd"),("systemd")) [::]:443 users:(("nginx"),("nginx"),("nginx")) [::]:80 users:(("nginx"),("nginx"),("nginx"))

The URLs and the user name are in the root-only info file:

sudo grep -E '^BASEX_(DBA_URL|REST_URL|ADMIN_USERNAME)=' /root/basex-info.txt

BASEX_DBA_URL=https://<vm-public-ip>/dba BASEX_REST_URL=https://<vm-public-ip>/rest BASEX_ADMIN_USERNAME=admin

The password is the BASEX_ADMIN_PASSWORD line of the same file: sudo grep '^BASEX_ADMIN_PASSWORD=' /root/basex-info.txt. Store it in your password manager. It is unique to this VM, and admin is the BaseX superuser.

The URLs use the VM's public IP address, or its private address when it has none. The certificate names that address plus the VM's private address and loopback:

openssl x509 -in /etc/nginx/tls/basex.crt -noout -subject -ext subjectAltName -enddate

subject=CN = <vm-public-ip>, O = sac X509v3 Subject Alternative Name: IP Address:<vm-public-ip>, IP Address:<vm-private-ip>, IP Address:127.0.0.1, DNS:localhost notAfter=<date about 27 months after first boot>

Without the password, the REST API answers 401, the default admin/admin login is refused, the DBA sends you to its login page, and port 80 redirects to HTTPS.

The following commands read the password from the info file into a shell variable and pass it to curl through a file descriptor, so it never appears in the process list or your shell history:

H=$(sudo sed -n 's#^BASEX_DBA_URL=https://\([^/]*\)/.*#\1#p' /root/basex-info.txt)
PW=$(sudo sed -n 's/^BASEX_ADMIN_PASSWORD=//p' /root/basex-info.txt) R=(--cacert /etc/nginx/tls/basex.crt --resolve "$H:443:127.0.0.1") curl -s -o /dev/null -w 'http:// -> %{http_code} %{redirect_url}\n' --resolve "$H:80:127.0.0.1" "http://$H/dba" curl -s -o /dev/null -w 'REST, no login -> HTTP %{http_code}\n' "${R[@]}" "https://$H/rest" curl -s -o /dev/null -w 'REST, admin:admin -> HTTP %{http_code}\n' "${R[@]}" -K <(printf 'user = "admin:admin"\n') "https://$H/rest" curl -s -o /dev/null -w 'REST, your password -> HTTP %{http_code}\n' "${R[@]}" -K <(printf 'user = "admin:%s"\n' "$PW") "https://$H/rest" curl -s -o /dev/null -w 'DBA, no login -> %{http_code} %{redirect_url}\n' "${R[@]}" "https://$H/dba/databases" curl -s -w ' <- /healthz (no login) HTTP %{http_code}\n' "${R[@]}" "https://$H/healthz"

http:// -> 301 https://<vm-public-ip>/dba REST, no login -> HTTP 401 REST, admin:admin -> HTTP 401 REST, your password -> HTTP 200 DBA, no login -> 302 https://<vm-public-ip>/dba/login?_page=databases ok <- /healthz (no login) HTTP 200

The --resolve option sends the request to this VM while keeping the real host name, so the certificate check passes. From another machine, drop --resolve and use the URL directly.

The REST API takes the same user and password with HTTP Basic authentication over HTTPS. This example creates a library database from an XML document with PUT, runs two XQuery expressions against it, lists the databases and returns a JSON summary.

The small bx function reads the password as above and hands it to curl through a file descriptor:

H=$(sudo sed -n 's#^BASEX_REST_URL=https://\([^/]*\)/.*#\1#p' /root/basex-info.txt)
PW=$(sudo sed -n 's/^BASEX_ADMIN_PASSWORD=//p' /root/basex-info.txt) bx() { curl -s --cacert /etc/nginx/tls/basex.crt --resolve "$H:443:127.0.0.1" -K <(printf 'user = "admin:%s"\n' "$PW") "$@"; echo; } bx -X PUT -H 'Content-Type: application/xml' --data-binary '<library> <book id="b1"><title>XQuery</title><author>Priscilla Walmsley</author><year>2015</year></book> <book id="b2"><title>XML in a Nutshell</title><author>Elliotte Rusty Harold</author><year>2004</year></book> <book id="b3"><title>Designing Data-Intensive Applications</title><author>Martin Kleppmann</author><year>2017</year></book> </library>' "https://$H/rest/library" bx --get --data-urlencode 'query=for $b in //book order by xs:integer($b/year) descending return $b/title/string()' "https://$H/rest/library" bx --get --data-urlencode 'query=//book[xs:integer(year) gt 2010]/author/string()' "https://$H/rest/library" bx "https://$H/rest" bx --get --data-urlencode 'query=json:serialize(map { "books": count(//book), "newest": max(//book/year ! xs:integer(.)) })' "https://$H/rest/library"

Database 'library' created in 49.59 ms. Designing Data-Intensive Applications XQuery XML in a Nutshell Priscilla Walmsley Martin Kleppmann <databases xmlns="http://basex.org/rest"><database resources="1" size="5533">library</database></databases> {"books":3,"newest":2017}

GET /rest/<database> without a query returns the stored documents. DELETE /rest/<database> drops a database, and POST takes a query or command document. For the full set of operations, see the BaseX documentation on the REST API.

In a browser, open the BASEX_DBA_URL from Step 5 (https://<vm-public-ip>/dba). The certificate is self-signed, so the browser warns you once. Accept the warning, or install your own certificate (Step 11). Sign in as admin with the password from the info file:

The Databases page lists every database with its resource count, size and last change. You can create, optimize, drop, back up and restore databases from this page:

The Editor runs XQuery against your databases and shows the result next to the query. Press Ctrl-Enter to run a query:

Click a database to see its resources, its backups, and its properties and indexes:

The Users page creates further users and sets their permissions (read, write, create or admin). The Logs page shows every request with its user, address and timing. Give applications their own user with the least permission they need, rather than the admin superuser.

The BaseX command-line client is on every login's PATH. It connects to the BaseX database server on 127.0.0.1:1984 and asks for the password. When standard input is not a terminal, the client reads the password from there, so you can pipe it straight from the info file:

sudo sed -n 's/^BASEX_ADMIN_PASSWORD=//p' /root/basex-info.txt | /opt/basex/bin/basexclient -U admin -c 'XQUERY count(db:get("library")//book)'; echo

Password: 3

For an interactive session, run basexclient -U admin without -c. The client prompts for the password.

Client libraries for Java, Python, Node.js and other languages speak the same protocol. Run them on the VM, or forward the port over SSH from your workstation and connect to localhost:1984:

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

Never open 1984 or 8984 in a network security group. For applications on other hosts, use the REST API over HTTPS (Step 6).

XQuery functions run inside the BaseX service. proc:system runs programs as the unprivileged basex user, and the file functions see a read-only system with the secrets hidden. Requests to the Azure metadata service are dropped:

H=$(sudo sed -n 's#^BASEX_REST_URL=https://\([^/]*\)/.*#\1#p' /root/basex-info.txt)
PW=$(sudo sed -n 's/^BASEX_ADMIN_PASSWORD=//p' /root/basex-info.txt) xq() { curl -s --cacert /etc/nginx/tls/basex.crt --resolve "$H:443:127.0.0.1" -K <(printf 'user = "admin:%s"\n' "$PW") --get --data-urlencode "query=$1" "https://$H/rest"; echo; } xq 'normalize-space(proc:system("id", "-un"))' xq 'try { file:read-text("/etc/shadow") } catch * { "refused: " || $err:description }' xq 'try { file:write-text("/var/lib/sac/config/sac-test", "x") } catch * { "refused: " || $err:description }' xq 'try { http:send-request(<http:request method="get" timeout="5"><http:header name="Metadata" value="true"/></http:request>, "http://169.254.169.254/metadata/instance?api-version=2021-02-01")[1]/@status/string() } catch * { "refused: " || $err:description }'

basex refused: Access to '/etc/shadow' is denied. refused: Resource "/var/lib/sac/config/sac-test (Read-only file system)" not found. refused: HTTP connect timed out

These service settings enforce the confinement. BaseX may write only /var/lib/basex. The metadata service and the wire server are denied to BaseX, nginx and the first-boot service, while the Azure Linux agent keeps its wire server access:

systemctl show basexhttp -p User -p NoNewPrivileges -p ProtectSystem -p ProtectHome -p PrivateTmp -p ReadWritePaths -p IPAddressDeny
systemctl show nginx basex-firstboot -p Id -p IPAddressDeny

IPAddressDeny=169.254.169.254/32 168.63.129.16/32 User=basex ReadWritePaths=/var/lib/basex PrivateTmp=yes ProtectHome=yes ProtectSystem=strict NoNewPrivileges=yes IPAddressDeny=169.254.169.254/32 168.63.129.16/32 Id=nginx.service IPAddressDeny=169.254.169.254/32 168.63.129.16/32 Id=basex-firstboot.service

BaseX keeps its databases, the user file users.xml and its logs under /var/lib/basex/data, and the XQuery package repository under /var/lib/basex/repo. Both locations are on the dedicated data disk. The JVM runs with a 1.5 GB heap, sized for a Standard_B2s:

df -h /var/lib/basex | tail -1 | awk '{print $2" total, "$4" free on "$6}'
sudo grep -E '^(DBPATH|REPOPATH|SERVERHOST|SERVERPORT) ' /opt/basex/.basex grep -oE -- '-Xmx[0-9a-z]+' /usr/local/lib/sac/basex-java

30G total, 28G free on /var/lib/basex DBPATH = /var/lib/basex/data REPOPATH = /var/lib/basex/repo SERVERPORT = 1984 SERVERHOST = 127.0.0.1 -Xmx1500m

• Heap. On a larger VM, raise -Xmx1500m in /usr/local/lib/sac/basex-java. About half of the VM's memory is a good starting point. Then run sudo systemctl restart basexhttp.
• Disk. To grow the data disk, stop the VM (deallocate) and resize the disk in the Azure portal (Disks, Size + performance). Then start the VM and extend the file system online: sudo resize2fs "$(findmnt -no SOURCE /var/lib/basex)".
• Backups. Create database backups in the DBA (Databases, Back up) or with the CREATE BACKUP command. They are written next to the databases on the data disk. For a full copy, stop BaseX (sudo systemctl stop basexhttp) and take an Azure snapshot of the data disk.
• Logs. BaseX writes one log per day to /var/lib/basex/data/.logs, which is also visible under Logs in the DBA. journalctl -u basexhttp shows the service output, and journalctl -u basex-firstboot shows what first boot did.

The served host name is fixed by configuration and is never taken from a request. To serve BaseX under your own DNS name, point the name at the VM and run the helper. The helper records the name, regenerates the self-signed certificate for it, updates the info file and reloads nginx:

sudo basex-set-hostname <your-dns-name>

If you use the VM's public IP address and it changes (for example, a dynamic IP after a deallocate), run the same command with the new address, because a request for a name that the VM does not serve is dropped. A static public IP avoids this.

To use a certificate from your own CA or a public CA instead, replace /etc/nginx/tls/basex.crt (full chain) and /etc/nginx/tls/basex.key (mode 0600, owner root). Then run sudo nginx -t && sudo systemctl reload nginx.

Root logins, empty passwords and X11 forwarding are switched off in /etc/ssh/sshd_config.d/00-sac.conf, which sorts before every other SSH setting. Key or password sign-in is not pinned there. It follows the authentication type you chose when you created the VM. Check the effective values:

sudo sshd -T | grep -E '^(permitrootlogin|permitemptypasswords|x11forwarding|pubkeyauthentication) '

permitrootlogin no pubkeyauthentication yes x11forwarding no permitemptypasswords no

Also note the following points:

• Admin password: To change it, sign in to the DBA, open Users, then admin, and set a new password. Alternatively, run ALTER PASSWORD admin in basexclient. Then update /root/basex-info.txt.
• Superuser reach: The admin user can read and write files on the data disk, query other web services and run programs as the basex user through XQuery. Use separate users with read or write permission for applications.
• Client addresses: nginx logs the real client address of every request, and X-Forwarded-For headers sent by clients are ignored. Restrict port 443 in your network security group to the networks that use BaseX.
• Bundled libraries: BaseX 12.4 ships Jetty 12.1.8, which a scanner reports as affected by CVE-2026-10050 (high: a DIGEST authentication bypass in Jetty's security module), CVE-2026-6790 (Host header validation), CVE-2026-8384 (a path confusion in Jetty's static file handling) and CVE-2026-10051 (HTTP/1.1 trailers kept across connections). All four are fixed in Jetty 12.1.10. BaseX does not use Jetty's authenticators: it checks the HTTP Basic credentials itself, and this image uses Basic authentication only. Jetty is reached only through nginx, which sends a fixed host name, forwards a normalised path for /dba and /rest only, and re-frames each request. 12.4 is the newest BaseX release, and SecureAnyCloud updates the image when BaseX ships a release with the newer Jetty.

When you have finished with the example database from Step 6, drop it:

H=$(sudo sed -n 's#^BASEX_REST_URL=https://\([^/]*\)/.*#\1#p' /root/basex-info.txt)
PW=$(sudo sed -n 's/^BASEX_ADMIN_PASSWORD=//p' /root/basex-info.txt)
curl -s --cacert /etc/nginx/tls/basex.crt --resolve "$H:443:127.0.0.1" -K <(printf 'user = "admin:%s"\n' "$PW") -X DELETE "https://$H/rest/library"; echo

Database 'library' was dropped.

Sign in to the AWS Management Console, open the EC2 service, and select Launch instance. Under Application and OS Images, choose AWS Marketplace AMIs and search for BaseX. Select the SecureAnyCloud listing, choose Select, and then choose Continue on the subscription summary.

Pick an instance type of m5.large or larger. BaseX is a JVM workload, so size the instance for your database and query concurrency. Choose your EC2 key pair under Key pair (login).

Under Network settings, select your VPC and subnet, and create or select a security group. The group must open port 22 from your management network and port 443 from the networks that will reach the database. Leave the root volume at the default size or larger, and keep the attached data volume that holds the databases.

Select Launch instance. First-boot initialisation takes approximately one minute after the instance state becomes Running and the status checks pass.

The following command launches an instance from the SecureAnyCloud BaseX Marketplace AMI into an existing subnet and security group. Replace <ami-id> with the AMI ID shown on the Marketplace listing and <key-name> with your EC2 key pair name. Replace <subnet-id> with your subnet ID, and <security-group-id> with a security group that opens ports 22 and 443 as described in Prerequisites.

aws ec2 run-instances \
  --image-id <ami-id> \
  --instance-type m5.large \
  --key-name <key-name> \
  --subnet-id <subnet-id> \
  --security-group-ids <security-group-id> \
  --tag-specifications 'ResourceType=instance,Tags=[{Key=Name,Value=basex}]'

When the instance reaches the Running state and its status checks pass, note its public IP address or DNS name. You can find it in the EC2 console or with aws ec2 describe-instances.

Connect over SSH with your key pair and the login user for your operating system variant.

OS variant SSH login user

Ubuntu 24.04 ubuntu

ssh -i <key-name>.pem ubuntu@<public-ip>

The BaseX administrator password is unique to your instance and was generated on first boot. Read it as root:

sudo cat /root/basex-info.txt

The file lists the administrator user (admin), the generated password, and the DBA and REST URLs for your instance. It is mode 0600 and owned by root, so only the root user can read it.

BaseX and nginx run as systemd services. Confirm that both are active:

systemctl is-active basexhttp.service nginx.service

Confirm that the RESTXQ welcome page answers through nginx TLS. The -k flag accepts the self-signed certificate of the instance:

curl -ks -o /dev/null -w '%{http_code}\n' https://127.0.0.1/

This returns 200. You can also confirm that BaseX is bound to loopback only, so the database is never directly network-facing:

ss -tlnp | grep 8984

Browse to https://<public-ip>/dba to open the BaseX DBA web administration console. The TLS certificate is self-signed for each instance, so your browser warns you on your first visit. Accept the certificate, or install your own (see Step 10). Then sign in as user admin with the password from Step 4.

The console opens on the Databases view. It lists your databases with their document count, size and last modified time, and has buttons to create, optimise, drop, back up and restore them.

Open the Editor tab to run XQuery interactively against your databases. Enter a query and choose Run. The computed result appears in the result pane.

The DBA console also provides Files, Jobs, Users, Sessions and Settings views for managing the server from the browser.

The REST API requires authentication and rejects the stock credential. Confirm that an unauthenticated request and the default admin / admin login are both refused:

curl -ks -o /dev/null -w 'no-auth=%{http_code}\n' https://127.0.0.1/rest
curl -ks -o /dev/null -w 'default-admin=%{http_code}\n' -u admin:admin https://127.0.0.1/rest

Both requests return 401. This confirms that the REST surface is authenticated and that the well-known default credential does not work.

The REST API stores documents and runs XQuery over HTTP with the credentials of your instance. The following commands read the administrator password from the credentials file and create a database named library from an XML document. They then run an XQuery that returns a computed result and remove the database:

PW=$(sudo grep -m1 '^BASEX_ADMIN_PASSWORD=' /root/basex-info.txt | cut -d= -f2-)
curl -ks -u "admin:${PW}" -X PUT -H 'Content-Type: application/xml' \
  --data-binary '<library><book><title>XQuery for Data</title><year>2021</year></book><book><title>RESTXQ in Practice</title><year>2023</year></book></library>' \
  https://127.0.0.1/rest/library
curl -ks -u "admin:${PW}" --get --data-urlencode 'query=(//book[year=max(//book/year)]/title)/string()' https://127.0.0.1/rest/library
curl -ks -u "admin:${PW}" -X DELETE https://127.0.0.1/rest/library

The XQuery returns RESTXQ in Practice, the title of the most recent book, computed from the stored document. You can point any HTTP client or your application at https://<public-ip>/rest. You can also build full HTTP services in XQuery with RESTXQ under the RESTXQ root /.

The databases, the admin credential store and the logs live on a dedicated EBS data volume mounted at /var/lib/basex. The volume is separate from the operating system disk, so you can resize it independently for capacity and IOPS. Confirm the mount:

findmnt /var/lib/basex

The data/ directory under the mount holds the native databases and users.xml. Because the store is on its own volume, you can snapshot it, grow it, or move it to a larger instance independently of the operating system disk.

The nginx TLS certificate is self-signed and regenerated for each instance at /etc/nginx/tls/basex.crt. For production, front the appliance with your own domain and a CA-issued certificate. Replace the certificate and key at /etc/nginx/tls/ and reload nginx, or terminate TLS at a load balancer.

To rotate the administrator password, stop the HTTP server, apply a new password with the standalone tool, and then start the server again:

sudo systemctl stop basexhttp.service
sudo runuser -u basex -- /usr/local/sbin/basex-admin -c 'ALTER PASSWORD admin <your-new-password>'
sudo systemctl start basexhttp.service

Restrict the security group so that ports 80 and 443 are reachable only from your own CIDR ranges. Where possible, deploy in a private VPC subnet.