diff --git a/docs/graphql/manual/api-reference/index.rst b/docs/graphql/manual/api-reference/index.rst index e11b278b316e4..6087788e26c9b 100644 --- a/docs/graphql/manual/api-reference/index.rst +++ b/docs/graphql/manual/api-reference/index.rst @@ -1,3 +1,5 @@ +.. _api-reference: + API Reference ============= diff --git a/docs/graphql/manual/deployment/allow-list.rst b/docs/graphql/manual/deployment/allow-list.rst index e53a904c3f4fb..6a12e035a35f5 100644 --- a/docs/graphql/manual/deployment/allow-list.rst +++ b/docs/graphql/manual/deployment/allow-list.rst @@ -1,3 +1,5 @@ +.. _allow-list: + Allow-list for queries ====================== diff --git a/docs/graphql/manual/deployment/compression.rst b/docs/graphql/manual/deployment/compression.rst index 787c077ce1f84..38c9099af4364 100644 --- a/docs/graphql/manual/deployment/compression.rst +++ b/docs/graphql/manual/deployment/compression.rst @@ -1,3 +1,5 @@ +.. _http-compression: + HTTP Compression ================ diff --git a/docs/graphql/manual/deployment/enable-https.rst b/docs/graphql/manual/deployment/enable-https.rst new file mode 100644 index 0000000000000..e8d459bc13823 --- /dev/null +++ b/docs/graphql/manual/deployment/enable-https.rst @@ -0,0 +1,75 @@ +.. _enable-https: + +Enable HTTPS +============ + +.. contents:: Table of contents + :backlinks: none + :depth: 2 + :local: + +Setting up HTTPS +---------------- + +Hasura GraphQL engine does not handle SSL/TLS for your API. That means, Hasura GraphQL engine cannot serve +your API on an HTTPS URL. + +You should use a reverse proxy (like Nginx, Caddy, +Kong, Traefik etc.) or the cloud provider's native load balancer SSL +termination features to secure your API. + +Sample configurations +--------------------- + +Here are a few sample configurations for some popular proxies: + +`Nginx `__ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Here is a sample ``nginx.conf`` to proxy requests to Hasura: + +.. code-block:: nginx + + server { + listen 80; + server_name hasura.my-domain.com; + + location / { + proxy_pass http://localhost:8080/; + proxy_http_version 1.1; + proxy_set_header Upgrade $http_upgrade; + proxy_set_header Connection "upgrade"; + } + } + +Please note that setting up SSL is not covered in this guide. You can find more +information at `Nginx docs +`__. + +To serve Hasura with a URL prefix instead of a separate subdomain, use +``location /hasura/`` or similar. + +`Caddy `__ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Here is a sample ``Caddyfile`` to proxy requests to Hasura: + +.. code-block:: bash + + hasura.my-domain.com { + proxy / http://localhost:8080 + websocket + } + +Caddy has SSL provisioning built-in with Let's Encrypt. You can find the docs at +`Caddy website `__. + +In order to serve at a URL prefix, use the following configuration: + +.. code-block:: bash + + my-domain.com { + proxy /hasura http://localhost:8080 + websocket + without /hasura + } diff --git a/docs/graphql/manual/deployment/graphql-engine-flags/index.rst b/docs/graphql/manual/deployment/graphql-engine-flags/index.rst index 78f086c65f01e..e1e8cc9d1ab7e 100644 --- a/docs/graphql/manual/deployment/graphql-engine-flags/index.rst +++ b/docs/graphql/manual/deployment/graphql-engine-flags/index.rst @@ -1,3 +1,5 @@ +.. _hge_flags: + GraphQL engine server configuration =================================== @@ -22,7 +24,6 @@ The following are a few configuration use cases: - :ref:`cli-with-admin-secret` - :ref:`configure-cors` - :ref:`console-assets-on-server` -- :ref:`http-compression` .. toctree:: :hidden: diff --git a/docs/graphql/manual/deployment/index.rst b/docs/graphql/manual/deployment/index.rst index 9d5f498349ae6..750c6c9e8a8bc 100644 --- a/docs/graphql/manual/deployment/index.rst +++ b/docs/graphql/manual/deployment/index.rst @@ -51,10 +51,12 @@ For access to Hasura GraphQL engine logs, check the below page for details: Using Docker Using Kubernetes Server configuration - Server logs + postgres-permissions securing-graphql-endpoint + Server logs + Enable HTTPS allow-list - postgres-permissions HTTP Compression + Production checklist Updating GraphQL engine Downgrading GraphQL engine diff --git a/docs/graphql/manual/deployment/logging.rst b/docs/graphql/manual/deployment/logging.rst index 40a6e2957ca57..df715ba9a8896 100644 --- a/docs/graphql/manual/deployment/logging.rst +++ b/docs/graphql/manual/deployment/logging.rst @@ -1,3 +1,5 @@ +.. _hge_logs: + Hasura GraphQL engine logs ========================== diff --git a/docs/graphql/manual/deployment/production-checklist.rst b/docs/graphql/manual/deployment/production-checklist.rst new file mode 100644 index 0000000000000..198d20917e527 --- /dev/null +++ b/docs/graphql/manual/deployment/production-checklist.rst @@ -0,0 +1,157 @@ +.. _production-checklist: + +Production checklist +==================== + +.. contents:: Table of contents + :backlinks: none + :depth: 1 + :local: + +This guide is a checklist for configuring and securing GraphQL engine for a +production deployment. + +Set an admin secret +------------------- + +Set an admin secret to protect the API from unauthorized access. It is +recommended to keep this as a long string. + +.. code-block:: bash + + # set env var + HASURA_GRAPHQL_ADMIN_SECRET=averylongpasswordstring + + # or use the flag + graphql-engine --database-url= serve --admin-secret=averylongpasswordstring + +More details can be found at :ref:`securing-graphql-endpoint`. + +Verify permissions +------------------ + +.. contents:: + :backlinks: none + :depth: 1 + :local: + +Review the summary +~~~~~~~~~~~~~~~~~~ +Review the authorization/permission rules set on tables. You can make use of the +"Schema permissions summary" page to get a bird's eye view on all the +permissions set across all tables and roles. Pay extra attention to roles like +"anonymous" which allow unauthenticated access. + +.. thumbnail:: ../../../img/graphql/manual/deployment/schema_permissions_summary.png + :alt: Hasura console - Schema permissions summary + :width: 75% + +Limit number of rows returned +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +You should :ref:`limit the number of rows ` that can be +accessed in one request, by setting the number in the select permission. This +will prevent someone from accidentally or otherwise querying the entire table in +one shot, thus adding load on Postgres. + +Disable APIs +------------ + +Hasura exposes many APIs which might not be relevant for a production instance +that is only supposed to serve GraphQL. APIs can be selectively enabled using +the corresponding flag or environment variable. + +In most production scenarios, you would only need GraphQL API to be enabled. + +.. code-block:: bash + + # set this env var to enable only the graphql api + HASURA_GRAPHQL_ENABLED_APIS=graphql + + # if you're using flags + graphql-engine --database-url= serve --enabled-apis=graphql + +By setting the above flag or env var, we are disabling the ``metadata``, +``pg_dump`` and ``config`` APIs. ``health`` and ``version`` APIs are public and +cannot be disabled. + +Read more about all the API types at the :ref:`API reference `. + +.. note:: + + If you're using ``cli-migrations`` image, prior to ``v1.0.0-beta.8``, setting + enabled APIs to only ``graphql`` can cause the migration apply step to fail. + Please update to the latest version if you're facing this issue. + + +Disable console +--------------- + +It is recommended that you disable the console on production deployments. Also, +when you disable the metadata API, console will stop working. + +.. code-block:: bash + + # set the env var to disable console + HASURA_GRAPHQL_ENABLE_CONSOLE=false + + # when using flags, no --enable-console flag implies console is disabled + graphql-engine --database-url= serve + +.. note:: + + You can still use the CLI to open a console connected to this instance. + (Provided ``metadata`` APIs are not disabled). + +Set up an allow-list +-------------------- + +An allow-list can be set up to restrict what kind of requests can be made against +this particular instance. If your API is meant to serve a frontend client, you +can only allow those requests used by the client to pass through. Every other +request will be rejected without even getting validated. + +Read more at :ref:`allow-list`. + +Restrict CORS domains +--------------------- + +By default, all cross-origin requests are allowed by Hasura GraphQL engine. You should restrict +them to the domains which you trust. + +.. code-block:: bash + + # set the env var, accept cross-origin requests from https://my-ui.com + HASURA_GRAPHQL_CORS_DOMAIN=https://my-ui.com + + # using flags + graphql-engine --database-url= server --cors-domain="https://my-ui.com" + +You can read more about this setting at :ref:`configure-cors`. + +Enable HTTPS +------------ + +Production APIs should be served over HTTPS to be secure over the network. + +See :ref:`enable-https` for details on achieving this. + +Configure logging +----------------- + +The :ref:`logs guide ` describes different log types and log levels Hasura GraphQL engine uses. +You can configure the GraphQL engine to enable/disable certain log-types using +the the ``--enabled-log-types`` flag or the ``HASURA_GRAPHQL_ENABLED_LOG_TYPES`` +env var. + +If you are collecting your logs using an agent and you're interested in +capturing the request logs along with the SQL that is generated, you should +enable ``query-log`` *(it is not enabled by default)*. + +.. code-block:: bash + + # enable all log types + HASURA_GRAPHQL_ENABLED_LOG_TYPES=startup,http-log,query-log,websocket-log,webhook-log + + # using flags + graphql-engine --database-url= + serve --enabled-log-types="startup,http-log,query-log,websocket-log,webhook-log" diff --git a/docs/graphql/manual/deployment/securing-graphql-endpoint.rst b/docs/graphql/manual/deployment/securing-graphql-endpoint.rst index ec1e9e69d1c44..1bf0ec2daadc6 100644 --- a/docs/graphql/manual/deployment/securing-graphql-endpoint.rst +++ b/docs/graphql/manual/deployment/securing-graphql-endpoint.rst @@ -1,3 +1,5 @@ +.. _securing-graphql-endpoint: + Securing the GraphQL endpoint ============================= diff --git a/docs/img/graphql/manual/deployment/schema_permissions_summary.png b/docs/img/graphql/manual/deployment/schema_permissions_summary.png new file mode 100644 index 0000000000000..4d345cc5acf92 Binary files /dev/null and b/docs/img/graphql/manual/deployment/schema_permissions_summary.png differ