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

The following are a few configuration use cases:

- :ref:`add-access-key`
- :ref:`cli-with-access-key`
- :ref:`configure-cors`

.. _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 are allowed. To run Hasura with more restrictive CORS settings, use the ``--cors-domain`` flag.

For example:

.. 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
                --cors-domain https://mywebsite.com:8090