mirror of
https://github.com/hasura/graphql-engine.git
synced 2024-12-18 13:02:11 +03:00
a27db0b658
There were 2 problems in the docs: 1. Extensions key is always sent in error responses. The `internal` key requires debug mode. 2. Admin role errors have the `internal` key by default PR-URL: https://github.com/hasura/graphql-engine-mono/pull/2550 GitOrigin-RevId: 4121f1ef45290896887be447a73f96b0d4e016b4
291 lines
10 KiB
ReStructuredText
291 lines
10 KiB
ReStructuredText
.. 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 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
|
|
|
|
.. 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>
|
|
|
|
Different Scenarios:
|
|
~~~~~~~~~~~~~~~~~~~~
|
|
|
|
**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
|