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

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

The following are a few configuration use cases:

.. _add-admin-secret:

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:

.. code-block:: bash

   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:

.. code-block:: bash

   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.

.. _cli-with-admin-secret:

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``:

.. code-block:: yaml

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

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

.. note::

   If you're setting ``admin_secret`` 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 admin secret value to the command
as an environment variable:

.. code-block:: bash

   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:

.. code-block:: bash

   hasura console --admin-secret=XXXXXXXXXXXX


.. note::

   The order of precedence for admin secret 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``.


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.

.. _console-assets-on-server:

Load console assets from server instead of CDN
----------------------------------------------

Starting with ``v1.0.0-beta.01``, the static assets (js, css, fonts, img etc.)
required by the console 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 server/console to load assets from the
docker image itself, instead of the CDN.

Set the following env var or flag on the server:

.. code-block:: bash

   # 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 ``/srv/console-assets`` directory of the
Docker image will be served at ``/console/assets`` endpoint on the server with
the right content-type headers.

.. note::

   Hasura follows a rolling update pattern for console release where assets for
   a ``major.minor`` version is updated continuously across all patches. If
   you're using the assets on server Docker image, it might not be that latest
   version of console.