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

.. meta::
   :description: Examples of server configurations with Hasura GraphQL engine
   :keywords: hasura, docs, deployment, flags, server, server configuration, example

.. _config_examples:

Server config examples
======================

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

Introduction
------------

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.

.. hiding this as it mixes auth for the data plane with auth for the control plane and might be confusing

  .. admonition:: Using collaborators as an alternative to Hasura Admin Secret sharing with Hasura Cloud
    :class: dhc

    Hasura Cloud offers console collaborators which avoids sharing the `HASURA-ADMIN-SECRET` with those that shouldn't
    have unrestricted access to your project. For more information about collaborator management, see
    :ref:`Collaborators in Hasura Cloud <manage_project_collaborators>`.

.. _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 an ``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 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:

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

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:

.. 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 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.

.. note::

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

.. _dev-mode:

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 :doc:`action <../../actions/debugging>` requests.

By default the ``internal`` key is not sent in the ``extensions`` response (except for ``admin`` roles). To enable this,
start the GraphQL engine server in debugging mode with the following configuration:

.. code-block:: bash

   # env var
   HASURA_GRAPHQL_DEV_MODE=true

   # flag
   --dev-mode

The ``internal`` key is sent for ``admin`` role requests by default. To disable them, configure as follows:

.. code-block:: bash

   # env var
   HASURA_GRAPHQL_ADMIN_INTERNAL_ERRORS=false

   # flag
   --admin-internal-errors false

.. note::

   It is highly recommended to enable debugging only for the ``admin`` role in production.

.. _add-metadata-database:

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 separate database to store the 
``metadata catalogue``.

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

.. code-block:: bash

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

.. admonition:: Caveat for Hasura Cloud

  The metadata for Hasura Cloud projects is stored in dedicated metadata DBs managed by Hasura Cloud.
  Hence the ``HASURA_GRAPHQL_METADATA_DATABASE_URL`` cannot be configured on Hasura Cloud as its value is controlled
  by Hasura Cloud itself.

Possible configurations:
~~~~~~~~~~~~~~~~~~~~~~~~

**1. Both the** ``primary database`` **and**  ``metadata database`` **are provided to the server**

.. code-block:: bash

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

In this case, Hasura GraphQL engine will use the ``HASURA_GRAPHQL_METADATA_DATABASE_URL`` to store the ``metadata catalogue``
and starts the server with the database provided in the ``HASURA_GRAPHQL_DATABASE_URL``.

**2. Only** ``metadata database`` **is provided to the server**

.. code-block:: bash

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

In this case, Hasura GraphQL engine will use the ``HASURA_GRAPHQL_METADATA_DATABASE_URL`` to store the ``metadata catalogue``
and starts the server without tracking/managing any database. *i.e* a Hasura GraphQL server will be started with no database. The
user could then manually track/manage databases at a later time.

**3. Only** ``primary database`` **is provided to the server**

.. code-block:: bash

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

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

In this case, Hasura GraphQL engine server will start with the database provided in the ``HASURA_GRAPHQL_DATABASE_URL`` and will
also use the *same database* to store the ``metadata catalogue``.

**4. Neither** ``primary database`` **nor** ``metadata database`` **is provided to the server**

Hasura GraphQL engine will fail to startup and will throw an error

.. code-block:: bash

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