GraphQL engine server config examples¶

Introduction¶

The following are a few configuration use cases:

Add an admin secret¶

To add an admin secret to Hasura, pass the --admin-secret flag with a secret generated by you.

Run server in this mode using following docker command:

docker run -P -d hasura/graphql-engine:latest graphql-engine \
           --database-url postgres://username:password@host:5432/dbname \
             serve \
             --admin-secret XXXXXXXXXXXXXXXX

Typically, you will also have a webhook for authentication:

docker run -P -d hasura/graphql-engine:latest graphql-engine \
           --database-url postgres://username:password@host:5432/dbname \
             serve \
             --admin-secret XXXXXXXXXXXXXXXX
             --auth-hook https://myauth.mywebsite.com/user/session-info

In addition to flags, the GraphQL engine also accepts environment variables.

In the above case, for adding an admin secret you will use the HASURA_GRAPHQL_ADMIN_SECRET and for the webhook, you will use the HASURA_GRAPHQL_AUTH_HOOK environment variables.

Using CLI commands with admin secret¶

When you start the GraphQL engine with an admin secret key, CLI commands will also need this admin secret to contact APIs. It can be set in config.yaml or as an environment variable or as a flag to the command. For example, let’s look at the case of the console command:

In the my-project/config.yaml file, set a new key admin_secret:

# config.yaml
endpoint: https://my-graphql-endpoint.com
admin_secret: XXXXXXXXXXXXXXXX

The console can now contact the GraphQL APIs with the specified admin secret.

An alternate and safe way is to pass the admin secret value to the command as an environment variable:

export HASURA_GRAPHQL_ADMIN_SECRET=xxxxx
hasura console

# OR in a single line
HASURA_GRAPHQL_ADMIN_SECRET=xxxxx hasura console

You can also set the admin secret using a flag to the command:

hasura console --admin-secret=XXXXXXXXXXXX

Configure CORS¶

By default, all CORS requests to the Hasura GraphQL engine are allowed. To run with more restrictive CORS settings, use the --cors-domain flag or the HASURA_GRAPHQL_CORS_DOMAIN ENV variable. The default value is *, which means CORS headers are sent for all domains.

The scheme + host with optional wildcard + optional port have to be mentioned.

Examples:

# Accepts from https://app.foo.bar.com , https://api.foo.bar.com etc.
HASURA_GRAPHQL_CORS_DOMAIN="https://*.foo.bar.com"

# Accepts from https://app.foo.bar.com:8080 , http://api.foo.bar.com:8080,
# http://app.localhost, http://api.localhost, http://localhost:3000,
# http://example.com etc.
HASURA_GRAPHQL_CORS_DOMAIN="https://*.foo.bar.com:8080, http://*.localhost, http://localhost:3000, http://example.com"

# Accepts from all domain
HASURA_GRAPHQL_CORS_DOMAIN="*"

# Accepts only from http://example.com
HASURA_GRAPHQL_CORS_DOMAIN="http://example.com"

You can tell Hasura to disable handling CORS entirely via the --disable-cors flag. Hasura will not respond with CORS headers. You can use this option if you’re already handling CORS on a reverse proxy etc.

Run console offline (i.e load console assets from server instead of CDN)¶

Normally the static assets (js, css, fonts, img etc.) required by the console are loaded from a CDN. Starting with v1.0.0-beta.1, these assets are bundled with the Docker image published by Hasura. These files can be found at /srv/console-assets.

If you’re working in an environment with Hasura running locally and have no access to internet, you can configure the GraphQL engine to load assets from the Docker image itself, instead of the CDN.

Set the following env var or flag on the server:

# env var
HASURA_GRAPHQL_CONSOLE_ASSETS_DIR=/srv/console-assets

# flag
--console-assets-dir=/srv/console-assets

Once the flag is set, all files in the /srv/console-assets directory of the Docker image will be served at the /console/assets endpoint on the server with the right content-type headers.

Dev (debugging) mode¶

The Hasura GraphQL engine may provide additional information for each object in the extensions key of errors. The internal key contains error information including the generated SQL statement and exception information from Postgres. This can be highly useful, especially in the case of debugging errors in action requests.

By default the extensions key is not sent in the errors response. To enable this, start the GraphQL engine server in debugging mode with the following configuration:

# env var
HASURA_GRAPHQL_DEV_MODE=true

# flag
--dev-mode

If you want the debugging mode enabled only for admin role requests, configure as follows instead of the above:

# env var
HASURA_GRAPHQL_ADMIN_INTERNAL_ERRORS=true

# flag
--admin-internal-errors

Add a metadata database¶

The Hasura GraphQL engine when initialized, creates a schema called hdb_catalog in the Postgres database and initializes a few tables under it. This schema and the internal tables are generally termed as the metadata catalogue and is responsible to manage the internal state of the Hasura GraphQL engine.

By default, the metadata_catalogue is created inside the primary database provided by the user. But sometimes it might be more advantageous to segregate the primary database and the metadata database.

Hasura GraphQL engine provides a way to the users to provide an entirely seperate Database to store the metadata catalogue.

To add a metadata database, set the following environment variable or add the flag to the server executable

# env var
HASURA_GRAPHQL_METADATA_DATABASE_URL=postgres://<user>:<password>@<host>:<port>/<metadata-db-name>

# flag
--metadata-database-url=postgres://<user>:<password>@<host>:<port>/<metadata-db-name>

# env var
HASURA_GRAPHQL_METADATA_DATABASE_URL=postgres://<user>:<password>@<host>:<port>/<metadata-db-name>
HASURA_GRAPHQL_DATABASE_URL=postgres://<user>:<password>@<host>:<port>/<db-name>

# flag
--metadata-database-url=postgres://<user>:<password>@<host>:<port>/<metadata-db-name>
--database-url=postgres://<user>:<password>@<host>:<port>/<db-name>

# env var
HASURA_GRAPHQL_METADATA_DATABASE_URL=postgres://<user>:<password>@<host>:<port>/<metadata-db-name>

# flag
--metadata-database-url=postgres://<user>:<password>@<host>:<port>/<metadata-db-name>

# env var
HASURA_GRAPHQL_DATABASE_URL=postgres://<user>:<password>@<host>:<port>/<db-name>

# flag
--database-url=postgres://<user>:<password>@<host>:<port>/<db-name>

Fatal Error: Either of --metadata-database-url or --database-url option expected