Search...
ctrl/
Light
Dark
System
Sign in

Deploying Gel with Docker​

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/gel geldata/gel-cli \
  -H gel instance link my_instance


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


Copy
$ 
  
  
docker run -it --rm --link=gel \
  -v gel-cli-config:/.config/gel 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 an 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
version: "3"
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 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 an 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.












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.