Deploying Gel with Docker
.md
Copy page

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

When to use the "geldata/gel" Docker image

This image is primarily intended to be used directly when there is a requirement to use Docker containers, such as in production, or in a development setup that involves multiple containers orchestrated by Docker Compose or a similar tool. Otherwise, using the gel server CLI on the host system is the recommended way to install and run Gel servers.

How to use this image

The simplest way to run the image (without data persistence) is this:

Copy

docker run --name gel -d \
  -e GEL_SERVER_SECURITY=insecure_dev_mode \
  geldata/gel

See the Configuration section below for the meaning of the GEL_SERVER_SECURITY variable and other options.

Then, to authenticate to the Gel instance and store the credentials in a Docker volume, run:

Copy

docker run -it --rm --link=gel \
  -e GEL_SERVER_PASSWORD=secret \
  -v gel-cli-config:/.config/edgedb geldata/gel-cli \
  -H gel instance link my_instance \
      --tls-security insecure \
      --non-interactive

Now, to open an interactive shell to the database instance run this:

Copy

docker run -it --rm --link=gel \
  -v gel-cli-config:/.config/edgedb geldata/gel-cli \
  -I my_instance

Data Persistence

If you want the contents of the database to survive container restarts, you must mount a persistent volume at the path specified by GEL_SERVER_DATADIR (/var/lib/gel/data by default). For example:

Copy

docker run \
  --name gel \
  -e GEL_SERVER_PASSWORD=secret \
  -e GEL_SERVER_TLS_CERT_MODE=generate_self_signed \
  -v /my/data/directory:/var/lib/gel/data \
  -d geldata/gel

Note that on Windows you must use a Docker volume instead:

Copy

docker volume create --name=gel-data

Copy

docker run \
  --name gel \
  -e GEL_SERVER_PASSWORD=secret \
  -e GEL_SERVER_TLS_CERT_MODE=generate_self_signed \
  -v gel-data:/var/lib/gel/data \
  -d geldata/gel

It is also possible to run a gel container on a remote PostgreSQL cluster specified by GEL_SERVER_BACKEND_DSN. See below for details.

Schema Migrations

A derived image may include application schema and migrations in /dbschema, in which case the container will attempt to apply the schema migrations found in /dbschema/migrations, unless the GEL_DOCKER_APPLY_MIGRATIONS environment variable is set to never.

Docker Compose

A simple docker-compose configuration might look like this. With a docker-compose.yaml containing:

Copy

services:
  gel:
    image: geldata/gel
    environment:
      GEL_SERVER_SECURITY: insecure_dev_mode
    volumes:
      - "./dbschema:/dbschema"
    ports:
      - "5656:5656"

Once there is a schema in dbschema/ a migration can be created with:

Copy

gel --tls-security=insecure -P 5656 migration create

Alternatively, if you don't have the Gel CLI installed on your host machine, you can use the CLI bundled with the server container:

Copy

docker compose exec gel \
  gel --tls-security=insecure -P 5656 migration create

Configuration

The Docker image supports the same set of enviroment variables as the Gel server process, which are documented under Reference > Environment Variables.

Gel containers can be additionally configured using initialization scripts and some Docker-specific environment variables, documented below.

Some variables support _ENV and _FILE variants to support more advanced configurations.

Initial configuration

When a Gel container starts on the specified data directory or remote Postgres cluster for the first time, initial instance setup is performed. This is called the bootstrap phase.

The following environment variables affect the bootstrap only and have no effect on subsequent container runs.

For EdgeDB versions before 6.0 (Gel) the prefix for all environment variables is EDGEDB_ instead of GEL_.

GEL_SERVER_BOOTSTRAP_COMMAND

Useful to fine-tune initial user and branch creation, and other initial setup. If neither the GEL_SERVER_BOOTSTRAP_COMMAND variable or the GEL_SERVER_BOOTSTRAP_SCRIPT_FILE are explicitly specified, the container will look for the presence of /gel-bootstrap.edgeql in the container (which can be placed in a derived image).

Maps directly to the gel-server flag --bootstrap-command. The *_FILE and *_ENV variants are also supported.

GEL_SERVER_BOOTSTRAP_SCRIPT_FILE

Deprecated in image version 2.8: use GEL_SERVER_BOOTSTRAP_COMMAND_FILE instead.

Run the script when initializing the database. The script is run by default user within default branch.

GEL_SERVER_PASSWORD

The password for the default superuser account will be set to this value. If no value is provided a password will not be set, unless set via GEL_SERVER_BOOTSTRAP_COMMAND. (If a value for GEL_SERVER_BOOTSTRAP_COMMAND is provided, this variable will be ignored.)

The *_FILE and *_ENV variants are also supported.

GEL_SERVER_PASSWORD_HASH

A variant of GEL_SERVER_PASSWORD, where the specified value is a hashed password verifier instead of plain text.

If GEL_SERVER_BOOTSTRAP_COMMAND is set, this variable will be ignored.

The *_FILE and *_ENV variants are also supported.

GEL_SERVER_GENERATE_SELF_SIGNED_CERT

Deprecated: use GEL_SERVER_TLS_CERT_MODE=generate_self_signed instead.

Set this option to 1 to tell the server to automatically generate a self-signed certificate with key file in the GEL_SERVER_DATADIR (if present, see below), and echo the certificate content in the logs. If the certificate file exists, the server will use it instead of generating a new one.

Self-signed certificates are usually used in development and testing, you should likely provide your own certificate and key file with the variables below.

GEL_SERVER_TLS_CERT/GEL_SERVER_TLS_KEY

The TLS certificate and private key data, exclusive with GEL_SERVER_TLS_CERT_MODE=generate_self_signed.

The *_FILE and *_ENV variants are also supported.

Custom scripts in "/docker-entrypoint.d/"

To perform additional initialization, a derived image may include one or more executable files in /docker-entrypoint.d/, which will get executed by the container entrypoint before any other processing takes place.

Runtime configuration

GEL_DOCKER_LOG_LEVEL

Determines the log verbosity level in the entrypoint script. Valid levels are trace, debug, info, warning, and error. The default is info.

Custom scripts in "/gel-bootstrap.d/" and "/gel-bootstrap-late.d"

To perform additional initialization, a derived image may include one or more *.edgeql or *.sh scripts, which are executed in addition to and after the initialization specified by the environment variables above or the /gel-bootstrap.edgeql script. Parts in /gel-bootstrap.d are executed before any schema migrations are applied, and parts in /gel-bootstrap-late.d are executed after the schema migration have been applied.

Best practice for naming your script files when you will have multiple script files to run on bootstrap is to prepend the filenames with 01-, 02-, and so on to indicate your desired order of execution.

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 container hostname or IP address. In Docker Compose, this is the service name (e.g., gel). For standalone containers, use localhost if on the same host, or the container's IP/hostname.
Port: 5656 (the default Gel port, unless remapped with -p)
Username: admin (the default superuser)
Password: The value of GEL_SERVER_PASSWORD you set when starting the container
Branch: main (the default branch)

Construct the DSN using these values:

Copy

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

For a Docker Compose setup with the service named gel:

Copy

GEL_DSN="gel://admin:secret@gel: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.

Retrieve the certificate from the running container:

Copy

docker exec <container-name> cat /var/lib/gel/data/edbtlscert.pem

Or using the Gel utility script:

Copy

docker exec <container-name> \
  gel-show-secrets.sh --format=raw GEL_SERVER_TLS_CERT

Alternatively, retrieve it using the Gel CLI:

Copy

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

If you mounted a persistent volume at GEL_SERVER_DATADIR, the certificate is also available at <volume-path>/edbtlscert.pem.

Using in your application

Set these environment variables in your application container:

Copy

# docker-compose.yaml example
services:
  app:
    image: your-app
    environment:
      GEL_DSN: "gel://admin:secret@gel:5656"
      # For self-signed certificates:
      GEL_CLIENT_TLS_SECURITY: "insecure"
      # Or provide the CA certificate:
      # GEL_TLS_CA: "<certificate content>"

For production, we recommend providing the TLS certificate rather than disabling TLS verification:

Copy

services:
  app:
    image: your-app
    environment:
      GEL_DSN: "gel://admin:${GEL_PASSWORD}@gel:5656"
      GEL_TLS_CA_FILE: "/certs/gel-ca.pem"
    volumes:
      - ./certs:/certs:ro

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

Local development with the CLI

To make your Gel container 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.

From your host machine, link to the container:

Copy

gel instance link \
  --dsn gel://admin:secret@localhost:5656 \
  --non-interactive \
  --trust-tls-cert \
  my_docker_instance

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

Copy

gel -I my_docker_instance

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

Or apply migrations:

Copy

gel -I my_docker_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 with Docker​.mdCopy page

When to use the "geldata/gel" Docker image​

How to use this image​

Data Persistence​

Schema Migrations​

Docker Compose​

Configuration​

Initial configuration​

GEL_SERVER_BOOTSTRAP_COMMAND​

GEL_SERVER_BOOTSTRAP_SCRIPT_FILE​

GEL_SERVER_PASSWORD​

GEL_SERVER_PASSWORD_HASH​

GEL_SERVER_GENERATE_SELF_SIGNED_CERT​

GEL_SERVER_TLS_CERT/GEL_SERVER_TLS_KEY​

Custom scripts in "/docker-entrypoint.d/"​

Runtime configuration​

GEL_DOCKER_LOG_LEVEL​

Custom scripts in "/gel-bootstrap.d/" and "/gel-bootstrap-late.d"​

Connecting your application​

Obtaining connection parameters​

Obtaining the TLS certificate​

Using in your application​

Local development with the CLI​

Health Checks​

Deploying Gel with Docker
.md
Copy page

When to use the "geldata/gel" Docker image

How to use this image

Data Persistence

Schema Migrations

Docker Compose

Configuration

Initial configuration

GEL_SERVER_BOOTSTRAP_COMMAND

GEL_SERVER_BOOTSTRAP_SCRIPT_FILE

GEL_SERVER_PASSWORD

GEL_SERVER_PASSWORD_HASH

GEL_SERVER_GENERATE_SELF_SIGNED_CERT

GEL_SERVER_TLS_CERT/GEL_SERVER_TLS_KEY

Custom scripts in "/docker-entrypoint.d/"

Runtime configuration

GEL_DOCKER_LOG_LEVEL

Custom scripts in "/gel-bootstrap.d/" and "/gel-bootstrap-late.d"

Connecting your application

Obtaining connection parameters

Obtaining the TLS certificate

Using in your application

Local development with the CLI

Health Checks