TerminusDB 12.0.8

Option A: AWS Marketplace console

• Open the SecureAnyCloud Hardened Neo4j & Graph and RDF Databases AMIs listing on AWS Marketplace. Choose View purchase options, then Subscribe. One subscription covers every version in the listing.
• Choose Launch your software. In Version, choose TerminusDB 12.0.8 on Ubuntu 24.04 - YYYY-MM-DD, then select your Region.
• Set the instance type. m5.large is recommended.
• Choose your EC2 key pair.
• Set the security group to allow TCP 22 from your own address and TCP 443 (and 80) from your clients.
• Launch the instance. First boot takes under a minute after the instance is reachable. During that time it generates this instance's certificate and admin password and creates the store.

Option B: AWS CLI

Run this command on your own workstation. Replace the AMI ID with the one shown for your Region on the Marketplace launch page. Replace the key pair, security group and subnet with your own:

aws ec2 run-instances \
  --image-id ami-0123456789abcdef0 \
  --instance-type m5.large \
  --key-name my-key-pair \
  --security-group-ids sg-0123456789abcdef0 \
  --subnet-id subnet-0123456789abcdef0 \
  --tag-specifications 'ResourceType=instance,Tags=[{Key=Name,Value=terminusdb}]'

The AMI already requires IMDSv2, so you do not need --metadata-options. The data volume is created from the AMI automatically.

ssh -i my-key-pair.pem ubuntu@<vm-ip>

The login banner points to the credentials file, the self-test and this guide.

Four units make up the appliance: docker runs the database container, sac-docker-imds-deny installs the metadata firewall rule for containers, terminusdb is the database, and nginx terminates TLS in front of it.

systemctl is-active docker sac-docker-imds-deny terminusdb nginx test -f /var/lib/sac/data/terminusdb-firstboot.done && echo first-boot-done curl -sk -o /dev/null -w 'health check /api/ok: HTTP %{http_code}\n' https://localhost/api/ok
sudo docker images terminusdb/terminusdb-server --digests --format '{{.Repository}}:{{.Tag}} {{.Digest}}'

All four units report active, the first-boot marker is present, /api/ok returns HTTP 200 without a credential, and the image is terminusdb/terminusdb-server:v12.0.8 with digest sha256:43061044d1857bb6f1a2f41d7a59ad06ba5f91c03cbc90128d7c0415f32a0916.

TerminusDB listens on loopback only; nginx owns the public ports:

sudo ss -Hltnp | grep -E ':(6363|80|443) ' | awk '{print $4, $6}' | sed -E 's/users:\(\("([a-z-]+)".*/\1/' | sort -u

You see docker-proxy on 127.0.0.1:6363 and nginx on ports 80 and 443. The appliance can check its own listening set for you:

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

The admin password is unique to this instance and is written to a root-only file at first boot. Print only the field names, never the password itself:

sudo grep -oE '^[A-Z_]+=' /root/terminusdb-credentials.txt

This lists TERMINUSDB_ADMIN_USER (admin), TERMINUSDB_ADMIN_PASSWORD, TERMINUSDB_HOST, TERMINUSDB_PUBLIC_IP, TERMINUSDB_URL and TERMINUSDB_API. Read the password with sudo sed -n 's/^TERMINUSDB_ADMIN_PASSWORD=//p' /root/terminusdb-credentials.txt when you need it, and keep it safe.

The examples below use a small shell function, tdb, that hands the password to curl on standard input, so it never appears on a command line or in your shell history. Each block defines it again so you can paste any block on its own.

A request with no credential, the upstream default admin/root, and a blank password are all refused:

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

Each returns HTTP 401, with a WWW-Authenticate: Basic challenge so browsers and HTTP clients know to ask for a login. Your own password is accepted, and the response names the admin user and the version:

tdb() { printf 'user = "admin:%s"\n' "$(sudo sed -n 's/^TERMINUSDB_ADMIN_PASSWORD=//p' /root/terminusdb-credentials.txt)" | curl -sk -K - "$@"; } tdb https://localhost/api/info; echo

The reply is api:success with "authority":"terminusdb://system/data/User/admin" and "terminusdb":{"version":"12.0.8"}.

The whole gate, including a check that each test is itself proven against a known-bad input first:

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

Create a database called people:

tdb() { printf 'user = "admin:%s"\n' "$(sudo sed -n 's/^TERMINUSDB_ADMIN_PASSWORD=//p' /root/terminusdb-credentials.txt)" | curl -sk -K - "$@"; } tdb -X POST https://localhost/api/db/admin/people \
  -H 'Content-Type: application/json' \
  -d '{"label":"People","comment":"example database"}'; echo

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

tdb() { printf 'user = "admin:%s"\n' "$(sudo sed -n 's/^TERMINUSDB_ADMIN_PASSWORD=//p' /root/terminusdb-credentials.txt)" | curl -sk -K - "$@"; } tdb -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"}'; echo tdb -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"}'; echo

Read the document back:

tdb() { printf 'user = "admin:%s"\n' "$(sudo sed -n 's/^TERMINUSDB_ADMIN_PASSWORD=//p' /root/terminusdb-credentials.txt)" | curl -sk -K - "$@"; } tdb 'https://localhost/api/document/admin/people?type=Employee'; echo

The schema is enforced. A document with a property the class does not declare is rejected rather than quietly stored:

tdb() { printf 'user = "admin:%s"\n' "$(sudo sed -n 's/^TERMINUSDB_ADMIN_PASSWORD=//p' /root/terminusdb-credentials.txt)" | curl -sk -K - "$@"; } tdb -o /dev/null -w 'schema violation: HTTP %{http_code}\n' -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"}'

The insert is refused with HTTP 400.

Every write above was a commit, with the author and message you supplied:

tdb() { printf 'user = "admin:%s"\n' "$(sudo sed -n 's/^TERMINUSDB_ADMIN_PASSWORD=//p' /root/terminusdb-credentials.txt)" | curl -sk -K - "$@"; } tdb https://localhost/api/log/admin/people | python3 -c 'import json,sys; [print(c["author"], "|", c["message"]) for c in json.load(sys.stdin)]'

Branching works like git: take a copy of main, change it independently, and compare.

tdb() { printf 'user = "admin:%s"\n' "$(sudo sed -n 's/^TERMINUSDB_ADMIN_PASSWORD=//p' /root/terminusdb-credentials.txt)" | curl -sk -K - "$@"; } tdb -X POST https://localhost/api/branch/admin/people/local/branch/trial \
  -H 'Content-Type: application/json' \
  -d '{"origin":"admin/people/local/branch/main"}'; echo tdb 'https://localhost/api/db/admin/people?branches=true' | python3 -c 'import json,sys; print(json.load(sys.stdin)["branches"])'

The second command lists both main and trial.

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

tdb() { printf 'user = "admin:%s"\n' "$(sudo sed -n 's/^TERMINUSDB_ADMIN_PASSWORD=//p' /root/terminusdb-credentials.txt)" | curl -sk -K - "$@"; } tdb -X POST https://localhost/api/woql/admin/people \
  -H 'Content-Type: application/json' \
  -d '{"query":{"@type":"Triple","subject":{"@type":"NodeValue","variable":"S"},"predicate":{"@type":"NodeValue","node":"rdf:type"},"object":{"@type":"Value","node":"@schema:Employee"}}}' \
  | python3 -c 'import json,sys; print(json.load(sys.stdin)["bindings"])'

From your own machine, use the instance's address. The certificate generated at first boot names it (public IP, private IP and the EC2 DNS names); fetch it once and trust it, or pass -k while testing:

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

The Python client speaks 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())

Browsers and the JavaScript client must call the API from the same origin. nginx refuses state-changing requests (POST, PUT, DELETE) that carry an Origin header for another site. Scripts and server-side clients send no Origin and are unaffected.

Point a DNS record at the instance, then regenerate the certificate and pin the served hostname:

sudo terminusdb-set-hostname terminusdb.example.com

This issues a new self-signed certificate for that name (replace /etc/ssl/terminusdb/terminusdb.crt and terminusdb.key with your own CA- or ACM-issued pair for production, then sudo systemctl reload nginx) and makes nginx answer only for it.

For a public, browser-trusted certificate, you can also terminate TLS at an Application Load Balancer in front of the instance and keep the security group's 443 open only to it.

The store is a directory on its own EBS volume. The simplest backup is an EBS snapshot of the /var/lib/terminusdb volume. For a file-level copy, stop the database first:

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

Restore by putting the directory back with the database stopped, then correcting ownership:

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

The command reads the new password from standard input, so it never appears in your shell history or the process list. It refuses anything shorter than 16 characters:

read -rsp 'New admin password: ' NEWPW; echo if [ "${#NEWPW}" -lt 16 ]; then echo "Refusing: use at least 16 characters. Nothing was changed." else printf '%s\n' "$NEWPW" | sudo docker exec -i terminusdb /app/terminusdb/terminusdb user password admin printf '%s\n' "$NEWPW" | sudo sh -c 'read -r P; sed -i "s|^TERMINUSDB_ADMIN_PASSWORD=.*|TERMINUSDB_ADMIN_PASSWORD=$P|" /root/terminusdb-credentials.txt' echo "Updated, and /root/terminusdb-credentials.txt now matches." fi unset NEWPW

Confirm the change took and that everything else is still refused:

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