mirror of
https://github.com/hasura/graphql-engine.git
synced 2024-12-17 20:41:49 +03:00
a80b632568
Co-authored-by: Rikin Kachhia <54616969+rikinsk@users.noreply.github.com> GitOrigin-RevId: bb378baee249334f4bc0add43e364dbad6a7284f
282 lines
9.6 KiB
ReStructuredText
282 lines
9.6 KiB
ReStructuredText
.. meta::
|
|
:description: Examples of server configurations with Hasura GraphQL engine
|
|
:keywords: hasura, docs, deployment, flags, server, server configuration, example
|
|
|
|
.. _config_examples:
|
|
|
|
GraphQL engine 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.
|
|
|
|
.. _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 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 ``extensions`` key is not sent in the ``errors`` response. 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
|
|
|
|
If you want the debugging mode enabled only for ``admin`` role requests, configure as follows instead of the above:
|
|
|
|
.. code-block:: bash
|
|
|
|
# env var
|
|
HASURA_GRAPHQL_ADMIN_INTERNAL_ERRORS=true
|
|
|
|
# flag
|
|
--admin-internal-errors
|
|
|
|
.. note::
|
|
|
|
It is highly recommended to enable debugging only for the ``admin`` role in production.
|
|
|
|
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
|