Gel (formerly EdgeDB) on AWS User Guide

Overview

Gel, formerly EdgeDB, is an open source graph-relational database built on top of PostgreSQL. You describe your data as typed object types with links and properties in a declarative schema, evolve it through versioned migrations, and query it with EdgeQL, a composable query language that returns rich, deeply nested results without hand written joins. Gel ships a built-in web administration interface, the Gel UI, with a schema browser, an interactive REPL and a data explorer. The cloudimg image installs Gel 7 from the official package repository, runs the server as the packaged gel-server-7 systemd service bound to loopback, fronts the Gel UI behind an nginx reverse proxy on TCP 80 with HTTP Basic auth, and generates a fresh database instance with a unique superuser password, TLS certificate and reverse-proxy password on the first boot of every instance. A small demo schema and data set are seeded so the schema browser and data explorer are populated the moment you sign in. Backed by 24/7 cloudimg support.

What is included:

• Gel 7 installed from the official packages.geldata.com repository, running as the gel-server-7 systemd service (data directory /var/lib/gel/7/data, PostgreSQL backend)
• The built-in Gel UI (schema browser, EdgeQL REPL, data explorer) fronted by nginx on :80
• nginx HTTP Basic auth as an outer gate on the UI, with a per-instance password in a root-only file
• The Gel server bound to loopback only (127.0.0.1:5656, HTTPS) and reached solely through the reverse proxy
• A per-instance superuser password, TLS certificate and reverse-proxy password, generated fresh on the first boot of every instance and never baked into the image
• A seeded demo schema (a Person and Movie object type with links) recorded as a real migration
• gel-server-7.service + nginx.service as systemd units, enabled and active
• 24/7 cloudimg support

Prerequisites

An AWS account, an EC2 key pair in the target region, and a VPC subnet. m5.large (2 vCPU / 8 GiB RAM) is a good starting point; scale up for larger workloads. Security group inbound: allow 22/tcp from your management network and 80/tcp for the Gel UI (front with TLS for public exposure - see Enabling HTTPS). The database port 5656 stays bound to loopback and is never exposed.

Step 1 - Launch from AWS Marketplace

In the AWS Marketplace console, search for Gel by cloudimg and choose Continue to Subscribe, then Continue to Configuration and Continue to Launch. Pick the m5.large instance type, your VPC subnet and key pair, and a security group that allows inbound 22 and 80. Launch the instance.

Step 2 - Launch from the AWS CLI

aws ec2 run-instances \
  --image-id <ami-id-from-listing> \
  --instance-type m5.large \
  --key-name <your-key-pair> \
  --security-group-ids <sg-allowing-22-and-80> \
  --subnet-id <your-subnet> \
  --tag-specifications 'ResourceType=instance,Tags=[{Key=Name,Value=gel}]'

Connecting to your instance

Connect over SSH as the default login user for your operating system variant. This listing currently ships the following variant:

ssh ubuntu@<public-ip>

Step 3 - Confirm the services are running

systemctl is-active gel-server-7 nginx

Both services report active. The Gel server bootstraps a fresh instance on the first boot and applies the seeded migration; on later boots it starts in a few seconds.

Step 4 - Retrieve your credentials

The superuser password, the Gel UI reverse-proxy password and the URLs are generated uniquely on the first boot of your instance and written to a root-only file. Read it with:

sudo cat /root/gel-credentials.txt

This file contains:

• GEL_ADMIN_USER (admin) and GEL_ADMIN_PASSWORD - the Gel superuser, used to sign in to the Gel UI and to run EdgeQL
• GEL_UI_USER and GEL_UI_PASSWORD - the outer nginx HTTP Basic auth credentials that gate the Gel UI
• GEL_URL - the Gel UI address for this instance

The file is root-only; you can confirm its permissions and non-secret fields without printing the passwords:

sudo stat -c 'permissions=%a owner=%U:%G' /root/gel-credentials.txt
sudo grep -E '^(GEL_ADMIN_USER|GEL_URL)=' /root/gel-credentials.txt

Store the passwords somewhere safe.

Step 5 - Check the health endpoint and the network shape

nginx serves an unauthenticated health endpoint for load balancers and probes, while the database itself stays bound to loopback behind the auth wall:

curl -s http://localhost/health; echo

It returns ok. The Gel server listens only on 127.0.0.1:5656, and any request to the UI without the Basic-auth credentials is refused with 401:

sudo ss -tlnp | grep -E '127.0.0.1:5656|:80 ' || true
curl -s -o /dev/null -w 'unauthenticated /ui/ -> HTTP %{http_code}\n' http://localhost/ui/

Step 6 - Sign in to the Gel UI

Browse to http://<public-ip>/ui. Your browser first prompts for the nginx Basic-auth credentials - enter GEL_UI_USER and GEL_UI_PASSWORD from Step 4. The Gel UI then presents its own sign-in screen: log in as admin with GEL_ADMIN_PASSWORD.

Step 7 - The Gel UI dashboard

After signing in you land on the instance dashboard, which lists the database branches (the image ships the main branch) and links to the Gel documentation.

Step 8 - Browse the typed schema

Open the main branch, then the Schema view. The image ships a seeded schema with a Person type and a Movie type that links to a director and multiple actors. The schema browser shows both the declarative SDL and an entity graph.

The same schema is visible from the CLI:

PW=$(sudo grep '^GEL_ADMIN_PASSWORD=' /root/gel-credentials.txt | cut -d= -f2-)
printf '%s\n' "$PW" | gel --host 127.0.0.1 --port 5656 --user admin --tls-security insecure --password-from-stdin query 'select schema::ObjectType { name } filter .name like "default::%";'

Step 9 - Query with EdgeQL

Use the built-in REPL to run EdgeQL. EdgeQL returns rich, nested results directly - here every movie with its release year, its director and its cast, in one query with no joins:

You can run the same EdgeQL from the CLI. The gel client connects to the local server over the self-signed instance certificate:

PW=$(sudo grep '^GEL_ADMIN_PASSWORD=' /root/gel-credentials.txt | cut -d= -f2-)
printf '%s\n' "$PW" | gel --host 127.0.0.1 --port 5656 --user admin --tls-security insecure --password-from-stdin query 'select Movie { title, release_year, director: { name } } order by .release_year;'

Step 10 - Explore the data

The Data Explorer shows the seeded objects in a grid, with the typed columns and links:

Step 11 - Insert and persist data

Mutations are ordinary EdgeQL. Insert a new object and confirm the count changes (run these on your instance):

PW=$(sudo grep '^GEL_ADMIN_PASSWORD=' /root/gel-credentials.txt | cut -d= -f2-)
printf '%s\n' "$PW" | gel --host 127.0.0.1 --port 5656 --user admin --tls-security insecure --password-from-stdin query "insert Person { name := 'Ada Lovelace' };"
printf '%s\n' "$PW" | gel --host 127.0.0.1 --port 5656 --user admin --tls-security insecure --password-from-stdin query 'select count(Person);'

Data is stored in the PostgreSQL-backed instance under /var/lib/gel/7/data and persists across service restarts and reboots.

Step 12 - Connect an application

Gel provides client libraries for the popular languages. Point a client at the server with the superuser credentials (or create a dedicated role for the application). For example, in Python:

pip install gel

import gel
client = gel.create_client(
    host="127.0.0.1", port=5656,
    user="admin", password="<GEL_ADMIN_PASSWORD>",
    tls_security="insecure",   # self-signed per-instance cert; supply the cert for production
)
print(client.query("select Movie { title } order by .release_year"))

For production, connect over the instance's TLS certificate (found in the data directory) rather than tls_security="insecure", and create a least-privilege role for the application instead of using the superuser.

Step 13 - Enabling HTTPS with your own domain

For public exposure, point a DNS record at the instance and terminate TLS at nginx with a real certificate:

sudo apt-get install -y certbot python3-certbot-nginx
sudo certbot --nginx -d gel.your-domain.com

The database and the Gel UI already run over the loopback interface behind nginx, so adding a public certificate is all that is required to serve the UI over HTTPS.

Step 14 - Maintenance

• Credentials: re-read them any time with sudo cat /root/gel-credentials.txt.
• Service management: sudo systemctl status gel-server-7 nginx, and sudo systemctl restart gel-server-7 to restart the database.
• Logs: sudo journalctl -u gel-server-7 -n 100 --no-pager.
• Backups: back up the data directory /var/lib/gel/7/data, or use gel dump to export a branch.
• Updates: the OS receives security updates; upgrade Gel with sudo apt-get update && sudo apt-get install --only-upgrade gel-server-7.

Support

Backed by 24/7 cloudimg support. Email support@cloudimg.co.uk with your instance ID and AWS region for deployment guidance, schema modelling and EdgeQL help, migrations, client connectivity, TLS termination, backups and Gel version upgrades.