Eclipse RDF4J 6.1.0 on AWS User Guide

Overview

This guide covers launching and using the Eclipse RDF4J 6.1.0 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/.

Eclipse RDF4J is a Java framework for working with RDF and linked data. This image ships its two official web applications: RDF4J Server, a triplestore that serves the SPARQL 1.1 Query and Update protocols and the RDF4J REST API for creating and managing repositories (in-memory, native on-disk, LMDB, with optional RDFS inferencing, SHACL validation and Lucene full-text search), and RDF4J Workbench, the browser interface for creating repositories, loading data and running queries. Eclipse RDF4J is licensed under the Eclipse Distribution License v1.0 (BSD-3-Clause).

What cloudimg adds to the upstream build:

• No default login, authentication on every path. RDF4J Server and Workbench have no authentication of their own, and the SPARQL endpoint accepts updates and deletes. On this image nginx requires an admin login on every request: the Workbench, the REST API and every SPARQL query and update. The password is unique to the instance and generated on first boot; nothing listens until it exists. The only unauthenticated path is a /healthz load-balancer check.
• HTTPS from the first boot. nginx serves everything on port 443 with a certificate generated on the instance for its own hostname. Port 80 only redirects to HTTPS, and requests for any other hostname are dropped.
• The server is loopback only and sandboxed. Apache Tomcat 11 listens on 127.0.0.1:8080 with its shutdown port disabled and no manager applications. It runs as an unprivileged service user in a systemd sandbox that cannot read the credentials file, the TLS key, SSH keys or /etc/shadow, and cannot reach the instance metadata service.
• The Workbench is pinned to this server. It cannot be pointed at another server URL or at a local directory.
• Patched libraries. The Spring Framework, Jackson and lz4 libraries inside both web applications are replaced by their latest patch releases, and Tomcat 11.0.27 is verified against the Apache release signature.
• Fully patched Ubuntu 24.04 at build time, with per-instance secrets and the cloudimg security defaults.

What is on the image: Ubuntu 24.04 LTS, OpenJDK 25 (Java runtime), Apache Tomcat 11.0.27 in /opt/tomcat, the RDF4J 6.1.0 Server and Workbench web applications, the RDF4J data directory /var/lib/rdf4j (empty: no repositories), nginx, and the cloudimg first-boot service.

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 the Workbench or the SPARQL endpoints. Tomcat's port 8080 is never exposed: it listens on loopback only.

Recommended instance type: m5.large (2 vCPU, 8 GiB). The Java heap defaults to 50% of instance memory; choose a larger instance for large native or LMDB repositories.

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 Eclipse RDF4J 6.1.0 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 admin password and starts Tomcat.

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=rdf4j}]'

The AMI already requires IMDSv2, so you do not need --metadata-options.

Step 2: Connect via SSH

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

The login banner shows the Workbench and RDF4J Server URLs for this instance.

Step 3: Check the services and health

Confirm Tomcat and nginx are running and the unauthenticated health endpoint answers over HTTPS. The certificate is unique to the instance and covers localhost, so curl can verify it with --cacert:

systemctl is-active tomcat.service nginx.service
curl -s --cacert /etc/ssl/rdf4j/rdf4j.crt -o /dev/null -w 'healthz: HTTP %{http_code}\n' https://localhost/healthz

Both services report active and /healthz returns HTTP 200 (answered by nginx itself; it needs no login).

Step 4: Read the per-instance admin credentials

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-Z0-9_]+=' /root/rdf4j-credentials.txt

This lists RDF4J_HOST, RDF4J_WORKBENCH_URL, RDF4J_SERVER_URL, RDF4J_ADMIN_USER (admin) and RDF4J_ADMIN_PASSWORD (the per-instance password). Read the password with sudo sed -n 's/^RDF4J_ADMIN_PASSWORD=//p' /root/rdf4j-credentials.txt when you need it, and keep it safe: it unlocks the Workbench, the REST API and every SPARQL endpoint.

Step 5: The authentication gate

Every path requires the admin login. An anonymous request, or a wrong password, is rejected with 401:

CA=/etc/ssl/rdf4j/rdf4j.crt
curl -s --cacert $CA -o /dev/null -w 'anonymous Workbench:     HTTP %{http_code}\n' https://localhost/rdf4j-workbench/
curl -s --cacert $CA -o /dev/null -w 'anonymous repositories:  HTTP %{http_code}\n' https://localhost/rdf4j-server/repositories
curl -s --cacert $CA -u 'admin:wrong-password' -o /dev/null -w 'wrong password:          HTTP %{http_code}\n' https://localhost/rdf4j-server/repositories

Each returns HTTP 401. With the per-instance password the server answers 200:

PW=$(sudo sed -n 's/^RDF4J_ADMIN_PASSWORD=//p' /root/rdf4j-credentials.txt)
curl -s --cacert /etc/ssl/rdf4j/rdf4j.crt -u "admin:$PW" -o /dev/null -w 'authenticated:           HTTP %{http_code}\n' https://localhost/rdf4j-server/repositories

Step 6: Use the RDF4J Workbench

Open https://<public-dns>/rdf4j-workbench/ in your browser and sign in as admin with the per-instance password. 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 8). The image ships with no repositories; the List of Repositories page shows each repository you create with its id, description and location:

New repository creates a repository. Choose the store type (memory, native or LMDB, optionally with RDFS inferencing, SHACL or Lucene search, a SPARQL endpoint proxy or a federation), an id and a title:

Load data with Add (upload a file, paste RDF or give an http(s) URL), then run SPARQL in Query. The result table below is a SPARQL SELECT over a small example catalogue of books:

Summary reports the repository's server, store type and statement count:

Step 7: Create a repository and use SPARQL over the REST API

Everything the Workbench does is available over the RDF4J REST API at https://<public-dns>/rdf4j-server/. Create a native (on-disk) repository named books:

PW=$(sudo sed -n 's/^RDF4J_ADMIN_PASSWORD=//p' /root/rdf4j-credentials.txt)
cat > /tmp/books-config.ttl <<'EOF'
@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#>.
@prefix config: <tag:rdf4j.org,2023:config/>.
[] a config:Repository ;
   config:rep.id "books" ;
   rdfs:label "Example books repository" ;
   config:rep.impl [
      config:rep.type "openrdf:SailRepository" ;
      config:sail.impl [ config:sail.type "openrdf:NativeStore" ]
   ].
EOF
curl -s --cacert /etc/ssl/rdf4j/rdf4j.crt -u "admin:$PW" -o /dev/null -w 'create repository: HTTP %{http_code}\n' \
  -X PUT -H 'Content-Type: text/turtle' --data-binary @/tmp/books-config.ttl \
  https://localhost/rdf4j-server/repositories/books
rm -f /tmp/books-config.ttl

The server answers HTTP 204. Insert a triple with SPARQL Update and read it back with a SPARQL query:

PW=$(sudo sed -n 's/^RDF4J_ADMIN_PASSWORD=//p' /root/rdf4j-credentials.txt)
curl -s --cacert /etc/ssl/rdf4j/rdf4j.crt -u "admin:$PW" -o /dev/null -w 'update: HTTP %{http_code}\n' \
  --data-urlencode 'update=INSERT DATA { <http://example.org/book1> <http://purl.org/dc/elements/1.1/title> "SPARQL Tutorial" }' \
  https://localhost/rdf4j-server/repositories/books/statements
curl -s --cacert /etc/ssl/rdf4j/rdf4j.crt -u "admin:$PW" -H 'Accept: text/csv' --get \
  --data-urlencode 'query=SELECT ?title WHERE { ?b <http://purl.org/dc/elements/1.1/title> ?title }' \
  https://localhost/rdf4j-server/repositories/books

The update returns HTTP 204 and the query prints title followed by SPARQL Tutorial. Any SPARQL 1.1 client can use https://<public-dns>/rdf4j-server/repositories/books as its query endpoint and .../books/statements as its update endpoint, with HTTP Basic authentication.

Step 8: Serve under your own DNS name

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

sudo rdf4j-set-hostname rdf4j.example.com

This issues a new self-signed certificate for that name (replace it with your own CA-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.

To give Tomcat a fixed heap instead of 50% of memory, run sudo systemctl edit tomcat.service, add an [Service] section with Environment="CATALINA_OPTS=-Xmx6g -XX:MaxMetaspaceSize=256m -Dorg.eclipse.rdf4j.appdata.basedir=/var/lib/rdf4j -Djava.awt.headless=true", then sudo systemctl restart tomcat.service.

Security notes

RDF4J can load data from a URL (LOAD <url> in SPARQL Update, SERVICE in queries and Add in the Workbench). On this image those requests run inside Tomcat's systemd sandbox: they cannot read the credentials file, the TLS key, SSH keys, /root or /etc/shadow, and they cannot reach the instance metadata service. A LOAD of a protected file is refused and loads nothing:

PW=$(sudo sed -n 's/^RDF4J_ADMIN_PASSWORD=//p' /root/rdf4j-credentials.txt)
curl -s --cacert /etc/ssl/rdf4j/rdf4j.crt -u "admin:$PW" -o /dev/null -w 'LOAD file:///etc/shadow: HTTP %{http_code}\n' \
  --data-urlencode 'update=LOAD <file:///etc/shadow> INTO GRAPH <http://example.org/g>' \
  https://localhost/rdf4j-server/repositories/books/statements

The server returns HTTP 500 (access denied) and the repository is unchanged. A browser on another website cannot make changes with your stored login either: nginx refuses cross-site state-changing requests. When you have finished with the example, delete the books repository:

PW=$(sudo sed -n 's/^RDF4J_ADMIN_PASSWORD=//p' /root/rdf4j-credentials.txt)
curl -s --cacert /etc/ssl/rdf4j/rdf4j.crt -u "admin:$PW" -o /dev/null -w 'delete repository: HTTP %{http_code}\n' \
  -X DELETE https://localhost/rdf4j-server/repositories/books

Keep your instance patched (sudo apt-get update && sudo apt-get upgrade), keep the admin password safe, 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

Eclipse and Eclipse RDF4J are trademarks of the Eclipse Foundation, Inc. Apache Tomcat is a trademark of the Apache Software Foundation. cloudimg is not affiliated with or endorsed by the Eclipse Foundation or the Apache Software Foundation.