Deploying Gel to Azure
.md
Copy page

In this guide we show how to deploy Gel using Azure's Postgres Flexible Server as the backend.

Gel Cloud: Reset the default password for the admin role

If you want to dump an existing Gel Cloud instance and restore it to a new self-managed instance, you need to change the automatically generated password for the default admin role - edgedb or admin. The administrator role name and its password used in the dump/restore process must be the same in both the instance dumped from and the instance restored to for the Gel tooling to continue functioning properly. To change the default password in the Cloud instance, execute the following query in the instance:

Copy

ALTER ROLE admin { set password := 'new_password' };

Prerequisites

Valid Azure Subscription with billing enabled or credits (free trial).
Azure CLI (install).

Provision a Gel instance

Copy

az login

Create a new resource group.

Copy

GROUP=my-group-name

Copy

az group create --name $GROUP --location westus

Provision a PostgreSQL server.

If you already have a database provisioned you can skip this step.

For convenience, assign a value to the PG_SERVER_NAME environment variable; we'll use this variable in multiple later commands.

Copy

PG_SERVER_NAME=postgres-for-gel

Use the read command to securely assign a value to the PASSWORD environment variable.

Copy

echo -n "> " && read -s PASSWORD

Then create a Postgres Flexible server.

Copy

az postgres flexible-server create \
  --resource-group $GROUP \
  --name $PG_SERVER_NAME \
  --location westus \
  --admin-user gel_admin \
  --admin-password $PASSWORD \
  --sku-name Standard_D2s_v3 \
  --version 14 \
  --yes

If you get an error saying "Specified server name is already used." change the value of PG_SERVER_NAME and rerun the command.

Allow other Azure services access to the Postgres instance.

Copy

az postgres flexible-server firewall-rule create \
  --resource-group $GROUP \
  --name $PG_SERVER_NAME \
  --rule-name allow-azure-internal \
  --start-ip-address 0.0.0.0 \
  --end-ip-address 0.0.0.0

Gel requires Postgres' uuid-ossp extension which needs to be enabled.

Copy

az postgres flexible-server parameter set \
  --resource-group $GROUP \
  --server-name $PG_SERVER_NAME \
  --name azure.extensions \
  --value uuid-ossp

Azure is not able to reliably pull docker images because of rate limits, so you will need to provide docker hub login credentials to create a container. If you don't already have a docker hub account you can create one here.

Copy

echo -n "docker user> " && read -s DOCKER_USER

Copy

echo -n "docker password> " && read -s DOCKER_PASSWORD

Start a Gel container.

Copy

PG_HOST=$(
  az postgres flexible-server list \
    --resource-group $GROUP \
    --query "[?name=='$PG_SERVER_NAME'].fullyQualifiedDomainName | [0]" \
    --output tsv
)

Copy

DSN="postgresql://gel_admin:$PASSWORD@$PG_HOST/postgres?sslmode=require"

Copy

az container create \
  --registry-username $DOCKER_USER \
  --registry-password $DOCKER_PASSWORD \
  --registry-login-server index.docker.io \
  --os-type Linux \
  --cpu 1 \
  --memory 1 \
  --resource-group $GROUP \
  --name gel-container-group \
  --image geldata/gel \
  --dns-name-label geldb \
  --ports 5656 \
  --secure-environment-variables \
    "GEL_SERVER_PASSWORD=$PASSWORD" \
    "GEL_SERVER_BACKEND_DSN=$DSN" \
  --environment-variables \
    GEL_SERVER_TLS_CERT_MODE=generate_self_signed

Persist the SSL certificate. We have configured Gel to generate a self signed SSL certificate when it starts. However, if the container is restarted a new certificate would be generated. To preserve the certificate across failures or reboots copy the certificate files and use their contents in the GEL_SERVER_TLS_KEY and GEL_SERVER_TLS_CERT environment variables.

Copy

key="$( az container exec \
          --resource-group $GROUP \
          --name gel-container-group \
          --exec-command "cat /tmp/gel/edbprivkey.pem" \
        | tr -d "\r" )"

Copy

cert="$( az container exec \
           --resource-group $GROUP \
           --name gel-container-group \
           --exec-command "cat /tmp/gel/edbtlscert.pem" \
        | tr -d "\r" )"

Copy

az container delete \
  --resource-group $GROUP \
  --name gel-container-group \
  --yes

Copy

az container create \
  --registry-username $DOCKER_USER \
  --registry-password $DOCKER_PASSWORD \
  --registry-login-server index.docker.io \
  --os-type Linux \
  --cpu 1 \
  --memory 1 \
  --resource-group $GROUP \
  --name gel-container-group \
  --image geldata/gel \
  --dns-name-label geldb \
  --ports 5656 \
  --secure-environment-variables \
    "GEL_SERVER_PASSWORD=$PASSWORD" \
    "GEL_SERVER_BACKEND_DSN=$DSN" \
    "GEL_SERVER_TLS_KEY=$key" \
  --environment-variables \
    "GEL_SERVER_TLS_CERT=$cert"

Connecting your application

To connect your application to the Gel instance, you'll need to provide connection parameters. Gel client libraries can be configured using either a DSN (connection string) or individual environment variables.

Obtaining connection parameters

Your connection requires the following components:

Host: The FQDN of your Azure container instance. Retrieve it with:

Copy

az container list \
  --resource-group $GROUP \
  --query "[?name=='gel-container-group'].ipAddress.fqdn | [0]" \
  --output tsv

Port: 5656 (the default Gel port)
Username: admin (the default superuser)
Password: The password you set in the $PASSWORD variable
Branch: main (the default branch)

Construct the DSN using these values:

Copy

GEL_HOST=$(az container list \
  --resource-group $GROUP \
  --query "[?name=='gel-container-group'].ipAddress.fqdn | [0]" \
  --output tsv)

Copy

GEL_DSN="gel://admin:$PASSWORD@$GEL_HOST:5656"

Obtaining the TLS certificate

Since we configured Gel with a self-signed TLS certificate, your application needs the certificate to connect securely. Retrieve it from the container:

Copy

az container exec \
  --resource-group $GROUP \
  --name gel-container-group \
  --exec-command "cat /tmp/gel/edbtlscert.pem" \
| tr -d "\r" > gel-tls-cert.pem

Alternatively, you can retrieve it using the Gel CLI:

Copy

gel --dsn $GEL_DSN --tls-security insecure \
  query "SELECT sys::get_tls_certificate()" > gel-tls-cert.pem

Using in your application

Set these environment variables where you deploy your application:

Copy

GEL_DSN="gel://admin:<password>@<hostname>:5656"
# For self-signed certificates, either trust the cert:
GEL_TLS_CA_FILE="/path/to/gel-tls-cert.pem"
# Or (for development only) disable TLS verification:
GEL_CLIENT_TLS_SECURITY=insecure

Gel's client libraries will automatically read these environment variables.

Local development with the CLI

To make your remote instance easier to work with during local development, create an alias using gel instance link.

The command groups gel instance and gel project are not intended to manage production instances.

Copy

printf $PASSWORD | gel instance link \
  --dsn $GEL_DSN \
  --password-from-stdin \
  --non-interactive \
  --trust-tls-cert \
  my_azure_instance

You can now refer to the remote instance using the alias my_azure_instance. Use this alias wherever an instance name is expected:

Copy

gel -I my_azure_instance

Gel x.x
Type \help for help, \quit to quit.
gel>

Or apply migrations:

Copy

gel -I my_azure_instance migrate

Health Checks

Using an HTTP client, you can perform health checks to monitor the status of your Gel instance. Learn how to use them with our health checks guide.

Deploying Gel to Azure​.mdCopy page

Prerequisites​

Provision a Gel instance​

Connecting your application​

Obtaining connection parameters​

Obtaining the TLS certificate​

Using in your application​

Local development with the CLI​

Health Checks​

Deploying Gel to Azure
.md
Copy page

Prerequisites

Provision a Gel instance

Connecting your application

Obtaining connection parameters

Obtaining the TLS certificate

Using in your application

Local development with the CLI

Health Checks