graphql-engine/docs/graphql/manual/deployment/graphql-engine-flags/config-examples.rst

GraphQL engine server config examples
=====================================

.. contents:: Table of contents
  :backlinks: none
  :depth: 1
  :local:

The following are a few configuration use cases:

.. _add-access-key:

Add an access key
-----------------

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

Run server in this mode using following docker command:

.. code-block:: bash

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

Typically, you will also have a webhook for authentication:

.. code-block:: bash

   docker run -P -d hasura/graphql-engine:latest graphql-engine \
              --database-url postgres://username:password@host:5432/dbname \
                serve \
                --access-key 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 access key you will use the ``HASURA_GRAPHQL_ACCESS_KEY``
and for the webhook, you will use the ``HASURA_GRAPHQL_AUTH_HOOK`` environment variables.

.. _cli-with-access-key:

Using CLI commands with access key
----------------------------------

When you start the GraphQL Engine with an access key, CLI commands will also
need this access key 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 ``access_key``:

.. code-block:: yaml

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

The console can now contact the GraphQL APIs with the specified access key.

.. note::

   If you're setting ``access_key`` in ``config.yaml`` please make sure you do
   not check this file into a public repository.

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

.. code-block:: bash

   export HASURA_GRAPHQL_ACCESS_KEY=xxxxx
   hasura console

   # OR in a single line
   HASURA_GRAPHQL_ACCESS_KEY=xxxxx hasura console

You can also set the access key using a flag to the command:

.. code-block:: bash

   hasura console --access-key=XXXXXXXXXXXX


.. note::

   The order of precedence for access key and endpoint is as follows:

   CLI flag > Environment variable > Config file

.. _configure-cors:

Configure CORS
--------------

By default, all CORS requests to 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.

Scheme + host with optional wildcard + optional port has to be mentioned.

Examples:

.. code-block:: bash

    # 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"


.. note::

  Top-level domains are not considered as part of wildcard domains. You
  have to add them separately. E.g - ``https://*.foo.com`` doesn't include
  ``https://foo.com``.