BaseX 12.4

In the AWS Marketplace listing, choose Continue to Subscribe, then Continue to Configuration. Pick BaseX 12.4 on Ubuntu 24.04 as the software version, choose your Region, then choose Launch through EC2.

Choose m5.large, your key pair and a security group as described above. The AMI brings its own 20 GiB data volume for BaseX. Increase its size on the launch page if you expect more data (Step 9).

To launch with the AWS CLI instead, replace the values in angle brackets:

aws ec2 run-instances --region <region> --image-id <ami-id-from-the-listing> \
  --instance-type m5.large --key-name <your-key-pair> \
  --security-group-ids <your-security-group> --subnet-id <your-subnet> \
  --metadata-options HttpTokens=required,HttpEndpoint=enabled \
  --tag-specifications 'ResourceType=instance,Tags=[{Key=Name,Value=basex}]'

Version: BaseX 12.4 on Ubuntu 24.04.

SSH user: ubuntu.

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

First boot generates the certificate and the admin password, then starts BaseX and nginx. BaseX is ready a few seconds after boot:

systemctl is-active basex nginx basex-firstboot
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 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) listen 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 credentials file:

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

BASEX_DBA_URL=https://ec2-<public-ip-dashed>.compute-1.amazonaws.com/dba BASEX_REST_URL=https://ec2-<public-ip-dashed>.compute-1.amazonaws.com/rest BASEX_ADMIN_USER=admin

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

The URLs use the instance's public DNS name from EC2 instance metadata (IMDSv2), or its public or private IPv4 address when it has no public name. The certificate names that host plus the instance's public and private IP addresses:

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

subject=CN = ec2-<public-ip-dashed>.compute-1.amazonaws.com, O = sac X509v3 Subject Alternative Name: DNS:ec2-<public-ip-dashed>.compute-1.amazonaws.com, IP Address:<public-ip>, IP Address:<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 credentials file into a shell variable and pass it to curl through a file descriptor. The password never appears in the process list or your shell history:

H=$(sudo sed -n 's#^BASEX_DBA_URL=https://\([^/]*\)/.*#\1#p' /root/basex-credentials.txt)
PW=$(sudo sed -n 's/^BASEX_ADMIN_PASSWORD=//p' /root/basex-credentials.txt) R=(--cacert /etc/ssl/basex/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://ec2-<public-ip-dashed>.compute-1.amazonaws.com/dba REST, no login -> HTTP 401 REST, admin:admin -> HTTP 401 REST, your password -> HTTP 200 DBA, no login -> 302 https://ec2-<public-ip-dashed>.compute-1.amazonaws.com/dba/login?_page=databases ok <- /healthz (no login) HTTP 200

--resolve sends the request to this instance while keeping the real host name, so the certificate check passes. From another machine, omit --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 before and hands it to curl through a file descriptor:

H=$(sudo sed -n 's#^BASEX_REST_URL=https://\([^/]*\)/.*#\1#p' /root/basex-credentials.txt)
PW=$(sudo sed -n 's/^BASEX_ADMIN_PASSWORD=//p' /root/basex-credentials.txt) bx() { curl -s --cacert /etc/ssl/basex/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 7.06 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. See the BaseX documentation on the REST API for the full set of operations.

Open the BASEX_DBA_URL from Step 4 (https://<your-host>/dba) in a browser. The certificate is self-signed, so the browser warns once. Accept the warning, or install your own certificate (Step 10). Sign in as admin with the password from the credentials file.

Databases lists every database with its resource count, size and last change. You can create, optimize, drop, back up and restore databases there. Select a database to see its resources, its backups, and its properties and indexes.

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

Users creates further users and sets their permissions (read, write, create or admin). Logs 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, it reads the password from there, so you can pipe it straight from the credentials file:

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

Password: 3

Run basexclient -U admin without -c for an interactive session. The client prompts for the password. Client libraries for Java, Python, Node.js and other languages speak the same protocol. Run them on the instance, or forward the port over SSH from your workstation and connect to localhost:1984:

ssh -i <your-key.pem> -N -L 1984:127.0.0.1:1984 ubuntu@<public-ip>

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

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

H=$(sudo sed -n 's#^BASEX_REST_URL=https://\([^/]*\)/.*#\1#p' /root/basex-credentials.txt)
PW=$(sudo sed -n 's/^BASEX_ADMIN_PASSWORD=//p' /root/basex-credentials.txt) xq() { curl -s --cacert /etc/ssl/basex/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="put" timeout="5"><http:header name="X-aws-ec2-metadata-token-ttl-seconds" value="60"/></http:request>, "http://169.254.169.254/latest/api/token")[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

The following commands show the service settings behind this behavior:

systemctl show basex -p User -p NoNewPrivileges -p ProtectSystem -p ProtectHome -p PrivateTmp -p IPAddressDeny
systemctl show nginx -p IPAddressDeny

IPAddressDeny=fd00:ec2::254/128 169.254.169.254/32 168.63.129.16/32 User=basex PrivateTmp=yes ProtectHome=yes ProtectSystem=strict NoNewPrivileges=yes IPAddressDeny=fd00:ec2::254/128 169.254.169.254/32 168.63.129.16/32

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, on the dedicated EBS volume. The JVM runs with a 2 GB heap:

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

20G total, 19G free on /var/lib/basex DBPATH = /var/lib/basex/data REPOPATH = /var/lib/basex/repo SERVERPORT = 1984 SERVERHOST = 127.0.0.1 -Xmx2g

• Heap. On a larger instance, raise -Xmx2g in /usr/local/lib/sac/basex-java (about half of the instance's memory is a good start), then run sudo systemctl restart basex.
• Disk. To grow the volume, modify it in the EC2 console (Volumes, Modify volume) 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. Backups are written next to the databases on the data volume. For a full copy, stop BaseX (sudo systemctl stop basex) and take an EBS snapshot of the data volume.
• Logs. BaseX writes one log per day to /var/lib/basex/data/.logs (also under Logs in the DBA). journalctl -u basex shows the service output, and journalctl -u basex-firstboot shows what first boot did.

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

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

If the instance's public DNS name changes after a stop and start, run the same command again, because a request for a name that the instance does not serve is dropped. An Elastic IP avoids this.

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

SSH accepts keys only. Passwords, root logins and X11 forwarding are switched off in /etc/ssh/sshd_config.d/00-sac.conf, which sorts before every other SSH setting. Check the effective values:

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

permitrootlogin no pubkeyauthentication yes passwordauthentication no kbdinteractiveauthentication no x11forwarding no

Keep the following points in mind:

• To change the admin password, sign in to the DBA, open Users, then admin, and set a new password (or run ALTER PASSWORD admin in basexclient). Then update /root/basex-credentials.txt.
• The admin user can read and write files on the data volume, query other web services and run programs as the basex user through XQuery. Use separate users with read or write permission for applications.
• nginx logs the real client address of every request, and it ignores X-Forwarded-For headers sent by clients. The AMI requires IMDSv2. Restrict port 443 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 normalized 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 5, drop it:

H=$(sudo sed -n 's#^BASEX_REST_URL=https://\([^/]*\)/.*#\1#p' /root/basex-credentials.txt)
PW=$(sudo sed -n 's/^BASEX_ADMIN_PASSWORD=//p' /root/basex-credentials.txt)
curl -s --cacert /etc/ssl/basex/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.