add production checklist to docs (close #2561) (#3140)

docs/graphql/manual/api-reference/index.rst

@@ -1,3 +1,5 @@
+.. _api-reference:
+
 API Reference
 =============
 

docs/graphql/manual/deployment/allow-list.rst

@@ -1,3 +1,5 @@
+.. _allow-list:
+
 Allow-list for queries
 ======================
 

docs/graphql/manual/deployment/compression.rst

@@ -1,3 +1,5 @@
+.. _http-compression:
+
 HTTP Compression
 ================
 

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 <https://nginx.org/en/docs/>`__
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+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
+<https://nginx.org/en/docs/http/configuring_https_servers.html>`__.
+
+To serve Hasura with a URL prefix instead of a separate subdomain, use
+``location /hasura/`` or similar.
+
+`Caddy <https://caddyserver.com/>`__
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+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 <https://caddyserver.com/docs/automatic-https>`__.
+   
+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
+   }

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:

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 <docker/index>
    Using Kubernetes <kubernetes/index>
    Server configuration <graphql-engine-flags/index>
-   Server logs <logging>
-   securing-graphql-endpoint
-   allow-list
    postgres-permissions
+   securing-graphql-endpoint
+   Server logs <logging>
+   Enable HTTPS <enable-https>
+   allow-list
    HTTP Compression <compression>
+   Production checklist <production-checklist>
    Updating GraphQL engine <updating>
    Downgrading GraphQL engine <downgrading>

docs/graphql/manual/deployment/logging.rst

@@ -1,3 +1,5 @@
+.. _hge_logs:
+
 Hasura GraphQL engine logs
 ==========================
 

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=<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 <limit-rows-permissions>` 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=<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 <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=<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=<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 <hge_logs>` 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=<database-url>
+   serve --enabled-log-types="startup,http-log,query-log,websocket-log,webhook-log"

docs/graphql/manual/deployment/securing-graphql-endpoint.rst

@@ -1,3 +1,5 @@
+.. _securing-graphql-endpoint:
+
 Securing the GraphQL endpoint
 =============================