TerminusDB

Search the Azure Marketplace for TerminusDB on Ubuntu 24.04 LTS by SecureAnyCloud. Choose Standard_B2s or larger, and allow inbound ports 22 and 443.

# Accept the Marketplace terms once per subscription (required before the first CLI deploy)
az vm image terms accept --urn sac1647283583153:terminusdb-ubuntu-24-04:default:latest
az vm create \
  --resource-group my-resource-group \
  --name my-terminusdb \
  --image sac1647283583153:terminusdb-ubuntu-24-04:default:latest \
  --size Standard_B2s \
  --admin-username azureuser \
  --generate-ssh-keys \
  --public-ip-sku Standard

Open the ports the appliance uses:

az vm open-port --resource-group my-resource-group --name my-terminusdb --port 22 --priority 1001
az vm open-port --resource-group my-resource-group --name my-terminusdb --port 443 --priority 1002

Connect over SSH as azureuser:

ssh azureuser@<public-ip>

Three units make up the appliance. docker runs the database container, terminusdb is the database itself, and nginx terminates TLS in front of it.

systemctl is-active docker terminusdb nginx

All three report active.

Confirm the exact image the appliance runs, pinned by digest:

sudo docker images terminusdb/terminusdb-server --digests --format 'table {{.Repository}}\t{{.Tag}}\t{{.Digest}}'

The health endpoint answers without a credential, so you can use it as a load-balancer or uptime probe:

curl -sk https://localhost/api/ok -w '\n'

List the listening ports:

sudo ss -Hltn | awk '{print $4}' | sort -u

Only 22, 80 and 443 are bound on an address reachable from outside the VM. Port 80 only redirects to HTTPS. TerminusDB itself listens on 127.0.0.1:6363 and is reachable only through the TLS proxy, so the administrator password is never sent over a plaintext connection.

The appliance can verify this for you:

sudo /usr/local/sbin/terminusdb-port-check.sh

TerminusDB's published default login is the user admin with the password root. This image never creates it. No database is initialised while the image is built, and the entire store is removed before the image is captured, so the image you launched contains no accounts at all.

On the first boot of your VM, a password is generated for that VM alone. Read it from the credentials file:

sudo cat /root/terminusdb-credentials.txt

The file is 0600 root:root and contains the user, the password and the URLs for this VM.

Store the password in a shell variable for the rest of this guide:

PW=$(sudo grep '^TERMINUSDB_ADMIN_PASSWORD=' /root/terminusdb-credentials.txt | cut -d= -f2-)

By default, TerminusDB treats a caller with no credential as a built-in anonymous identity and reports its version and build hash to them. This image refuses unauthenticated requests at the edge instead. A request with no credential is rejected:

curl -sk -o /dev/null -w 'no credential: %{http_code}\n' https://localhost/api/info

The upstream default and a blank password are rejected too:

curl -sk -o /dev/null -w 'admin/root: %{http_code}\n' -u 'admin:root' https://localhost/api/info
curl -sk -o /dev/null -w 'blank: %{http_code}\n' -u 'admin:' https://localhost/api/info

Each returns 401. Your own password is accepted, and the response names the admin authority:

PW=$(sudo grep '^TERMINUSDB_ADMIN_PASSWORD=' /root/terminusdb-credentials.txt | cut -d= -f2-)
curl -sk -u "admin:$PW" https://localhost/api/info | python3 -m json.tool

To verify the whole security posture, run the following scripts. They also check that each of these tests fails against a known-bad input:

sudo /usr/local/sbin/terminusdb-verify-auth.sh
sudo /usr/local/sbin/terminusdb-gate-selftest.sh

Create a database named people through the HTTP API:

PW=$(sudo grep '^TERMINUSDB_ADMIN_PASSWORD=' /root/terminusdb-credentials.txt | cut -d= -f2-)
curl -sk -u "admin:$PW" -X POST https://localhost/api/db/admin/people \
  -H 'Content-Type: application/json' \
  -d '{"label":"People","comment":"example database"}'

List the databases that exist:

PW=$(sudo grep '^TERMINUSDB_ADMIN_PASSWORD=' /root/terminusdb-credentials.txt | cut -d= -f2-)
curl -sk -u "admin:$PW" https://localhost/api/db | python3 -m json.tool

TerminusDB is schema-checked: documents must satisfy a class you define. Add an Employee class:

PW=$(sudo grep '^TERMINUSDB_ADMIN_PASSWORD=' /root/terminusdb-credentials.txt | cut -d= -f2-)
curl -sk -u "admin:$PW" -X POST \
  'https://localhost/api/document/admin/people?graph_type=schema&author=guide&message=add+Employee+schema' \
  -H 'Content-Type: application/json' \
  -d '{"@type":"Class","@id":"Employee","name":"xsd:string","title":"xsd:string"}'

Insert a document that matches the schema:

PW=$(sudo grep '^TERMINUSDB_ADMIN_PASSWORD=' /root/terminusdb-credentials.txt | cut -d= -f2-)
curl -sk -u "admin:$PW" -X POST \
  'https://localhost/api/document/admin/people?author=guide&message=insert+Ada+Lovelace' \
  -H 'Content-Type: application/json' \
  -d '{"@type":"Employee","name":"Ada Lovelace","title":"Analyst"}'

Read the document back:

PW=$(sudo grep '^TERMINUSDB_ADMIN_PASSWORD=' /root/terminusdb-credentials.txt | cut -d= -f2-)
curl -sk -u "admin:$PW" 'https://localhost/api/document/admin/people?type=Employee'

The schema is enforced. TerminusDB rejects a document with a property the class does not declare instead of storing it:

PW=$(sudo grep '^TERMINUSDB_ADMIN_PASSWORD=' /root/terminusdb-credentials.txt | cut -d= -f2-)
curl -sk -o /dev/null -w 'schema violation: %{http_code}\n' -u "admin:$PW" -X POST \
  'https://localhost/api/document/admin/people?author=guide&message=bad' \
  -H 'Content-Type: application/json' \
  -d '{"@type":"Employee","name":"Bad Record","nonexistent_property":"x"}'

This is what makes TerminusDB different. Every write above was a commit, with the author and message you supplied. Read the log:

PW=$(sudo grep '^TERMINUSDB_ADMIN_PASSWORD=' /root/terminusdb-credentials.txt | cut -d= -f2-)
curl -sk -u "admin:$PW" 'https://localhost/api/log/admin/people' | python3 -m json.tool | head -30

Branching is cheap and works like git. Take a copy of main, change it independently, and compare.

PW=$(sudo grep '^TERMINUSDB_ADMIN_PASSWORD=' /root/terminusdb-credentials.txt | cut -d= -f2-)
curl -sk -u "admin:$PW" -X POST https://localhost/api/branch/admin/people/local/branch/trial \
  -H 'Content-Type: application/json' \
  -d '{"origin":"admin/people/local/branch/main"}'

Confirm that the branch exists:

PW=$(sudo grep '^TERMINUSDB_ADMIN_PASSWORD=' /root/terminusdb-credentials.txt | cut -d= -f2-)
curl -sk -u "admin:$PW" 'https://localhost/api/db/admin/people?branches=true' | python3 -m json.tool

WOQL is TerminusDB's query language. This query finds every document of type Employee:

PW=$(sudo grep '^TERMINUSDB_ADMIN_PASSWORD=' /root/terminusdb-credentials.txt | cut -d= -f2-)
curl -sk -u "admin:$PW" -X POST https://localhost/api/woql/admin/people \
  -H 'Content-Type: application/json' \
  -d '{"query":{"@type":"Triple","subject":{"variable":"S"},"predicate":{"node":"rdf:type"},"object":{"node":"@schema:Employee"}}}' \
  | python3 -m json.tool | head -20

Every command above used localhost from inside the VM. From elsewhere, use the VM's address. The certificate generated at first boot names that address, so once you trust it you can verify it normally:

curl -k -u "admin:<new-password>" https://<public-ip>/api/info

The Python client uses the same API:

from terminusdb_client import Client client = Client("https://<public-ip>") client.connect(user="admin", key="<admin-password>", team="admin", db="people") print(client.get_all_documents())

The image generates a self-signed certificate for your VM's address. To use a certificate for a real domain, replace the certificate and key pair, then reload nginx:

sudo install -m 0644 -o root -g root /path/to/fullchain.pem /etc/terminusdb/tls/server.crt
sudo install -m 0640 -o root -g root /path/to/privkey.pem /etc/terminusdb/tls/server.key
sudo systemctl reload nginx

The store is a directory, so a backup is a copy of it. Take the copy while the database is stopped:

sudo systemctl stop terminusdb
sudo tar -czf /root/terminusdb-backup.tar.gz -C /var/lib/terminusdb storage
sudo systemctl start terminusdb

To restore, put the directory back and correct its ownership:

sudo systemctl stop terminusdb
sudo tar -xzf /root/terminusdb-backup.tar.gz -C /var/lib/terminusdb
sudo chown -R terminusdb:terminusdb /var/lib/terminusdb/storage
sudo systemctl start terminusdb

unattended-upgrades applies Ubuntu security updates automatically. To apply updates immediately, run:

sudo apt-get update && sudo apt-get -y upgrade

The command below reads the new password from standard input, so it never appears in your shell history or the process list.

Do not pipe an empty value into it. TerminusDB accepts an empty password, and your instance would then authenticate anyone. The block refuses any password shorter than 12 characters instead of passing it on:

NEWPW='<new-password>' if [ "${#NEWPW}" -lt 12 ]; then echo "Refusing: the password must be at least 12 characters. Nothing was changed." else printf '%s\n' "$NEWPW" | sudo docker exec -i terminusdb /app/terminusdb/terminusdb user password admin
sudo sed -i "s|^TERMINUSDB_ADMIN_PASSWORD=.*|TERMINUSDB_ADMIN_PASSWORD=${NEWPW}|" /root/terminusdb-credentials.txt echo "Updated, and /root/terminusdb-credentials.txt now matches." fi unset NEWPW

Confirm that the change took effect and that the appliance still refuses everything else:

sudo /usr/local/sbin/terminusdb-verify-auth.sh