OrientDB 3.2.57 on AWS User Guide

Overview

This guide covers launching and using the OrientDB 3.2.57 AMI from cloudimg on Amazon EC2. It is one version of the cloudimg Hardened Neo4j & Graph and RDF Databases AMIs listing on AWS Marketplace; you pick it as the software version when you subscribe and launch. Every product in the listing is described at /guides/graph-databases-aws/.

OrientDB Community Edition is a multi-model database: one engine stores graph data (vertices and edges, traversed natively) and document data (schema-less records with nested embedded documents), and queries both with one SQL dialect that adds graph features such as MATCH, TRAVERSE and out() / in() / both(). It ships OrientDB Studio, a browser workbench for queries, schema and graph visualisation, an HTTP/JSON API and a binary protocol for drivers. OrientDB is licensed under the Apache License, Version 2.0.

What cloudimg adds to the upstream build:

• No default login anywhere. On first boot the image generates a unique 24-character password for the OrientDB server root user, handed to OrientDB through a temporary in-memory file that is deleted once OrientDB has stored its hash, never on a command line. The image ships with no OrientDB user and no database. Databases are created without the classic admin/admin, reader/reader and writer/writer users, and the bundled sample database that carries them is removed. OrientDB's built-in guest server account, which upstream recreates with a published password, is given a random password and suspended.
• HTTPS from the first boot, behind one login. nginx serves Studio and the HTTP API on port 443 with a certificate generated on the instance for its own hostname, and asks for the per-instance root login before anything reaches OrientDB. Port 80 only redirects to HTTPS, and requests for any other hostname are dropped.
• The server is loopback only. OrientDB's HTTP port 2480 and binary port 2424 listen on 127.0.0.1; only SSH, 80 and 443 are reachable from the network. Distributed (Hazelcast) mode is removed from the image, so no cluster port can ever open.
• No server-side code execution. The JavaScript engine is removed from the image and the server's script interpreter accepts SQL only, so neither a script command nor a stored JavaScript function can run code on the instance; only an administrator can create or change functions. The ETL plugin, whose jobs can read local files and fetch URLs on the server, is removed, and the Studio feature that downloads a database from a URL on the server (installDatabase) is refused at nginx.
• A sandboxed service. OrientDB runs as an unprivileged orientdb user in a systemd sandbox that can write only its data directory, cannot read system secrets such as /etc/shadow, the credentials file or the TLS key, and cannot reach the instance metadata service.
• Libraries with published security fixes are updated (lz4-java 1.11.4, jackson-core 2.22.4), and Ubuntu 24.04 is fully patched at build time.

What is on the image: Ubuntu 24.04 LTS, OpenJDK 21 (Java runtime only), OrientDB 3.2.57 in /opt/orientdb, the databases and server log on a dedicated 30 GiB data volume at /var/lib/orientdb, nginx, and the cloudimg first-boot service. First boot creates a small Demo database with a graph (four Person vertices joined by Knows edges) and documents (Note records with nested fields) so Studio has something to show straight away.

Connecting to your instance

Prerequisites

1. An AWS account and permission to launch EC2 instances
2. An EC2 key pair in the Region you launch in
3. A security group that allows TCP 22 from your own address, and TCP 443 (and optionally 80, which only redirects) from the clients that will use Studio or the API. The OrientDB ports 2424 and 2480 are never exposed: they listen on loopback only.

Recommended instance type: m5.large (2 vCPU, 8 GiB). The JVM heap is set to 2 GiB in /etc/default/orientdb (ORIENTDB_OPTS_MEMORY) and OrientDB sizes its disk cache from the memory left over; raise both, and the instance size, for large datasets.

Step 1: Launch the instance

Option A: AWS Marketplace console

1. Open the cloudimg Hardened Neo4j & Graph and RDF Databases AMIs listing on AWS Marketplace and choose View purchase options, then Subscribe. One subscription covers every version in the listing.
2. Choose Launch your software, then in Version choose OrientDB 3.2.57 on Ubuntu 24.04 - YYYY-MM-DD and your Region.
3. Instance type: m5.large is recommended.
4. Key pair: choose your EC2 key pair.
5. Security group: TCP 22 from your own address; TCP 443 (and 80) from your clients.
6. Launch. First boot takes about a minute after the instance is reachable, while it generates this instance's certificate and passwords and creates the Demo database.

Option B: AWS CLI

Run this on your own workstation. Replace the AMI ID with the one shown for your Region on the Marketplace launch page, and 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=orientdb}]'

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

Step 2: Connect via SSH

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

The login banner shows the Studio and HTTP API URLs for this instance.

Step 3: Check the services and health

Confirm OrientDB and nginx are running, first boot has finished, and the unauthenticated health endpoint answers over HTTPS:

systemctl is-active orientdb.service nginx.service
test -f /var/lib/cloudimg/orientdb-firstboot.done && echo first-boot-done
curl -sk -o /dev/null -w 'healthz: HTTP %{http_code}\n' https://localhost/healthz

Both services report active, the first-boot marker is present and /healthz returns HTTP 200 (the nginx-served liveness check; it needs no login and returns nothing about OrientDB).

OrientDB itself listens on loopback only; nginx owns the public ports:

sudo ss -tlnp | grep -E ':(2424|2480|80|443) '

You see java on [::ffff:127.0.0.1]:2424 and [::ffff:127.0.0.1]:2480 (the loopback address) and nginx on ports 80 and 443.

Step 4: Read the per-instance credentials

The root 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/orientdb-credentials.txt

This lists ORIENTDB_HOST, ORIENTDB_STUDIO_URL, ORIENTDB_HTTP_API_URL, ORIENTDB_ROOT_USER (root), ORIENTDB_ROOT_PASSWORD (the per-instance password), ORIENTDB_DEMO_DATABASE (Demo) and ORIENTDB_BINARY_URL. Read the password itself with sudo sed -n 's/^ORIENTDB_ROOT_PASSWORD=//p' /root/orientdb-credentials.txt when you need it, and keep it safe: it is the server administrator account. OrientDB stores only a salted PBKDF2 hash of it, and the same password protects the HTTPS gateway (nginx keeps a bcrypt hash).

Step 5: The authentication gate

Every path on port 443 except /healthz requires the login. An anonymous request and a wrong password are both rejected with 401, and so are the classic OrientDB defaults:

curl -sk -o /dev/null -w 'anonymous:      HTTP %{http_code}\n' https://localhost/listDatabases
curl -sk -u 'root:wrong-password' -o /dev/null -w 'wrong password: HTTP %{http_code}\n' https://localhost/listDatabases
curl -sk -u 'admin:admin' -o /dev/null -w 'admin/admin:    HTTP %{http_code}\n' https://localhost/listDatabases

With the per-instance password the API answers 200 and lists the databases:

PW=$(sudo sed -n 's/^ORIENTDB_ROOT_PASSWORD=//p' /root/orientdb-credentials.txt)
curl -sk -u "root:$PW" -o /dev/null -w 'authenticated root: HTTP %{http_code}\n' https://localhost/listDatabases
curl -sk -u "root:$PW" https://localhost/listDatabases; echo

The list contains Demo. OrientDB checks the login again behind nginx, so the defaults are refused by OrientDB itself too, including on the loopback port that bypasses nginx:

for c in admin:admin reader:reader writer:writer guest:guest; do
  printf '%-14s HTTP %s\n' "$c" "$(curl -s -u "$c" -o /dev/null -w '%{http_code}' -X POST --data-binary 'SELECT 1' http://127.0.0.1:2480/command/Demo/sql)"
done

Every line shows HTTP 401: the Demo database has no database users at all, and the built-in guest account is suspended.

Step 6: Open OrientDB Studio

Open https://<public-dns>/studio/index.html in your browser. The certificate is self-signed and unique to this instance, so your browser warns once; serve the instance under your own DNS name with a trusted certificate for production (Step 10). The browser then asks for the gateway login: enter root and the per-instance password. Studio shows its sign-in page:

Choose the Demo database, sign in as root with the same password, and run a query in the Browse tab. The result grid shows the records:

The Graph tab draws vertices and their relationships. Run SELECT FROM Person with the play button: Studio draws the four people and the Knows edges between them, and clicking a vertex shows its properties:

The Schema tab lists the classes: the vertex class Person (extending V) and the edge class Knows (extending E) with their record counts, and further down, under Generic Classes, the schema-less document class Note:

Step 7: Traverse the graph and query documents over the HTTP API

Commands are POST /command/<database>/sql with the statement as the body. A two-hop MATCH pattern walks the Knows edges from Alice:

PW=$(sudo sed -n 's/^ORIENTDB_ROOT_PASSWORD=//p' /root/orientdb-credentials.txt)
curl -sk -u "root:$PW" -X POST https://localhost/command/Demo/sql \
  --data-binary "MATCH {class: Person, as: a, where: (name = 'Alice')}.out('Knows'){as: b}.out('Knows'){as: c} RETURN a.name AS a, b.name AS b, c.name AS c" \
  | python3 -c 'import json,sys; print(json.load(sys.stdin)["result"])'

It returns Alice, who knows Bob, who knows Carol. The same graph answers graph functions inside ordinary SQL, and the document side answers queries on nested fields that exist on no schema:

PW=$(sudo sed -n 's/^ORIENTDB_ROOT_PASSWORD=//p' /root/orientdb-credentials.txt)
curl -sk -u "root:$PW" -X POST https://localhost/command/Demo/sql \
  --data-binary "SELECT name, out('Knows').name AS knows FROM Person ORDER BY name" \
  | python3 -c 'import json,sys; [print(r["name"], "->", r["knows"]) for r in json.load(sys.stdin)["result"]]'
curl -sk -u "root:$PW" -X POST https://localhost/command/Demo/sql \
  --data-binary "SELECT title, meta.author AS author, tags FROM Note WHERE meta.priority = 1" \
  | python3 -c 'import json,sys; print(json.load(sys.stdin)["result"])'

The first prints who each person knows; the second returns the Release plan note written by Alice.

Create your own database and write to it:

PW=$(sudo sed -n 's/^ORIENTDB_ROOT_PASSWORD=//p' /root/orientdb-credentials.txt)
curl -sk -u "root:$PW" -o /dev/null -w 'create database: HTTP %{http_code}\n' -X POST https://localhost/database/Inventory/plocal
curl -sk -u "root:$PW" -o /dev/null -X POST https://localhost/command/Inventory/sql --data-binary "CREATE CLASS Item"
curl -sk -u "root:$PW" -o /dev/null -X POST https://localhost/command/Inventory/sql --data-binary "INSERT INTO Item SET sku = 'A-100', qty = 5"
curl -sk -u "root:$PW" -X POST https://localhost/command/Inventory/sql --data-binary "SELECT sku, qty FROM Item" \
  | python3 -c 'import json,sys; print(json.load(sys.stdin)["result"])'
curl -sk -u "root:$PW" -o /dev/null -w 'drop database: HTTP %{http_code}\n' -X DELETE https://localhost/database/Inventory

The SELECT returns the A-100 item, and the example database is dropped again. A new database has no users of its own: create the users your applications need with CREATE USER <name> IDENTIFIED BY '<password>' ROLE reader (or writer). Never create a database with the security.createDefaultUsers option, which would add the published admin/admin, reader/reader and writer/writer users.

Step 8: Use the binary protocol and the console

Drivers and the OrientDB console connect to the binary port 2424 on loopback. Connect from the instance itself, or from your workstation through an SSH tunnel (ssh -L 2424:127.0.0.1:2424 ubuntu@<vm-ip>). The console reads its commands from a file, which keeps the password off the command line:

PW=$(sudo sed -n 's/^ORIENTDB_ROOT_PASSWORD=//p' /root/orientdb-credentials.txt)
T=$(mktemp -d); chmod 700 "$T"
printf 'connect remote:127.0.0.1:2424/Demo root %s\nselect name, city from Person order by name\n' "$PW" > "$T/demo.osql"
HOME="$T" /opt/orientdb/bin/console.sh "$T/demo.osql" 2>&1 | grep -E '^\||item\(s\) found'
rm -rf "$T"

The console prints the four people and 4 item(s) found. The nginx gateway accepts only root; database users you create sign in over the binary protocol or the loopback HTTP port 2480 (for example through the same SSH tunnel). To let another user through the gateway too, add it to /etc/nginx/orientdb.htpasswd with sudo htpasswd -B /etc/nginx/orientdb.htpasswd <user>, using the same password it has in OrientDB.

Step 9: Where things live

The data volume is mounted by filesystem UUID:

findmnt /var/lib/orientdb
df -h /var/lib/orientdb

To change the heap (ORIENTDB_OPTS_MEMORY), edit /etc/default/orientdb and run sudo systemctl restart orientdb.service. Keep the listeners in orientdb-server-config.xml on 127.0.0.1 so OrientDB stays behind nginx. Back up a database with the console's backup database command or by stopping the service and copying /var/lib/orientdb/databases.

Step 10: Serve under your own DNS name

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

sudo orientdb-set-hostname orientdb.example.com

This issues a new self-signed certificate for that name (replace it with your own CA- or ACM-issued certificate for production) and makes nginx answer only for it. For a public, browser-trusted certificate, terminate TLS at an Application Load Balancer or CloudFront in front of the instance and keep the security group's 443 open only to that front.

Security notes

OrientDB 3.2.57 is the latest release at the time of writing; no published advisory affects it. On top of that, this image:

• ships no OrientDB user and no database, creates databases without default users, and keeps the built-in guest server account suspended with a random password (upstream recreates it with a published password whenever it is missing, so it is disabled rather than deleted);
• removes OrientDB's JavaScript engine: every script language except SQL is refused, and a stored JavaScript function cannot run even when an administrator creates one. 3.2.57 also lets only an administrator create or change a function;
• removes distributed mode and the Hazelcast libraries it needs (which carry published advisories with no fix in the version OrientDB 3.2 uses), and the ETL plugin;
• runs OrientDB as an unprivileged user in a systemd sandbox: it can write only /var/lib/orientdb, and /root, /etc/shadow, /etc/ssh, /etc/nginx, the credentials file and the TLS key are not visible to it, so a database restore or install pointed at a system file cannot read it;
• blocks the instance metadata service (169.254.169.254) for both OrientDB and nginx, so a URL given to OrientDB can never reach the instance's credentials, and refuses installDatabase at nginx;
• refuses cross-origin state-changing requests and WebSocket upgrades at nginx, and logs the real client address.

An attempt to run JavaScript on the server is refused, even for root:

PW=$(sudo sed -n 's/^ORIENTDB_ROOT_PASSWORD=//p' /root/orientdb-credentials.txt)
curl -s -u "root:$PW" -X POST http://127.0.0.1:2480/command/Demo/javascript --data-binary 'java.lang.Runtime.getRuntime()' \
  | python3 -c 'import json,sys; print(json.load(sys.stdin)["errors"][0]["content"])'

OrientDB answers Cannot find a script executor requester for language: javascript.

Keep the instance patched (sudo apt-get update && sudo apt-get upgrade), keep the root password safe, back up /var/lib/orientdb, and expose only ports 22 and 443 to the networks that need them.

Support

cloudimg provides 24/7 technical support for every version in this listing by email and live chat, 365 days a year, with a 24-hour response SLA: support@cloudimg.co.uk.

Trademarks

OrientDB is a trademark of its respective owner and is used here only to identify the software included. cloudimg is not affiliated with, and this image is not endorsed by, the OrientDB project or its trademark holders.