update docs (#1696)

docs/CONTRIBUTING.md

@@ -67,10 +67,7 @@ docs tree. A user can land on a page via search as well. e.g. Say you are adding
 Hasura GraphQL engine`. It's fine to alias it to just `AWS` in the sidebar as there the user has the context of the 
 page hierarchy.
 - Ensure every new added page has a ``Table of contents`` section with the right depth. You can see any existing
-page for reference on how to do this.
-- When referring to an external link using `` `....`_``, add an extra underscore to the link. ie. `` `...`__``. A 
-single underscore creates a global link which can then be referred from any page in the docs and hence might cause 
-some conflicts with other links sometimes (a conflict will show up as a Warning though while building).   
+page for reference on how to do this.   
 - Before adding an image to docs, first compress it via some tool to ensure users won't have to unnecessarily 
 download more data than needed. You can use www.tinypng.com for this. Sometimes you can compress images by 
 upto 75% without losing any visible quality.
@@ -80,8 +77,7 @@ X and Y ...", make "create a relationship" a link to the `Create relationships`
 - Try to commit logically separate changes into different commits. i.e. if you need to update the `.gitignore` 
 file for some reason and also have other normal docs changes, commit the gitignore change separately for better 
 visibility. Ideally each commit should perform just one specific function. e.g. add xyz deployment guide, update 
-gitignore, fix broken link, etc. This is not very important though so don't spend too much effort trying to achieve 
-this. 
+gitignore, fix broken link, etc.
 
 **Notes:** 
 - Docs are currently deployed manually. Changes will not reflect immediately after a PR gets merged.

docs/graphql/manual/auth/common-roles-auth-examples.rst

@@ -15,20 +15,28 @@ Anonymous (not logged in) users
 
 - Create a role called ``anonymous`` (this value is up to you, you could even name the role ``public``).
 - Generally, you wouldn't add insert, update, or delete permissions.
-- For the select permission condition, create a valid condition depending on your data model. For example, ``is_published: {_eq: true}``.
+- For the select permission condition, create a valid condition depending on your data model. For example,
+  ``is_published: {_eq: true}``.
 - If you don't have a condition, then just set the permission to ``Without any checks``, represented by a ``{}``.
-- Choose the right set of columns that will get exposed in the GraphQL schema as fields. Ensure that sensitive information will not be exposed.
+- Choose the right set of columns that will get exposed in the GraphQL schema as fields. Ensure that sensitive
+  information will not be exposed.
 
 .. image:: ../../../img/graphql/manual/auth/anonymous-role-examples.png
    :class: no-shadow
 
+You can use the env variable ``HASURA_GRAPHQL_UNAUTHORIZED_ROLE`` or ``--unauthorized-role`` flag to set a role
+for non-logged in users. The configured unauthorized role will be used whenever an access token is not present
+in a request to the GraphQL API.
+
 Logged-in users
 ---------------
 
 - Create a role called ``user``.
 - Access control rules in this case are usually dependent on a ``user_id`` or a ``owner_id`` column in your data model.
-- Set up a permission for insert/select/update/delete that uses said column. E.g.: ``author_id: {_eq: "X-Hasura-User-Id"}`` for an article table.
-- Note that the ``X-Hasura-User-Id`` is a :doc:`dynamic session variable<./roles-variables>` that comes in from your :doc:`auth webhook's<./webhook>` response, or as a request as a header if you're testing.
+- Set up a permission for insert/select/update/delete that uses said column. E.g.:
+  ``author_id: {_eq: "X-Hasura-User-Id"}`` for an article table.
+- Note that the ``X-Hasura-User-Id`` is a :doc:`dynamic session variable<./roles-variables>` that comes in from
+  your :doc:`auth webhook's<./webhook>` response, or as a request as a header if you're testing.
 
 .. image:: ../../../img/graphql/manual/auth/user-select-graphiql.png
    :class: no-shadow
@@ -37,41 +45,50 @@ Logged-in users
 Managers of an organisation in a multi-tenant app
 -------------------------------------------------
 
-Suppose you have a multi-tenant application where managers of a particular organisation can see all of the data that belongs to the organisation. In this case, your data models will probably have an ``org_id`` column that denotes the organisation either in the same table or via a related table.
+Suppose you have a multi-tenant application where managers of a particular organisation can see all of the data that
+belongs to the organisation. In this case, your data models will probably have an ``org_id`` column that denotes the
+organisation either in the same table or via a related table.
 
 - Create a role called ``manager``.
 - Create a permission for select, which has the condition: ``org_id: {_eq: "X-Hasura-Org-Id"}``.
-- ``X-Hasura-Org-Id`` is a :doc:`dynamic variable<./roles-variables>` that is returned by your :doc:`auth webhook <./webhook>` for an incoming GraphQL request.
+- ``X-Hasura-Org-Id`` is a :doc:`dynamic variable<./roles-variables>` that is returned by your
+  :doc:`auth webhook <./webhook>` for an incoming GraphQL request.
 
 .. image:: ../../../img/graphql/manual/auth/org-manager-graphiql.png
    :class: no-shadow
 
 Collaborators of an article
 ---------------------------
 
-Let's say the "ownership" or "visibility" information for a data model (table) is not present as a column in the table, but in a different related table. In this case, let's say there is an ``article`` table and a ``collaborator`` table that has ``article_id, collaborator_id`` columns.
+Let's say the "ownership" or "visibility" information for a data model (table) is not present as a column in the
+table, but in a different related table. In this case, let's say there is an ``article`` table and a ``collaborator``
+table that has ``article_id, collaborator_id`` columns.
 
 - Create a relationship called ``collaborators`` from the article table.
 
   - Array relationship (article has array of collaborators): ``article :: id → collaborator :: article_id``.
 
 - Create a role called ``collaborator``.
-- Create a select permission on the ``article`` table, which has the condition: ``collaborators: {collaborator_id: {_eq: "X-Hasura-User_id"}}``.
+- Create a select permission on the ``article`` table, which has the condition:
+  ``collaborators: {collaborator_id: {_eq: "X-Hasura-User_id"}}``.
 
-  - This reads as: Allow the role collaborator to select if ``article.collaborators`` has a ``collaborator_id`` equal to that of ``X-Hasura-User-Id``.
+  - This reads as: Allow the role collaborator to select if ``article.collaborators`` has a ``collaborator_id``
+    equal to that of ``X-Hasura-User-Id``.
 
 .. image:: ../../../img/graphql/manual/auth/collaborator-relationship.png
    :class: no-shadow
 
 Role-based schemas
 ------------------
 
-For every role that you create, Hasura automatically publishes a different GraphQL schema that represents the right queries, fields, and mutations that are available to that role.
+For every role that you create, Hasura automatically publishes a different GraphQL schema that represents the
+right queries, fields, and mutations that are available to that role.
 
 Case 1: Logged-in users and anonymous users can access the same GraphQL fields
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-In simple use-cases, logged-in users and anonymous users might be able to fetch different rows (let's say because of a ``is_public`` flag), but have access to the same fields.
+In simple use-cases, logged-in users and anonymous users might be able to fetch different rows (let's say because
+of a ``is_public`` flag), but have access to the same fields.
 
 - ``anonymous`` role has a ``{is_public: {_eq: true}}`` select condition.
 
@@ -84,9 +101,11 @@ In simple use-cases, logged-in users and anonymous users might be able to fetch
 Case 2: Logged-in users and anonymous users have access to different fields
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-In this case, anonymous users might have access only to a subset of fields while logged-in users can access all the fields for data that they own.
+In this case, anonymous users might have access only to a subset of fields while logged-in users can access all the
+fields for data that they own.
 
-- ``anonymous`` role has a ``{is_public: {_eq: true}}`` select condition, and only the right columns are allowed to be selected.
+- ``anonymous`` role has a ``{is_public: {_eq: true}}`` select condition, and only the right columns are allowed to
+  be selected.
 
   - This reads: Allow anyone to access rows that are marked public.
 

docs/graphql/manual/auth/roles-variables.rst

@@ -106,17 +106,25 @@ the request:
 
 .. note::
 
-  If you've enabled Hasura GraphQL engine with an admin secret key, make sure you add the ADMIN_SECRET header as well.
+  If you've enabled Hasura GraphQL engine with an admin secret key, make sure you add the ``X-HASURA-ADMIN_SECRET``
+  header as well.
 
 
 Option 2: In production, from apps
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-If you're making GraphQL queries from your apps, you will probably not (and should not) be sending session variables directly
-from your app because anyone can spoof the role and values of the variables and get access to whatever data they want.
+If you're making GraphQL queries from your apps, you will probably not (and should not) be sending session
+variables directly from your app because anyone can spoof the role and values of the variables and get access
+to whatever data they want.
 
 In this case, you should configure a webhook that will return an object containing the role and session variables
 given the session token (authorization token, JWT, cookie etc.) that your app normally uses.
 
+For **non-logged in users**, you can also use the env variable ``HASURA_GRAPHQL_UNAUTHORIZED_ROLE`` or the
+``--unauthorized-role`` flag to set a default role (e.g. ``anonymous``). This will allow you to set a role for users
+that are not logged in. The configured unauthorized role will be used whenever an access token is not present in a
+request to the GraphQL API. This can be useful for data that you would like anyone to be able to access and can be
+configured and restricted just like any other role.
+
 See :doc:`webhook` or :doc:`jwt` for more details on passing dynamic session variables in production.
 

docs/graphql/manual/deployment/docker/index.rst

@@ -18,8 +18,8 @@ Prerequisites
 Step 1: Get the **docker-run.sh** bash script
 ---------------------------------------------
 
-The `hasura/graphql-engine/install-manifests <https://github.com/hasura/graphql-engine/tree/master/install-manifests>`_ repo
-contains all installation manifests required to deploy Hasura anywhere.
+The `hasura/graphql-engine/install-manifests <https://github.com/hasura/graphql-engine/tree/master/install-manifests>`_
+repo contains all installation manifests required to deploy Hasura anywhere.
 
 Get the docker run bash script from there:
 
@@ -30,10 +30,13 @@ Get the docker run bash script from there:
 Step 2: Configure the **docker-run.sh** script
 ----------------------------------------------
 
-The ``docker-run.sh`` script has a sample docker run command in it. The following are the changes needed to be
+The ``docker-run.sh`` script has a sample docker run command in it. The following changes have to be
 made to the command:
 
-Database url
+- Database URL
+- Network config
+
+Database URL
 ^^^^^^^^^^^^
 
 Edit the ``HASURA_GRAPHQL_DATABASE_URL`` env var value, so that you can connect to your Postgres instance.
@@ -115,7 +118,7 @@ command to allow the Docker container to access the host's network:
           hasura/graphql-engine:latest
           
 
-Step 3: Run the hasura docker container
+Step 3: Run the Hasura docker container
 ---------------------------------------
 
 Execute ``docker-run.sh`` & check if everything is running well:
@@ -128,12 +131,12 @@ Execute ``docker-run.sh`` & check if everything is running well:
    CONTAINER ID  IMAGE                    ...  CREATED  STATUS  PORTS           ...
    097f58433a2b  hasura/graphql-engine..  ...  1m ago   Up 1m   8080->8080/tcp  ...
 
-Step 3: Open the hasura console
+Step 4: Open the Hasura console
 -------------------------------
 
 Head to http://localhost:8080/console to open the Hasura console.
 
-Step 4: Track existing tables and relationships
+Step 5: Track existing tables and relationships
 -----------------------------------------------
 
 See :doc:`../../schema/using-existing-database` to enable GraphQL over the database.

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

@@ -25,5 +25,6 @@ Run the docker command with an admin-secret env var
 
 .. note::
 
-  If you're looking at adding access control rules for your data to your GraphQL API then head
-  to :doc:`Authentication / access control <../../auth/index>`.
+  The ``HASURA_GRAPHQL_ADMIN_SECRET`` should never be passed from the client to Hasura GraphQL engine as it would
+  give the client full admin rights to your Hasura instance. See :doc:`../../auth/index` for information on
+  setting up Authentication.

docs/graphql/manual/deployment/graphql-engine-flags/reference.rst

@@ -107,12 +107,12 @@ For ``serve`` sub-command these are the flags and ENV variables available:
      - N/A
      - Disable CORS. Do not send any CORS headers on any request.
 
-   * - ``--ws-read-cookie``
+   * - ``--ws-read-cookie <true|false>``
      - ``HASURA_GRAPHQL_WS_READ_COOKIE``
-     - Read cookie on WebSocket initial handshake, even when CORS is disabled.
+     - Read cookie on WebSocket initial handshake even when CORS is disabled.
        This can be a potential security flaw! Please make sure you know what
-       you're doing.This configuration is only applicable when CORS is disabled.
-       (``"true"`` or ``"false"``. Default: false)
+       you're doing. This configuration is only applicable when CORS is disabled.
+       (default: false)
 
    * - ``--enable-telemetry <true|false>``
      - ``HASURA_GRAPHQL_ENABLE_TELEMETRY``
@@ -148,11 +148,14 @@ For ``serve`` sub-command these are the flags and ENV variables available:
 
    * - ``--stringify-numeric-types``
      - ``HASURA_GRAPHQL_STRINGIFY_NUMERIC_TYPES``
-     - Stringify certain Postgres numeric types, specifically ``bigint``, ``numeric``, ``decimal`` and ``double precision`` as they don't fit into the ``IEEE-754`` spec for JSON encoding-decoding. (default: false)
+     - Stringify certain Postgres numeric types, specifically ``bigint``, ``numeric``, ``decimal`` and
+       ``double precision`` as they don't fit into the ``IEEE-754`` spec for JSON encoding-decoding.
+       (default: false)
 
    * - ``--enabled-apis <APIS>``
      - ``HASURA_GRAPHQL_ENABLED_APIS``
-     - Comma separated list of APIs (metadata & graphql) to be enabled. (default: ``metadata,graphql``)
+     - Comma separated list of APIs (options: ``metadata`` & ``graphql``) to be enabled.
+       (default: ``metadata,graphql``)
 
 .. note::
   1. When the equivalent flags for environment variables are used, the flags will take precedence.

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

@@ -22,6 +22,12 @@ prompted for the admin secret key.
 
 .. image:: ../../../../img/graphql/manual/deployment/access-key-console.png
 
+.. note::
+
+  The ``HASURA_GRAPHQL_ADMIN_SECRET`` should never be passed from the client to Hasura GraphQL engine as it would
+  give the client full admin rights to your Hasura instance. See :doc:`../../auth/index` for information on
+  setting up Authentication.
+
 
 (optional) Use the admin secret with the CLI
 --------------------------------------------
@@ -32,8 +38,3 @@ In case you're using the CLI to open the Hasura console, use the ``admin-secret`
 
    hasura console --admin-secret=myadminsecretkey
 
-
-.. note::
-
-  If you're looking at adding access control rules for your data to your GraphQL API then head
-  to :doc:`Authentication / access control <../../auth/index>`.

docs/graphql/manual/deployment/index.rst

@@ -50,8 +50,8 @@ For access to Hasura GraphQL engine logs, check the below page for details:
    Using Heroku <heroku/index>
    Using Docker <docker/index>
    Using Kubernetes <kubernetes/index>
+   Server configuration <graphql-engine-flags/index>
+   Server logs <logging>
    securing-graphql-endpoint
    postgres-permissions
-   GraphQL engine server configuration <graphql-engine-flags/index>
-   GraphQL engine server logs <logging>
    Updating GraphQL engine <updating>

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

@@ -34,6 +34,11 @@ Update the ``deployment.yaml`` to set the ``HASURA_GRAPHQL_ADMIN_SECRET`` enviro
           protocol: TCP
         resources: {}
 
+.. note::
+
+  The ``HASURA_GRAPHQL_ADMIN_SECRET`` should never be passed from the client to Hasura GraphQL engine as it would
+  give the client full admin rights to your Hasura instance. See :doc:`../../auth/index` for information on
+  setting up Authentication.
 
 
 (optional) Use the admin secret key with the CLI
@@ -44,9 +49,3 @@ In case you're using the CLI to open the Hasura console, use the ``admin-secret`
 .. code-block:: bash
 
    hasura console --admin-secret=myadminsecretkey
-
-
-.. note::
-
-  If you're looking at adding access control rules for your data to your GraphQL API then head
-  to :doc:`Authentication / access control <../../auth/index>`.

docs/graphql/manual/guides/integrations/auth0-jwt.rst

@@ -106,8 +106,11 @@ a table, you can setup access control rules.
 
 Refer :doc:`../../auth/basics` for more information.
 
-You can also use the env variable ``HASURA_GRAPHQL_UNAUTHORIZED_ROLE`` or ``--unauthorized-role`` flag to set a role for unauthorized users. This will allow you to set permissions for the role you specify (ex: "public") to enable requests for users that are not logged in. 
+You can also use the env variable ``HASURA_GRAPHQL_UNAUTHORIZED_ROLE`` or ``--unauthorized-role`` flag to set a role
+for **unauthorized users** (e.g. ``anonymous``). This will allow you to set permissions for users that are not
+logged in.
 
 The configured unauthorized role will be used whenever an access token is not present in a request to the GraphQL API. 
 
-This can be useful for data that you would like the public to be able to access and can be configured and restricted just like any other role using the Hasura console.
+This can be useful for data that you would like anyone to be able to access and can be configured and restricted
+just like any other role.

docs/graphql/manual/remote-schemas/index.rst

@@ -74,10 +74,16 @@ You need to enter the following information:
 
 - **Remote Schema name**: an alias for the remote schema that must be unique on an instance of GraphQL Engine.
 - **GraphQL server URL**: the endpoint at which your remote GraphQL server is available. This value can be entered
-  manually or by specifying an environment variable that contains this information. If you want to specify an
-  environment variable, please note that currently there is no validation that the environment variable is
-  actually available at the time of this configuration, so any errors in this configuration will result in a
-  runtime error.
+  manually or by specifying an environment variable that contains this information.
+
+  .. note::
+
+    - Currently there is no validation that an environment variable is actually available at the time
+      of this configuration, so any errors in this configuration will result in a runtime error.
+    - During **local development** using docker and a localhost server, ensure the Hasura docker container can reach
+      the server endpoint on the host. i.e. use ``docker.host.internal`` on mac or ``docker.for.win.localhost`` on
+      windows.
+
 - **Headers**: configure the headers to be sent to your custom GraphQL server.
 
   - Toggle forwarding all headers sent by the client (when making a GraphQL query) to your remote GraphQL server.