BaseX Native XML Database on AWS User Guide

Overview

This image runs BaseX, a lightweight, high performance native XML and JSON database and a fully compliant XQuery 3.1, XPath and XSLT processor. BaseX stores documents in an efficient native store, indexes them for fast full text and structural queries, and answers queries and updates in milliseconds through a clean REST and RESTXQ HTTP API. It also ships the DBA web administration application for managing databases and running interactive XQuery from the browser.

BaseX is installed under /opt/basex and runs its HTTP server as a dedicated unprivileged basex system account under a systemd service that starts it on boot and restarts it on failure. The databases, the admin credential store (users.xml) and the logs live under /var/lib/basex/data on a dedicated, independently resizable EBS data volume, separate from the operating system disk.

The BaseX HTTP server binds to loopback only (127.0.0.1:8984). An nginx reverse proxy terminates TLS on port 443 and is the sole network facing surface for the DBA web admin (/dba), the REST API (/rest) and the RESTXQ root (/); port 80 redirects to HTTPS and serves an unauthenticated /healthz probe for load balancers. Terminating TLS at nginx means the HTTP Basic credentials the REST API uses never cross the network in plaintext.

This image is secure by default. Stock BaseX ships a well known admin / admin credential and its HTTP surface is only as safe as that password. This image ships no known credential: the REST API returns 401 to unauthenticated requests and rejects the stock admin / admin login, and the DBA console enforces its own session login. A unique administrator password is generated on the first boot of every deployed instance, applied to the database, and written to /root/basex-info.txt with mode 0600 so that only root can read it. The database service is configured so that it cannot start before that per instance password has been set.

Prerequisites

Before you deploy this image you need:

• An Amazon Web Services account where you can launch EC2 instances
• IAM permissions to launch instances, create security groups, and subscribe to AWS Marketplace products
• An EC2 key pair in the target Region for SSH access to the instance
• A VPC and subnet in the target Region, with a security group allowing inbound port 22 from your management network and port 443 for the TLS web admin and API, restricted to the networks your clients use
• The AWS CLI (version 2) installed locally if you plan to deploy from the command line

Step 1: Launch the Instance from the AWS Marketplace

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 cloudimg listing and choose Select, then Continue on the subscription summary.

Pick an instance type of m5.large or larger (BaseX is a JVM workload; size it for your database and query concurrency). Choose your EC2 key pair under Key pair (login). Under Network settings select your VPC and subnet, and either create or select a security group that opens 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.

Step 2: Launch the Instance from the AWS CLI

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

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 from the EC2 console or with aws ec2 describe-instances.

Step 3: Connect to Your Instance

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

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

Step 4: Retrieve the Administrator Password

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.

Step 5: Confirm the Services Are Running

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

systemctl is-active basexhttp.service nginx.service

Confirm the RESTXQ welcome page answers through nginx TLS (the -k flag accepts the per instance self signed certificate):

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

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

ss -tlnp | grep 8984

Step 6: Open the DBA Web Admin Console

Browse to https://<public-ip>/dba to open the BaseX DBA web administration console. Because the TLS certificate is self signed per instance, your browser will warn on first visit; accept the certificate (or install your own, see Step 10) and sign in as user admin with the password from Step 4.

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

Open the Editor tab to run XQuery interactively against your databases. Enter a query, choose Run, and 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.

Step 7: Confirm Authentication Is Enforced

The REST API requires authentication and rejects the stock credential. Confirm 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 return 401, confirming that the REST surface is authenticated and the well known default credential does not work.

Step 8: Store a Document and Run XQuery over REST

The REST API stores documents and runs XQuery over HTTP with your per instance credentials. The following block reads the administrator password from the credentials file, creates a database named library from an XML document, runs an XQuery that returns a computed result, then removes 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, and build full HTTP services in XQuery with RESTXQ under the RESTXQ root /.

Step 9: The Dedicated Data Volume

The databases, the admin credential store and the logs live on a dedicated EBS data volume mounted at /var/lib/basex, 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.

Step 10: TLS, Passwords and Hardening

The nginx TLS certificate is self signed and regenerated per instance at /etc/nginx/tls/basex.crt. For production, front the appliance with your own domain and a CA issued certificate by replacing the certificate and key at /etc/nginx/tls/ and reloading 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, then start it 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, and deploy in a private VPC subnet where possible.

Maintenance

• Service management: sudo systemctl {status,restart,stop,start} basexhttp.service controls the database; nginx is sudo systemctl restart nginx.service.
• Logs: sudo journalctl -u basexhttp.service shows the server log; BaseX request logs are under /var/lib/basex/data/.logs.
• JVM heap: the service sets -Xmx1500m in /etc/systemd/system/basexhttp.service. Increase it for larger databases and run sudo systemctl daemon-reload then restart.
• Data volume: grow the EBS volume in the AWS console, then extend the filesystem on /var/lib/basex.

Support

cloudimg provides 24/7 technical support for this image via email and live chat. Contact support@cloudimg.co.uk for deployment help, database and endpoint configuration, XQuery and RESTXQ development, backups, authentication and TLS setup, or any issues including refund requests.

All product and company names are trademarks or registered trademarks of their respective holders. Use of them does not imply any affiliation with or endorsement by them.