GraphQL Engine Server Configuration
Introduction
You can customize the configuration of the Hasura GraphQL Engine using either server flags or environment variables.
See the Server config reference for the list of all available flags and environment variables that can be configured.
Setting server configurations
Using flags
You can configure self-hosted Hasura GraphQL Engine instances by setting flags on the graphql-engine command and the
serve sub-command.
The graphql-engine command
The graphql-engine command has a limited number of flags and environment variables; these pertain directly to the
databases used in your project.
Every graphql-engine command is structured as:
$ graphql-engine <server-flags>
As an example, we can set the metadata database url for a project using a flag:
$ graphql-engine --metadata-database-url "postgres://<user>:<password>@<host>:<port>/<db-name>"
The serve sub-command
The serve sub-command provides opportunities to further customize Hasura's configuration.
Building on the previous example, we can set the port by which Hasura is served by pairing the serve sub-command with
the --port flag and assigning a value:
$ graphql-engine --metadata-database-url "postgres://user:password@host:port/db-name" serve --port 3000
The following options can be configured via flags only:
--host Postgres server host
-p, --port Postgres server port
-u, --user Database user name
-p, --password Password of the user
-d, --dbname Database name to connect to
-o, --pg-connection-options PostgreSQL connection options
All other flags can also be passed as environment variables.
Using environment variables
You can also use environment variables to configure the Hasura GraphQL Engine. As an example, if you're using
Docker on a self-hosted instance, you can set these values by modifying your
docker-compose.yaml file used to run Hasura:
# docker-compose.yaml
version: '3.6'
services:
postgres:
image: postgres:12
restart: always
volumes:
- db_data:/var/lib/postgresql/data
environment:
POSTGRES_PASSWORD: postgrespassword
graphql-engine:
image: hasura/graphql-engine:v2.15.0
ports:
- '8080:8080'
depends_on:
- 'postgres'
restart: always
environment:
## postgres database to store Hasura metadata
HASURA_GRAPHQL_METADATA_DATABASE_URL: postgres://postgres:postgrespassword@postgres:5432/postgres
## this env var can be used to add the above postgres database to Hasura as a data source. this can be removed/updated based on your needs
PG_DATABASE_URL: postgres://postgres:postgrespassword@postgres:5432/postgres
## enable the console served by server
HASURA_GRAPHQL_ENABLE_CONSOLE: 'true' # set to "false" to disable console
## enable debugging mode. It is recommended to disable this in production
HASURA_GRAPHQL_DEV_MODE: 'true'
HASURA_GRAPHQL_ENABLED_LOG_TYPES: startup, http-log, webhook-log, websocket-log, query-log
## uncomment next line to run console offline (i.e load console assets from server instead of CDN)
# HASURA_GRAPHQL_CONSOLE_ASSETS_DIR: /srv/console-assets
## uncomment next line to set an admin secret
# HASURA_GRAPHQL_ADMIN_SECRET: myadminsecretkey
volumes:
db_data:
Alternatively, if you're using Hasura Cloud, you can set and add environment variables from a project's dashboard:
When the equivalent flags for environment variables are used, the flags will take precedence.
When adding or updating environment variables on Hasura Cloud, you will not need to restart your project and there will be no downtime.
Use cases
The following are a few configuration use cases:
