Search
ctrl+/
Ask AI
ctrl+.
Light
Dark
System
Sign in

Deploying Gel to a Bare Metal Server​
.md
Copy page

In this guide we show how to deploy Gel to bare metal using your system's package manager and systemd.

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' };

Install the Gel Package​

The steps for installing the Gel package will be slightly different depending on your Linux distribution. Once you have the package installed you can jump to Enable a systemd unit.

Debian/Ubuntu LTS​

Import the Gel packaging key.

Copy
$ 
  
  
  
sudo mkdir -p /usr/local/share/keyrings && \
  sudo curl --proto '=https' --tlsv1.2 -sSf \
  -o /usr/local/share/keyrings/gel-keyring.gpg \
  https://packages.geldata.com/keys/gel-keyring.gpg


Add the Gel package repository.


Copy
$ 
  
  
  
echo deb '[signed-by=/usr/local/share/keyrings/gel-keyring.gpg]' \
  https://packages.geldata.com/apt \
  $(grep "VERSION_CODENAME=" /etc/os-release | cut -d= -f2) main \
  | sudo tee /etc/apt/sources.list.d/gel.list




For non-LTS releases of Debian/Ubuntu (e.g. Ubuntu Oracular), one can install
                        package for latest LTS release, because they are usually forward compatible.
                        To do this, replace the $(grep ...) with the name of latest LTS release
                        (e.g. noble).




Install the Gel package.


Copy
$ 
sudo apt-get update && sudo apt-get install gel-6






CentOS/RHEL 7/8​


Add the Gel package repository.


Copy
$ 
  
  
sudo curl --proto '=https' --tlsv1.2 -sSfL \
 https://packages.geldata.com/rpm/gel-rhel.repo \
 > /etc/yum.repos.d/gel.repo


Install the Gel package.


Copy
$ 
sudo yum install gel-6


Disable SELinux.


Copy
$ 
sed -i 's/SELINUX=enforcing/SELINUX=disabled/' /etc/selinux/config
Copy
$ 
reboot









Enable a systemd unit​


The Gel package comes bundled with a systemd unit that is disabled by
                default. You can start the server by enabling the unit.


Copy
$ 
sudo systemctl enable --now gel-server-6


This will start the server on port 5656, and the data directory will be
                /var/lib/gel/6/data.




gel-server cannot be run as root.








Set environment variables​


To set environment variables when running Gel with systemctl,


Copy
$ 
systemctl edit --full gel-server-6


This opens a systemd unit file. Set the desired environment variables
                under the [Service] section. View the supported environment variables at
                Reference > Environment Variables.


Copy
[Service]
Environment="GEL_SERVER_TLS_CERT_MODE=generate_self_signed"
Environment="GEL_SERVER_ADMIN_UI=enabled"


Save the file and exit, then restart the service.


Copy
$ 
systemctl restart gel-server-6






Set a password​


There is no default password. To set one, you will first need to get the Unix
                socket directory. You can find this by looking at your system.d unit file.


Copy
$ 
sudo systemctl cat gel-server-6


Set a password by connecting from localhost.


Copy
$ 
echo -n "> " && read -s PASSWORD
Copy
$ 
  
  
RUNSTATE_DIR=$(systemctl show gel-server-6 -P ExecStart | \
 grep -o -m 1 -- "--runstate-dir=[^ ]\+" | \
 awk -F "=" '{print $2}')
Copy
$ 
  
  
sudo gel --port 5656 --tls-security insecure --admin \
 --unix-path $RUNSTATE_DIR \
 query "ALTER ROLE admin SET password := '$PASSWORD'"


The server listens on localhost by default. Changing this looks like this.


Copy
$ 
  
gel --port 5656 --tls-security insecure --password query \
 "CONFIGURE INSTANCE SET listen_addresses := {'0.0.0.0'};"


The listen port can be changed from the default 5656 if your deployment
                scenario requires a different value.


Copy
$ 
  
gel --port 5656 --tls-security insecure --password query \
 "CONFIGURE INSTANCE SET listen_port := 1234;"


You may need to restart the server after changing the listen port or addresses.


Copy
$ 
sudo systemctl restart gel-server-6






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 IP address or hostname of your server (e.g., localhost,
                            192.168.1.100, or gel.example.com)
    

    • 

  • 

    Port: 5656 by default, or the custom port if you changed it with
                            CONFIGURE INSTANCE SET listen_port
    

    • 

  • 

    Username: admin (the default superuser)
    

    • 

  • 

    Password: The password you set with ALTER ROLE admin SET password
    

    • 

  • 

    Branch: main (the default branch)
    

    • 



Construct the DSN using these values:


Copy
$ 
GEL_DSN="gel://admin:<password>@<hostname>:5656"






Obtaining the TLS certificate​


If you configured Gel with GEL_SERVER_TLS_CERT_MODE=generate_self_signed,
                    your application needs the certificate to connect securely.


The generated certificate is stored in the data directory. You can find it at:


Copy
$ 
cat /var/lib/gel/6/data/edbtlscert.pem


Alternatively, retrieve it using the Gel CLI:


Copy
$ 
  
gel --dsn $GEL_DSN --tls-security insecure \
  query "SELECT sys::get_tls_certificate()"






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, provide the CA cert:
GEL_TLS_CA_FILE="/path/to/edbtlscert.pem"
# Or embed the certificate content directly:
GEL_TLS_CA="<certificate content>"


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






Local development with the CLI​


To make your 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
$ 
  
  
  
  
gel instance link \
  --dsn $GEL_DSN \
  --non-interactive \
  --trust-tls-cert \
  my_bare_metal_instance


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


Copy
$ 
gel -I my_bare_metal_instance
Gel x.x
Type \help for help, \quit to quit.
gel>


Or apply migrations:


Copy
$ 
gel -I my_bare_metal_instance migrate








Upgrading Gel​


When you want to upgrade to the newest point release upgrade the package and
                restart the gel-server-6 unit.




Debian/Ubuntu LTS​


Copy
$ 
sudo apt-get update && sudo apt-get install --only-upgrade gel-6
Copy
$ 
sudo systemctl restart gel-server-6






CentOS/RHEL 7/8​


Copy
$ 
sudo yum update gel-6
Copy
$ 
sudo systemctl restart gel-server-6








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.