hasura/graphql-engine
1
0
Fork 0
mirror of https://github.com/hasura/graphql-engine.git synced 2024-09-20 15:09:02 +03:00
Code Issues Projects Releases Wiki Activity

docs: update docker guides with 2.0 changes

Browse Source 
- update docker guides
- misc improvements

https://github.com/hasura/graphql-engine-mono/pull/1638

GitOrigin-RevId: 061aaa4f0da2752fe063be97ffce162653f23b8d
This commit is contained in:
Rikin Kachhia 2021-06-23 16:51:06 +05:30 committed by hasura-bot
parent 1f2470289f
commit f7b379f677
5 changed files with 57 additions and 156 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
docs/graphql/core/databases/ms-sql-server/getting-started/cloud.rst
View File

@ -43,8 +43,8 @@ Here's an example of what your connection strings might look like with a SQL ser
.. admonition:: Make sure your SQL server database is reachable by Hasura Cloud:
1. Allow public connections or :ref:`whitelist the Hasura Cloud IP<cloud_projects_create_allow_nat_ip>` on your SQL Server firewall: This is good for testing and will allow you to try Hasura out with your database quickly!
2. VPC peering: VPC peering and private network access is available on Hasura Cloud paid tiers: Reccommended for production. Get in touch with us if you'd like to try this out against your existing databases!
1. Allow public connections or :ref:`whitelist the Hasura Cloud IP <cloud_projects_create_allow_nat_ip>` on your SQL Server firewall: This is good for testing and will allow you to try Hasura out with your database quickly!
2. VPC peering: VPC peering and private network access is available on Hasura Cloud paid tiers: Recommended for production. Get in touch with us if you'd like to try this out against your existing databases!
.. thumbnail:: /img/graphql/core/databases/ms-sql-server/1-manage-databases.png
:alt: Manage databases

181
docs/graphql/core/deployment/deployment-guides/docker.rst
View File

@ -15,11 +15,8 @@ Run Hasura GraphQL engine using Docker
Introduction
------------
This guide assumes that you already have Postgres running and helps you set up the Hasura GraphQL engine using Docker
and connect it to your Postgres database.
In case you'd like to run Hasura with a fresh Postgres database, follow :ref:`this guide <docker_simple>`
to deploy the Hasura GraphQL engine along with a Postgres instance using Docker Compose.
This guide will help you deploy the Hasura GraphQL engine and a Postgres database to store its metadata
using Docker Compose.
Deploying Hasura using Docker
-----------------------------
@ -28,137 +25,39 @@ Prerequisites
^^^^^^^^^^^^^
- `Docker <https://docs.docker.com/install/>`_
- `Docker Compose <https://docs.docker.com/compose/install/>`__
Step 1: Get the docker-compose file
-----------------------------------
Step 1: Get the **docker-run.sh** bash script
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The `hasura/graphql-engine/install-manifests <https://github.com/hasura/graphql-engine/tree/stable/install-manifests>`_
repo contains all installation manifests required to deploy Hasura anywhere.
Get the Docker run bash script from there:
The `hasura/graphql-engine/install-manifests <https://github.com/hasura/graphql-engine/tree/stable/install-manifests>`__ repo
contains all installation manifests required to deploy Hasura anywhere. Get the docker compose file from there:
.. code-block:: bash
$ wget https://raw.githubusercontent.com/hasura/graphql-engine/stable/install-manifests/docker-run/docker-run.sh
# in a new directory run
wget https://raw.githubusercontent.com/hasura/graphql-engine/stable/install-manifests/docker-compose/docker-compose.yaml
# or run
curl https://raw.githubusercontent.com/hasura/graphql-engine/stable/install-manifests/docker-compose/docker-compose.yaml -o docker-compose.yml
Step 2: Configure the **docker-run.sh** script
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Step 2: Run Hasura GraphQL engine
---------------------------------
The ``docker-run.sh`` script has a sample Docker run command in it. The following changes have to be
made to the command:
The following command will run Hasura GraphQL engine along with a Postgres database to store its metadata.
- Database URL
- Network config
.. code-block:: bash
Database URL
************
$ docker-compose up -d
Edit the ``HASURA_GRAPHQL_DATABASE_URL`` env var value, so that you can connect to your Postgres instance.
.. code-block:: bash
:emphasize-lines: 3
#! /bin/bash
docker run -d -p 8080:8080 \
-e HASURA_GRAPHQL_DATABASE_URL=postgres://<username>:<password>@hostname:<port>/<dbname> \
-e HASURA_GRAPHQL_ENABLE_CONSOLE=true \
hasura/graphql-engine:latest
Examples of ``HASURA_GRAPHQL_DATABASE_URL``:
- ``postgres://admin:password@localhost:5432/my-db``
- ``postgres://admin:@localhost:5432/my-db`` *(if there is no password)*
.. note::
- If your **password contains special characters** (e.g. #, %, $, @, etc.), you need to URL encode them in the
``HASURA_GRAPHQL_DATABASE_URL`` env var (e.g. %40 for @).
You can check the :ref:`logs <docker_logs>` to see if the database credentials are proper and if Hasura is able
to connect to the database.
- Hasura GraphQL engine needs access permissions to your Postgres database as described in
:ref:`Postgres permissions <postgres_permissions>`.
Network config
**************
If your Postgres instance is running on ``localhost``, the following changes will be needed to the ``docker run``
command to allow the Docker container to access the host's network:
.. rst-class:: api_tabs
.. tabs::
.. tab:: Linux
Add the ``--net=host`` flag to access the host's Postgres service.
This is what your command should look like:
.. code-block:: bash
:emphasize-lines: 1
docker run -d --net=host \
-e HASURA_GRAPHQL_DATABASE_URL=postgres://<username>:<password>@hostname:<port>/<dbname> \
-e HASURA_GRAPHQL_ENABLE_CONSOLE=true \
hasura/graphql-engine:latest
.. tab:: Docker for Mac
Use ``host.docker.internal`` as hostname to access the host's Postgres service.
This is what your command should look like:
.. code-block:: bash
:emphasize-lines: 2
docker run -d -p 8080:8080 \
-e HASURA_GRAPHQL_DATABASE_URL=postgres://<username>:<password>@host.docker.internal:<port>/<dbname> \
-e HASURA_GRAPHQL_ENABLE_CONSOLE=true \
hasura/graphql-engine:latest
.. tab:: Docker for Windows
Use ``host.docker.internal`` as hostname to access the host's Postgres service.
This is what your command should look like:
.. code-block:: bash
:emphasize-lines: 2
docker run -d -p 8080:8080 \
-e HASURA_GRAPHQL_DATABASE_URL=postgres://<username>:<password>@host.docker.internal:<port>/<dbname> \
-e HASURA_GRAPHQL_ENABLE_CONSOLE=true \
hasura/graphql-engine:latest
.. note::
In earlier Docker for Windows versions the hostname used to be ``docker.for.win.localhost``
Step 3: Run the Hasura Docker container
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Execute ``docker-run.sh`` & check if everything is running well:
Check if the containers are running:
.. code-block:: bash
$ ./docker-run.sh
$ docker ps
$ docker ps
CONTAINER ID IMAGE ... CREATED STATUS PORTS ...
097f58433a2b hasura/graphql-engine.. ... 1m ago Up 1m 8080->8080/tcp ...
Step 4: Open the Hasura console
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Head to ``http://localhost:8080/console`` to open the Hasura console.
Step 5: Track existing tables and relationships
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
See :ref:`schema_existing_db` to enable GraphQL over the database.
CONTAINER ID IMAGE ... CREATED STATUS PORTS ...
097f58433a2b hasura/graphql-engine ... 1m ago Up 1m 8080->8080/tcp ...
b0b1aac0508d postgres ... 1m ago Up 1m 5432/tcp ...
.. _docker_secure:
@ -168,18 +67,18 @@ Securing the GraphQL endpoint
To make sure that your GraphQL endpoint and the Hasura console are not publicly accessible, you need to
configure an admin secret key.
Run the Docker command with an admin-secret env var
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Run the Docker container with an admin-secret env var
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. code-block:: bash
.. code-block:: yaml
:emphasize-lines: 5
#! /bin/bash
docker run -d -p 8080:8080 \
-e HASURA_GRAPHQL_DATABASE_URL=postgres://<username>:<password>@hostname:<port>/<dbname> \
-e HASURA_GRAPHQL_ENABLE_CONSOLE=true \
-e HASURA_GRAPHQL_ADMIN_SECRET=<myadminsecretkey> \
hasura/graphql-engine:latest
graphql-engine:
image: hasura/graphql-engine:v2.0.0
environment:
HASURA_GRAPHQL_METADATA_DATABASE_URL: postgres://postgres:postgrespassword@postgres:5432/postgres
HASURA_GRAPHQL_ADMIN_SECRET: myadminsecretkey
...
.. note::
@ -199,10 +98,12 @@ GraphQL engine container:
$ docker ps
CONTAINER ID IMAGE ...
cdfbc6b94c70 hasura/graphql-engine.. ...
CONTAINER ID IMAGE ... CREATED STATUS PORTS ...
097f58433a2b hasura/graphql-engine ... 1m ago Up 1m 8080->8080/tcp ...
b0b1aac0508d postgres ... 1m ago Up 1m 5432/tcp ...
$ docker logs cdfbc6b94c70
$ docker logs 097f58433a2b
{"timestamp":"2018-10-09T11:20:32.054+0000", "level":"info", "type":"http-log", "detail":{"status":200, "query_hash":"01640c6dd131826cff44308111ed40d7fbd1cbed", "http_version":"HTTP/1.1", "query_execution_time":3.0177627e-2, "request_id":null, "url":"/v1/graphql", "user":{"x-hasura-role":"admin"}, "ip":"127.0.0.1", "response_size":209329, "method":"POST", "detail":null}}
...
@ -235,20 +136,26 @@ All the versions can be found at: https://github.com/hasura/graphql-engine/relea
Step 2: Update the Docker image
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
In the ``docker run`` command or the ``docker-compose`` command that you're running, update the image tag to this
In the ``docker-compose`` command that you're running, update the image tag to this
latest version.
For example, if you had:
.. raw:: html
<code>docker run hasura/graphql-engine:v1.0.0-alpha01 ...</code>
<code>
graphql-engine:<br/>
&nbsp;&nbsp;image: hasura/graphql-engine:v1.2.0
</code>
you should change it to:
.. raw:: html
<code>docker run hasura/graphql-engine:<span class="latest-release-tag">latest</span> ...</code>
<code>
graphql-engine:<br/>
&nbsp;&nbsp;image: hasura/graphql-engine:<span class="latest-release-tag">latest</span>
</code>
.. note::

20
docs/graphql/core/getting-started/docker-simple.rst
View File

@ -15,12 +15,9 @@ Quickstart with Docker
Introduction
------------
This guide will help you get the Hasura GraphQL engine and Postgres running as
Docker containers using Docker Compose. This is the easiest way to set up
Hasura GraphQL engine on your **local environment**.
In case you'd like to run Hasura on an existing Postgres database, follow :ref:`this guide <deployment_docker>`
to deploy the Hasura GraphQL engine as a standalone docker container and connect it to your Postgres instance.
This guide will help you get the Hasura GraphQL engine and a Postgres database to store its metadata
running as Docker containers using Docker Compose. This is the easiest way to set up
Hasura GraphQL engine on your **local environment**.
Prerequisites
-------------
@ -82,7 +79,7 @@ Click ``Connect Database``.
.. admonition:: Starting from scratch
If you are looking to start setting up a backend from scratch, we recommend
using Postgres. If you do not have an existing Postgres database, you can choose
using Postgres as the database. If you do not have an existing Postgres database, you can choose
to connect to the same Postgres database that is used to store the Hasura metadata.
You can pick the database connection URL from the value assigned to the
@ -166,12 +163,9 @@ Secure your endpoint
:ref:`Add an admin secret <docker_secure>` to make sure that your GraphQL endpoint and the Hasura console are not publicly accessible.
Advanced Docker setup
Detailed Docker setup
---------------------
This was a quickstart guide to get the Hasura GraphQL engine up and running
quickly. For more detailed instructions on deploying using Docker with an
external database, check out :ref:`deployment_docker`.
- :ref:`Using Docker <deployment_docker>`: Run as a docker container and connect to an existing Postgres
database.
quickly. For more detailed instructions on deploying using Docker, check out
:ref:`deployment_docker`.

2
docs/graphql/core/getting-started/index.rst
View File

@ -43,7 +43,7 @@ Supported databases
Hasura GraphQL engine supports:
- :ref:`Postgres <database_postgres>`
- :ref:`MS SQL Server <database_ms_sql_server>` (in beta)
- :ref:`MS SQL Server <database_ms_sql_server>`
- **MySQL** (in preview) - See the :ref:`preview guide <mysql_preview>`
.. toctree::

6
docs/graphql/core/guides/upgrade-hasura-v2.rst
View File

@ -246,8 +246,8 @@ The following commands need to be executed in the specified order to apply metad
Downgrading back to Hasura v1
-----------------------------
In case there are some issues with your API post updating to Hasura v2, you can downgrade back to Hasura v1 using the
:ref:`downgrade command <downgrade_hge>`:
In case there are some issues with your Hasura instance post updating to Hasura v2, you can downgrade back to Hasura v1 by reverting the Hasura
docker image version and using the :ref:`downgrade command <downgrade_hge>` to revert the Hasura metadata catalogue changes:
.. code-block:: bash
@ -255,4 +255,4 @@ In case there are some issues with your API post updating to Hasura v2, you can
.. note::
You can downgrade a Hasura v2 instance to Hasura v1 only if there is only one database connected to it.
You can downgrade a Hasura v2 instance to Hasura v1 only if there is only one database connected to it.