From d4972feb552762c3758cf18ef60724131bf8df98 Mon Sep 17 00:00:00 2001 From: Marion Schleifer Date: Thu, 23 Jul 2020 14:34:17 +0200 Subject: [PATCH] docs: restructure deployment section (#5339) --- .../azure-container-instances-postgres.rst | 5 + .../deploying}/digital-ocean-one-click.rst | 236 +++++++----- .../index.rst => deploying/docker.rst} | 127 ++++++- .../google-kubernetes-engine-cloud-sql.rst | 9 +- .../manual/deployment/deploying/heroku.rst | 341 ++++++++++++++++++ .../manual/deployment/deploying/index.rst | 69 ++++ .../deployment/deploying/kubernetes.rst | 227 ++++++++++++ .../deploying}/nhost-one-click.rst | 2 +- .../deploying}/render-one-click.rst | 5 +- .../manual/deployment/docker/logging.rst | 34 -- .../docker/securing-graphql-endpoint.rst | 36 -- .../manual/deployment/docker/updating.rst | 50 --- .../manual/deployment/heroku/index.rst | 125 ------- .../manual/deployment/heroku/logging.rst | 29 -- .../heroku/securing-graphql-endpoint.rst | 48 --- .../manual/deployment/heroku/updating.rst | 86 ----- .../heroku/using-existing-heroku-database.rst | 65 ---- docs/graphql/manual/deployment/index.rst | 45 ++- .../manual/deployment/kubernetes/index.rst | 106 ------ .../manual/deployment/kubernetes/logging.rst | 30 -- .../kubernetes/securing-graphql-endpoint.rst | 57 --- .../manual/deployment/kubernetes/updating.rst | 66 ---- docs/graphql/manual/deployment/logging.rst | 3 + .../deployment/securing-graphql-endpoint.rst | 1 + ...dating.rst => updating-graphql-engine.rst} | 2 + docs/graphql/manual/getting-started/index.rst | 2 - .../guides/deployment/heroku-one-click.rst | 66 ---- .../manual/guides/deployment/index.rst | 39 -- docs/graphql/manual/guides/index.rst | 1 - 29 files changed, 931 insertions(+), 981 deletions(-) rename docs/graphql/manual/{guides/deployment => deployment/deploying}/azure-container-instances-postgres.rst (99%) rename docs/graphql/manual/{guides/deployment => deployment/deploying}/digital-ocean-one-click.rst (57%) rename docs/graphql/manual/deployment/{docker/index.rst => deploying/docker.rst} (56%) rename docs/graphql/manual/{guides/deployment => deployment/deploying}/google-kubernetes-engine-cloud-sql.rst (99%) create mode 100644 docs/graphql/manual/deployment/deploying/heroku.rst create mode 100644 docs/graphql/manual/deployment/deploying/index.rst create mode 100644 docs/graphql/manual/deployment/deploying/kubernetes.rst rename docs/graphql/manual/{guides/deployment => deployment/deploying}/nhost-one-click.rst (98%) rename docs/graphql/manual/{guides/deployment => deployment/deploying}/render-one-click.rst (97%) delete mode 100644 docs/graphql/manual/deployment/docker/logging.rst delete mode 100644 docs/graphql/manual/deployment/docker/securing-graphql-endpoint.rst delete mode 100644 docs/graphql/manual/deployment/docker/updating.rst delete mode 100644 docs/graphql/manual/deployment/heroku/index.rst delete mode 100644 docs/graphql/manual/deployment/heroku/logging.rst delete mode 100644 docs/graphql/manual/deployment/heroku/securing-graphql-endpoint.rst delete mode 100644 docs/graphql/manual/deployment/heroku/updating.rst delete mode 100644 docs/graphql/manual/deployment/heroku/using-existing-heroku-database.rst delete mode 100644 docs/graphql/manual/deployment/kubernetes/index.rst delete mode 100644 docs/graphql/manual/deployment/kubernetes/logging.rst delete mode 100644 docs/graphql/manual/deployment/kubernetes/securing-graphql-endpoint.rst delete mode 100644 docs/graphql/manual/deployment/kubernetes/updating.rst rename docs/graphql/manual/deployment/{updating.rst => updating-graphql-engine.rst} (95%) delete mode 100644 docs/graphql/manual/guides/deployment/heroku-one-click.rst delete mode 100644 docs/graphql/manual/guides/deployment/index.rst diff --git a/docs/graphql/manual/guides/deployment/azure-container-instances-postgres.rst b/docs/graphql/manual/deployment/deploying/azure-container-instances-postgres.rst similarity index 99% rename from docs/graphql/manual/guides/deployment/azure-container-instances-postgres.rst rename to docs/graphql/manual/deployment/deploying/azure-container-instances-postgres.rst index be38115817b..29e5ad2bb6d 100644 --- a/docs/graphql/manual/guides/deployment/azure-container-instances-postgres.rst +++ b/docs/graphql/manual/deployment/deploying/azure-container-instances-postgres.rst @@ -12,6 +12,9 @@ Hasura GraphQL engine on Azure with Container Instances and Postgres :depth: 1 :local: +Introduction +------------ + This guide talks about how to deploy the Hasura GraphQL engine on `Azure `__ using `Container Instances `__ with `Azure @@ -222,6 +225,8 @@ Hasura is able to connect to the database. If you're using an existing/external database, make sure the firewall rules for the database allow connection for Azure services. +.. _azure_logs: + Checking logs ^^^^^^^^^^^^^ diff --git a/docs/graphql/manual/guides/deployment/digital-ocean-one-click.rst b/docs/graphql/manual/deployment/deploying/digital-ocean-one-click.rst similarity index 57% rename from docs/graphql/manual/guides/deployment/digital-ocean-one-click.rst rename to docs/graphql/manual/deployment/deploying/digital-ocean-one-click.rst index 07ad364330d..de66b4daf86 100644 --- a/docs/graphql/manual/guides/deployment/digital-ocean-one-click.rst +++ b/docs/graphql/manual/deployment/deploying/digital-ocean-one-click.rst @@ -12,16 +12,19 @@ Hasura GraphQL engine One-click App on DigitalOcean Marketplace :depth: 1 :local: +Introduction +------------ + The Hasura GraphQL engine is available as a One-click app on the DigitalOcean Marketplace. It is packed with a `Postgres `__ database and `Caddy `__ webserver for easy and automatic HTTPS using `Let's Encrypt `__. -Quickstart ----------- +Deploying Hasura on Digital Ocean +--------------------------------- -1. Create a Hasura One-click Droplet -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Step 1: Create a Hasura One-click Droplet +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Click the button below to create a new Hasura GraphQL engine Droplet through the DigitalOcean Marketplace. For first time users, the link also contains a @@ -34,8 +37,8 @@ support most workloads. (``Ctrl+Click`` to open in a new tab) :class: no-shadow :target: https://marketplace.digitalocean.com/apps/hasura?action=deploy&refcode=c4d9092d2c48&utm_source=hasura&utm_campaign=docs -2. Open console -~~~~~~~~~~~~~~~ +Step 2: Open console +^^^^^^^^^^^^^^^^^^^^ Once the Hasura GraphQL engine Droplet is ready, you can visit the Droplet IP to open the Hasura console, where you can create tables, explore GraphQL APIs etc. @@ -62,8 +65,8 @@ can create a table on this Postgres instance and make your first GraphQL query. :class: no-shadow :alt: Hasura console -3. Create a table -~~~~~~~~~~~~~~~~~ +Step 3: Create a table +^^^^^^^^^^^^^^^^^^^^^^ Navigate to ``Data -> Create table`` on the console and create a table called ``profile`` with the following columns: @@ -82,8 +85,8 @@ Choose ``id`` as the Primary key and click the ``Create`` button. :class: no-shadow :alt: Hasura console - create table -4. Insert sample data -~~~~~~~~~~~~~~~~~~~~~ +Step 4: Insert sample data +^^^^^^^^^^^^^^^^^^^^^^^^^^ Once the table is created, go to the ``Insert Row`` tab and insert some sample rows: @@ -99,8 +102,8 @@ Once the table is created, go to the ``Insert Row`` tab and insert some sample r :class: no-shadow :alt: Hasura console - insert data -5. Try out GraphQL -~~~~~~~~~~~~~~~~~~ +Step 5: Try out GraphQL +^^^^^^^^^^^^^^^^^^^^^^^ Switch to the ``GraphiQL`` tab on top and execute the following GraphQL query: @@ -117,8 +120,10 @@ Switch to the ``GraphiQL`` tab on top and execute the following GraphQL query: :class: no-shadow :alt: Hasura console - GraphiQL -Secure the GraphQL endpoint ---------------------------- +.. _digital_ocean_secure: + +Securing the GraphQL endpoint +----------------------------- By default Hasura is exposed without any admin secret. Anyone can read and write to your database using GraphQL. When deploying to production, you should secure @@ -127,41 +132,46 @@ tables. To add an admin secret key, follow the steps described below: -1. Connect to the Droplet via SSH: +Step 1: Connect to the Droplet via SSH +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - .. code-block:: bash +.. code-block:: bash - ssh root@ + ssh root@ -2. Go to the ``/etc/hasura`` directory: +Step 2: Go to the ``/etc/hasura`` directory +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - .. code-block:: bash +.. code-block:: bash - cd /etc/hasura + cd /etc/hasura -3. Edit ``docker-compose.yaml`` and un-comment the line that mentions admin secret key. - Also change it to some unique secret: +Step 3: Set an admin secret +^^^^^^^^^^^^^^^^^^^^^^^^^^^ - .. code-block:: bash +Edit ``docker-compose.yaml`` and un-comment the line that mentions admin secret key. +Also change it to some unique secret: - vim docker-compose.yaml +.. code-block:: bash - ... - # un-comment next line to add an admin secret key - HASURA_GRAPHQL_ADMIN_SECRET: myadminsecretkey - ... + vim docker-compose.yaml - # type ESC followed by :wq to save and quit + ... + # un-comment next line to add an admin secret key + HASURA_GRAPHQL_ADMIN_SECRET: myadminsecretkey + ... + + # type ESC followed by :wq to save and quit -4. Update the container: +Step 4: Update the container +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - .. code-block:: bash - - docker-compose up -d +.. code-block:: bash + docker-compose up -d That's it. Visit the console at ``http:///console`` and it should prompt for the admin secret key. Further API requests can be made by adding the @@ -179,47 +189,57 @@ If you own a domain, you can enable HTTPS on this Droplet by mapping the domain to the Droplet's IP. The Hasura GraphQL Droplet is configured with Caddy which is an HTTP/2 web server with automatic HTTPS using Let's Encrypt. -1. Go to your domain's DNS dashboard and add an A record mapping the domain to the Droplet IP. -2. Connect to the Droplet via SSH: +Step 1: Add a record mapping +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - .. code-block:: bash +Go to your domain's DNS dashboard and add an A record mapping the domain to the Droplet IP. - ssh root@ +Step 2: Connect to the Droplet via SSH +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. code-block:: bash + + ssh root@ -3. Go to the ``/etc/hasura`` directory: +Step 3: Go to the ``/etc/hasura`` directory +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - .. code-block:: bash +.. code-block:: bash - cd /etc/hasura + cd /etc/hasura -4. Edit the ``Caddyfile`` and change ``:80`` to your domain: +Step 4: Edit the ``Caddyfile`` and change ``:80`` to your domain +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - .. code-block:: bash +.. code-block:: bash - vim Caddyfile + vim Caddyfile - ... - add_your-domain-here { - proxy / graphql-engine:8080 { - websocket - } + ... + add_your-domain-here { + proxy / graphql-engine:8080 { + websocket } - ... + } + ... - # type ESC followed by :wq to save and quit + # type ESC followed by :wq to save and quit -5. Restart the container: +Step 5: Restart the container +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - .. code-block:: bash +.. code-block:: bash - docker-compose restart caddy + docker-compose restart caddy Go to ``https:///console`` to visit the Hasura console. +.. _do_updating: + Updating to the latest version ------------------------------ @@ -228,74 +248,87 @@ changing the version tag in ``docker-compose.yaml``. You can find the latest releases on the `GitHub releases page `__. -1. Connect to the Droplet via SSH: +Step 1: Connect to the Droplet via SSH +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - .. code-block:: bash +.. code-block:: bash - ssh root@ + ssh root@ -2. Go to the ``/etc/hasura`` directory: +Step 2: Go to the ``/etc/hasura`` directory +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - .. code-block:: bash +.. code-block:: bash - cd /etc/hasura + cd /etc/hasura -3. Edit ``docker-compose.yaml`` and change the image tag to the latest one: +Step 3: Edit ``docker-compose.yaml`` and change the image tag to the latest one +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - .. code-block:: bash +.. code-block:: bash - vim docker-compose.yaml + vim docker-compose.yaml - ... - graphql-engine: - image: hasura/graphql-engine:latest_tag_here - ... + ... + graphql-engine: + image: hasura/graphql-engine:latest_tag_here + ... - # type ESC followed by :wq to save and quit + # type ESC followed by :wq to save and quit -4. Restart the container: +Step 4: Restart the container +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - .. code-block:: bash +.. code-block:: bash - docker-compose up -d + docker-compose up -d Using DigitalOcean Managed Postgres Database -------------------------------------------- -1. Create a new Postgres Database from the DigitalOcean Console, preferably in the - same region as the Droplet. -2. Once the database is created, under the "Overview" tab, from the "Connection - Details" section, choose "Connection string" from the dropdown. -3. "Connection string" is the "Database URL". Copy it. -4. Connect to the Droplet via SSH: +Step 1: Create a Postgres database +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - .. code-block:: bash +Create a new Postgres database from the DigitalOcean console, preferably in the same region as the Droplet. - ssh root@ +Step 2: Get the database URL +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Once the database is created, under the "Overview" tab, from the "Connection Details" section, choose "Connection string" from the dropdown. +"Connection string" is the "Database URL". Copy it. + +Step 3: Connect to the Droplet via SSH +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. code-block:: bash + + ssh root@ -5. Go to the ``/etc/hasura`` directory: +Step 4: Go to the ``/etc/hasura`` directory +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - .. code-block:: bash +.. code-block:: bash - cd /etc/hasura + cd /etc/hasura -6. Edit ``docker-compose.yaml`` and change the database URL: +Step 5: Edit ``docker-compose.yaml`` and change the database URL +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - .. code-block:: bash +.. code-block:: bash - vim docker-compose.yaml + vim docker-compose.yaml - ... - # change the url to use a different database - HASURA_GRAPHQL_DATABASE_URL: - ... + ... + # change the url to use a different database + HASURA_GRAPHQL_DATABASE_URL: + ... - # type ESC followed by :wq to save and quit + # type ESC followed by :wq to save and quit Similarly, the database URL can be changed to connect to any other Postgres database. @@ -319,29 +352,34 @@ If you need to configure the pool size or the timeout, you can use the below env If you still want to enable connection pooling on your managed database on DigitalOcean, you should do so in the ``session`` mode. +.. _do_logs: Logs ---- +Step 1: Connect to the Droplet via SSH +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -1. Connect to the Droplet via SSH: +.. code-block:: bash - .. code-block:: bash - - ssh root@ + ssh root@ -2. Go to the ``/etc/hasura`` directory: +Step 2: Go to the ``/etc/hasura`` directory +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - .. code-block:: bash +.. code-block:: bash - cd /etc/hasura + cd /etc/hasura -3. To checks logs for any container, use the following command: +Step 3: Check logs +^^^^^^^^^^^^^^^^^^ - .. code-block:: bash +To checks logs for any container, use the following command: - docker-compose logs +.. code-block:: bash + + docker-compose logs Where ```` is one of ``graphql-engine``, ``postgres`` or ``caddy``. diff --git a/docs/graphql/manual/deployment/docker/index.rst b/docs/graphql/manual/deployment/deploying/docker.rst similarity index 56% rename from docs/graphql/manual/deployment/docker/index.rst rename to docs/graphql/manual/deployment/deploying/docker.rst index 5076d05962b..b7f83a65451 100644 --- a/docs/graphql/manual/deployment/docker/index.rst +++ b/docs/graphql/manual/deployment/deploying/docker.rst @@ -12,17 +12,23 @@ Run Hasura GraphQL engine using Docker :depth: 1 :local: +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. +Deploying Hasura using Docker +----------------------------- + Prerequisites -------------- +^^^^^^^^^^^^^ - `Docker `_ Step 1: Get the **docker-run.sh** bash script ---------------------------------------------- +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The `hasura/graphql-engine/install-manifests `_ repo contains all installation manifests required to deploy Hasura anywhere. @@ -34,7 +40,7 @@ Get the Docker run bash script from there: $ wget https://raw.githubusercontent.com/hasura/graphql-engine/stable/install-manifests/docker-run/docker-run.sh Step 2: Configure the **docker-run.sh** script ----------------------------------------------- +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The ``docker-run.sh`` script has a sample Docker run command in it. The following changes have to be made to the command: @@ -43,7 +49,7 @@ made to the command: - Network config Database URL -^^^^^^^^^^^^ +************ Edit the ``HASURA_GRAPHQL_DATABASE_URL`` env var value, so that you can connect to your Postgres instance. @@ -73,7 +79,7 @@ Examples of ``HASURA_GRAPHQL_DATABASE_URL``: :ref:`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: @@ -125,7 +131,7 @@ command to allow the Docker container to access the host's network: Step 3: Run the Hasura Docker container ---------------------------------------- +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Execute ``docker-run.sh`` & check if everything is running well: @@ -138,27 +144,112 @@ Execute ``docker-run.sh`` & check if everything is running well: 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. +.. _docker_secure: + +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 +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. code-block:: bash + :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 + +.. note:: + + The ``HASURA_GRAPHQL_ADMIN_SECRET`` should never be passed from the client to the Hasura GraphQL engine as it would + give the client full admin rights to your Hasura instance. See :ref:`auth` for information on + setting up authentication. + +.. _docker_logs: + +Hasura GraphQL engine server logs +--------------------------------- + +You can check the logs of the Hasura GraphQL engine deployed using Docker by checking the logs of the +GraphQL engine container: + +.. code-block:: bash + + $ docker ps + + CONTAINER ID IMAGE ... + cdfbc6b94c70 hasura/graphql-engine.. ... + + $ docker logs cdfbc6b94c70 + + {"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}} + ... + +**See:** + +- https://docs.docker.com/config/containers/logging for more details on logging in Docker. + +- :ref:`hge_logs` for more details on Hasura logs. + +.. _docker_update: + +Updating Hasura GraphQL engine +------------------------------ + +This guide will help you update the Hasura GraphQL engine running with Docker. This guide assumes that you already have +Hasura GraphQL engine running with Docker. + +Step 1: Check the latest release version +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The current latest version is: + +.. raw:: html + + hasura/graphql-engine:latest + +All the versions can be found at: https://github.com/hasura/graphql-engine/releases + +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 +latest version. + +For example, if you had: + +.. raw:: html + + docker run hasura/graphql-engine:v1.0.0-alpha01 ... + +you should change it to: + +.. raw:: html + + docker run hasura/graphql-engine:latest ... + +.. note:: + + If you are downgrading to an older version of the GraphQL engine you might need to downgrade your metadata catalogue version + as described in :ref:`downgrade_hge` + Advanced -------- -- :ref:`Securing your GraphQL endpoint ` -- :ref:`GraphQL engine server logs ` -- :ref:`Updating GraphQL engine ` - :ref:`Setting up migrations ` -.. toctree:: - :titlesonly: - :hidden: - - Securing your GraphQL endpoint - GraphQL engine server logs - Updating GraphQL engine diff --git a/docs/graphql/manual/guides/deployment/google-kubernetes-engine-cloud-sql.rst b/docs/graphql/manual/deployment/deploying/google-kubernetes-engine-cloud-sql.rst similarity index 99% rename from docs/graphql/manual/guides/deployment/google-kubernetes-engine-cloud-sql.rst rename to docs/graphql/manual/deployment/deploying/google-kubernetes-engine-cloud-sql.rst index cacc3c61e16..27208970a51 100644 --- a/docs/graphql/manual/guides/deployment/google-kubernetes-engine-cloud-sql.rst +++ b/docs/graphql/manual/deployment/deploying/google-kubernetes-engine-cloud-sql.rst @@ -12,6 +12,9 @@ Hasura GraphQL engine on Google Cloud Platform with Kubernetes engine and Cloud :depth: 1 :local: +Introduction +------------ + This is a guide on deploying the Hasura GraphQL engine on the `Google Cloud Platform `__ using `Kubernetes engine `__ to run Hasura and PosgreSQL @@ -185,8 +188,10 @@ command below. It usually takes a couple of minutes. Once the IP is allocated, visit the IP in a browser and it should open the console. -Troubleshooting ---------------- +.. _gc_kubernetes_logs: + +Logs +---- Check the status for pods to see if they are running. If there are any errors, check the logs of the GraphQL engine: diff --git a/docs/graphql/manual/deployment/deploying/heroku.rst b/docs/graphql/manual/deployment/deploying/heroku.rst new file mode 100644 index 00000000000..a6ddc5468df --- /dev/null +++ b/docs/graphql/manual/deployment/deploying/heroku.rst @@ -0,0 +1,341 @@ +.. meta:: + :description: Deploy Hasura GraphQL engine with Heroku + :keywords: hasura, docs, deployment, heroku + +.. _deploy_heroku: + +Run Hasura GraphQL engine on Heroku +=================================== + +.. contents:: Table of contents + :backlinks: none + :depth: 2 + :local: + +Introduction +------------ + +This guide shows how to deploy Hasura GraphQL engine on Heroku. + +Deploying Hasura with a new Postgres DB +--------------------------------------- + +.. _heroku_one_click: + +Option 1: One-click deployment +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Click the below button to deploy Hasura on Heroku in a few seconds: + +.. image:: https://camo.githubusercontent.com/83b0e95b38892b49184e07ad572c94c8038323fb/68747470733a2f2f7777772e6865726f6b7563646e2e636f6d2f6465706c6f792f627574746f6e2e737667 + :width: 200px + :alt: heroku_deploy_button + :class: no-shadow + :target: https://heroku.com/deploy?template=https://github.com/hasura/graphql-engine-heroku + +.. note:: + If you don't have an account on Heroku, you need to sign up on Heroku. You won't need a credit card, and once you + sign up you'll be redirected to your Heroku app creation page automatically. + +.. thumbnail:: /img/graphql/manual/guides/heroku-app.png + :alt: Deploy to Heroku + +Heroku's free Postgres add-on is automatically provisioned. + +.. _heroku_cli_deployment: + +Option 2: Deploy via Heroku CLI +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Follow these instructions to create a new Heroku app with a Postgres add-on using the Heroku CLI. + +Step 1: Clone the Hasura GraphQL engine Heroku app +************************************************** + +The Hasura app with Heroku buildpack/configuration is available at: + +https://github.com/hasura/graphql-engine-heroku + +Step 2: Create an app with **--stack=container** +************************************************ + +Use the `Heroku CLI `__ to create a new Heroku app from inside the cloned directory. Let's call +the app ``graphql-on-postgres``. + +.. code-block:: bash + + # Replace graphql-on-postgres with whatever you'd like your app to be called + $ heroku create graphql-on-postgres --stack=container + + Creating ⬢ graphql-on-postgres... done, stack is container + https://graphql-on-postgres.herokuapp.com/ | https://git.heroku.com/graphql-on-postgres.git + +**Note**: + +- ``HEROKU_GIT_REMOTE``: `https://git.heroku.com/graphql-on-postgres.git` +- ``HEROKU_APP_URL``: `https://graphql-on-postgres.herokuapp.com/` + +Step 3: Create the Heroku Postgres add-on +***************************************** + +Create the Postgres add-on in your Heroku app. + +.. code-block:: bash + + $ heroku addons:create heroku-postgresql:hobby-dev -a graphql-on-postgres + + Creating heroku-postgresql:hobby-dev on ⬢ graphql-on-postgres... free + Database has been created and is available + ! This database is empty. If upgrading, you can transfer + ! data from another database with pg:copy + Created postgresql-angular-20334 as DATABASE_URL + Use heroku addons:docs heroku-postgresql to view documentation + +Step 4: **git push** to deploy +****************************** + +Remember to change ``HEROKU_GIT_REMOTE`` to your git remote below. In our case: +``https://git.heroku.com/graphql-on-postgres.git``. + +.. code-block:: bash + + $ git init && git add . + $ git commit -m "first commit" + $ git remote add heroku HEROKU_GIT_REMOTE + $ git push heroku master + +Visit ``https://graphql-on-postgres.herokuapp.com`` (replace ``graphql-on-postgres`` with your app name) and +you should see the Hasura console. + +.. _heroku_existing_db: + +Deploying using an existing Postgres DB +--------------------------------------- + +Let's say you have an existing `Heroku Postgres `__ database with data in it, and you'd +like to add GraphQL to it. + +.. note:: + + In case you're exposing an existing database (esp. if it is production), please :ref:`configure an admin secret key ` + for the console and the GraphQL endpoint. + +Option 1: Via Heroku UI +^^^^^^^^^^^^^^^^^^^^^^^ + +Step 1: Deploy Hasura on Heroku +******************************* + +Deploy Hasura on Heroku as described in :ref:`this section `. + +Step 2: Remove the created Postgres add-on in the app +***************************************************** + +Head to your Heroku dashboard and delete the Postgres add-on created in the previous step: + +.. thumbnail:: /img/graphql/manual/deployment/remove-heroku-postgres-addon.png + :alt: Delete the Postgres add-on + +Step 3: Configure environment variables +*************************************** + +Now configure the ``DATABASE_URL`` with your existing Heroku Postgres database URL and a ``HASURA_GRAPHQL_ADMIN_SECRET`` +if you want to :ref:`secure your endpoint `. + +.. thumbnail:: /img/graphql/manual/deployment/heroku-database-url-access.png + :alt: Configure environment variables + +.. note:: + + The Hasura GraphQL engine needs access permissions to your Postgres database as described in + :ref:`Postgres permissions `. + +Step 4: Track tables and relationships +************************************** + +Wait for the GraphQL engine to restart and then see :ref:`schema_existing_db` to enable GraphQL +over the database. + +Option 2: Via Heroku CLI +^^^^^^^^^^^^^^^^^^^^^^^^ + +You can set up the Hasura GraphQL engine as a "git push to deploy" app on +`Heroku `__ and connect it to a `Heroku Postgres `__ +instance. + +Step 1: Clone the Hasura GraphQL engine Heroku app +************************************************** + +The Hasura app with Heroku buildpack/configuration is available at: + +https://github.com/hasura/graphql-engine-heroku + +Step 2: Configure the database URL +********************************** + +Edit the command in the ``Dockerfile`` to change which database the Hasura GraphQL engine connects to. +By default, it connects to the primary database in your app which is available at ``DATABASE_URL``. + +.. code-block:: dockerfile + :emphasize-lines: 6 + + FROM hasura/graphql-engine:latest + + # Change $DATABASE_URL to your Heroku Postgres URL if you're not using + # the primary Postgres instance in your app + CMD graphql-engine \ + --database-url $DATABASE_URL \ + serve \ + --server-port $PORT \ + --enable-console + +Read about more configuration options :ref:`here `. + +.. note:: + + Hasura GraphQL engine needs access permissions to your Postgres database as described in + :ref:`Postgres permissions `. + + +.. _heroku_secure: + +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. + + +Add an admin secret +^^^^^^^^^^^^^^^^^^^ + +Head to the config-vars URL on your Heroku dashboard and set the ``HASURA_GRAPHQL_ADMIN_SECRET`` environment variable. + +.. thumbnail:: /img/graphql/manual/deployment/secure-heroku.png + :alt: Add an admin secret + +Setting this environment variable will automatically restart the dyno. Now when you access your console, you'll be +prompted for the admin secret key. + +.. thumbnail:: /img/graphql/manual/deployment/access-key-console.png + :alt: Prompt for the admin secret + +.. 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 :ref:`auth` for information on + setting up authentication. + + +(optional) Use the admin secret with the CLI +******************************************** + +In case you're using the CLI to open the Hasura console, use the ``admin-secret`` flag when you open the console: + +.. code-block:: bash + + hasura console --admin-secret=myadminsecretkey + +.. _heroku_logs: + +GraphQL engine server logs +-------------------------- + +You can use the `Heroku CLI `__ to check the logs +of the Hasura GraphQL engine deployed on Heroku: + +.. code-block:: bash + + $ heroku logs --app + + 2018-10-09T11:18:21.306000+00:00 app[web.1]: {"timestamp":"2018-10-09T11:18:21.305+0000", "level":"info", "type":"http-log", "detail":{"status":200, "query_hash":"48c74f902b53a886f9ddc1b7dd12a4a6020d70c3", "http_version":"HTTP/1.1", "query_execution_time":9.477913e-3, "request_id":"b7bb6fb3-97b3-4c6f-a54a-1e0f71a190e9", "url":"/v1/graphql", "user":{"x-hasura-role":"admin"}, "ip":"171.61.77.16", "response_size":15290, "method":"POST", "detail":null}} + ... + +**See:** + +- https://devcenter.heroku.com/articles/logging for more details on logging on Heroku. + +- :ref:`hge_logs` for more details on Hasura logs + +.. _heroku_update: + +Updating GraphQL engine +----------------------- + +This section will help you update the Hasura GraphQL engine running on Heroku. + +The current latest version is: + +.. raw:: html + + hasura/graphql-engine:latest + +Update to the latest version +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Step 1: Clone the Hasura GraphQL engine Heroku app +************************************************** + +The Hasura app with Heroku buildpack/configuration is available at: +https://github.com/hasura/graphql-engine-heroku. + +Clone the above repository. + +.. code-block:: bash + + git clone https://github.com/hasura/graphql-engine-heroku + cd graphql-engine-heroku + +If you already have this, then pull the latest changes which will have the updated GraphQL engine Docker image. + +Step 2: Attach your Heroku app +****************************** + +Let's say your Heroku app is called ``hasura-heroku`` and is running on ``https://hasura-heroku.herokuapp.com``. + +From inside the ``graphql-engine-heroku`` directory, use the `Heroku CLI `__ to configure the git repo you cloned in Step 1 +to be able to push to this app. + +.. code-block:: bash + + # Replace with your Heroku app's name + heroku git:remote -a + heroku stack:set container -a + +You can find your Heroku git repo in your Heroku - Settings - Info - Heroku Git URL + +Step 3: **git push** to deploy the latest Hasura GraphQL engine +*************************************************************** + +When you ``git push`` to deploy, the Heroku app will get updated with the latest changes: + +.. code-block:: bash + + git push heroku master + +Deploy a specific version +^^^^^^^^^^^^^^^^^^^^^^^^^ + +Head to the ``Dockerfile`` in the git repo you cloned in step 1. +Change the ``FROM`` line to the specific version you want. A list of all releases can be found +at https://github.com/hasura/graphql-engine/releases. + +.. code-block:: Dockerfile + :emphasize-lines: 1 + + FROM hasura/graphql-engine:v1.0.0 + + ... + ... + +Change ``v1.0.0`` to ``v1.1.0`` for example, commit this and then ``git push heroku master`` to deploy. + +.. note:: + + If you are downgrading to an older version of the GraphQL engine you might need to downgrade your metadata catalogue version + as described in :ref:`downgrade_hge` + +Advanced +-------- + +- :ref:`Setting up migrations ` diff --git a/docs/graphql/manual/deployment/deploying/index.rst b/docs/graphql/manual/deployment/deploying/index.rst new file mode 100644 index 00000000000..a6e1a8a1ea3 --- /dev/null +++ b/docs/graphql/manual/deployment/deploying/index.rst @@ -0,0 +1,69 @@ +.. meta:: + :description: Deploy Hasura GraphQL engine + :keywords: hasura, docs, deployment + +.. _deployment_guides: + +Deployment guides +================= + +.. contents:: Table of contents + :backlinks: none + :depth: 1 + :local: + +Introduction +------------ + +The Hasura GraphQL engine is a binary that is shipped as a Docker container. + +Choose from the below guides to deploy the Hasura GraphQL engine and connect it to a Postgres database. + +.. _one_click_deployment_guides: + +One-click deployment options +---------------------------- + +If you want to take Hasura for a spin and check out the features, the following one-click deployments will be useful for you: + +- `Deploy using Hasura Cloud `__ (**recommended**) +- :ref:`Deploy using Heroku ` +- :ref:`Deploy using Render One-click Deploy with Managed PostgreSQL ` +- :ref:`Deploy using Nhost One-click Deploy with Managed PostgreSQL, Storage, and Auth ` + +.. _all_deployment_guides: + +Deployment guides +----------------- + +Choose from the full list of deployment guides: + +- `Deploy using Hasura Cloud `__ (**recommended**) +- :ref:`Deploy using Docker ` +- :ref:`Deploy using Kubernetes ` +- :ref:`Deploy using Heroku ` +- :ref:`Deploy using Digital Ocean One-click App on Marketplace ` +- :ref:`Deploy using Azure Container Instances with Postgres ` +- :ref:`Deploy using Google Cloud Platform with Kubernetes engine and Cloud SQL ` +- `Deploy using Instant GraphQL on AWS RDS (blog) `__ +- :ref:`Deploy using Render One-click Deploy with Managed PostgreSQL ` +- :ref:`Deploy using Nhost One-click Deploy with Managed PostgreSQL, Storage, and Auth ` + +.. admonition:: Custom Docker images or binaries + + If you need a custom Docker image or binary for GraphQL engine, please see :ref:`this page `. + +.. toctree:: + :maxdepth: 1 + :titlesonly: + :hidden: + + Using Hasura Cloud + Using Docker + Using Kubernetes + Using Heroku (one-click) + Using DigitalOcean (one-click) + Using Azure Container Instances + Using Google Cloud Platform & Kubernetes + Using Render (one-click) + Using Nhost (one-click) diff --git a/docs/graphql/manual/deployment/deploying/kubernetes.rst b/docs/graphql/manual/deployment/deploying/kubernetes.rst new file mode 100644 index 00000000000..23928d8a171 --- /dev/null +++ b/docs/graphql/manual/deployment/deploying/kubernetes.rst @@ -0,0 +1,227 @@ +.. meta:: + :description: Deploy Hasura GraphQL engine with Kubernetes + :keywords: hasura, docs, deployment, kubernetes + +.. _deploy_kubernetes: + +Run Hasura GraphQL engine on Kubernetes +======================================= + +.. contents:: Table of contents + :backlinks: none + :depth: 1 + :local: + +Introduction +------------ + +This guide assumes that you already have Postgres running and helps you set up the Hasura GraphQL engine on Kubernetes +and connect it to your Postgres database. + +Deploying Hasura using Kubernetes +--------------------------------- + +Step 1: Get the Kubernetes deployment and service files +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The `hasura/graphql-engine/install-manifests `__ repo +contains all installation manifests required to deploy Hasura anywhere. Get the Kubernetes deployment and service files +from there: + +.. code-block:: bash + + $ wget https://raw.githubusercontent.com/hasura/graphql-engine/stable/install-manifests/kubernetes/deployment.yaml + $ wget https://raw.githubusercontent.com/hasura/graphql-engine/stable/install-manifests/kubernetes/svc.yaml + +Step 2: Set the Postgres database url +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Edit ``deployment.yaml`` and set the right database url: + +.. code-block:: yaml + :emphasize-lines: 4 + + ... + env: + - name: HASURA_GRAPHQL_DATABASE_URL + value: postgres://username:password@hostname:port/dbname + ... + +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 ` to see if the database credentials are proper and if Hasura is able + to connect to the database. + + - The Hasura GraphQL engine needs access permissions on your Postgres database as described in + :ref:`Postgres permissions `. + + +Step 3: Create the Kubernetes deployment and service +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. code-block:: bash + + $ kubectl create -f deployment.yaml + $ kubectl create -f svc.yaml + +Step 4: Open the Hasura console +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The above creates a LoadBalancer type service with port 80. So you should be able to access the console at the +external IP. + +For example, using Docker-for-desktop on Mac: + +.. code-block:: bash + + $ kubectl get svc + NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE + hasura LoadBalancer 10.96.214.240 localhost 80:30303/TCP 4m + kubernetes ClusterIP 10.96.0.1 443/TCP 8m + +Head to: http://localhost and the console should load! + +Step 5: Track existing tables and relationships +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +See :ref:`schema_existing_db` to enable GraphQL over the database. + +.. _kubernetes_secure: + +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. + + +Add the HASURA_GRAPHQL_ADMIN_SECRET env var +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Update the ``deployment.yaml`` to set the ``HASURA_GRAPHQL_ADMIN_SECRET`` environment variable. + +.. code-block:: yaml + :emphasize-lines: 10,11 + + ... + spec: + containers: + ... + command: ["graphql-engine"] + args: ["serve", "--enable-console"] + env: + - name: HASURA_GRAPHQL_DATABASE_URL + value: postgres://username:password@hostname:port/dbname + - name: HASURA_GRAPHQL_ADMIN_SECRET + value: mysecretkey + ports: + - containerPort: 8080 + protocol: TCP + resources: {} + +.. note:: + + The ``HASURA_GRAPHQL_ADMIN_SECRET`` should never be passed from the client to the Hasura GraphQL engine as it would + give the client full admin rights to your Hasura instance. See :ref:`auth` for information on + setting up authentication. + + +(optional) Use the admin secret key with the CLI +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +In case you're using the CLI to open the Hasura console, use the ``admin-secret`` flag when you open the console: + +.. code-block:: bash + + hasura console --admin-secret=myadminsecretkey + +.. _kubernetes_logs: + +Hasura GraphQL engine server logs +--------------------------------- + +You can check the logs of the Hasura GraphQL engine deployed on Kubernetes by checking the logs of the GraphQL engine +service, i.e. ``hasura``: + +.. code-block:: bash + + $ kubectl logs -f svc/hasura + + {"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}} + ... + + +**See:** + +- https://kubernetes.io/docs/concepts/cluster-administration/logging for more details on logging in Kubernetes. + +- :ref:`hge_logs` for more details on Hasura logs + +.. _kubernetes_update: + +Updating Hasura GraphQL engine +------------------------------ + +This guide will help you update the Hasura GraphQL engine running on Kubernetes. This guide assumes that you already have +the Hasura GraphQL engine running on Kubernetes. + +Step 1: Check the latest release version +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The current latest version is: + +.. raw:: html + + hasura/graphql-engine:latest + +All the versions can be found at: https://github.com/hasura/graphql-engine/releases. + +Step 2: Update the container image +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +In the ``deployment.yaml`` file, update the image tag to this latest version. + +For example, if you had: + +.. raw:: html + + + containers:
+ - image: hasura/graphql-engine:v1.0.0-alpha01 + + +you should change it to: + +.. raw:: html + + + containers:
+ - image: hasura/graphql-engine:latest + + +Step 3: Rollout the change +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. code-block:: bash + + $ kubectl replace -f deployment.yaml + + +.. note:: + + If you are downgrading to an older version of the GraphQL engine you might need to downgrade your metadata catalogue version + as described in :ref:`downgrade_hge` + +Advanced +-------- + +- :ref:`Setting up migrations ` + diff --git a/docs/graphql/manual/guides/deployment/nhost-one-click.rst b/docs/graphql/manual/deployment/deploying/nhost-one-click.rst similarity index 98% rename from docs/graphql/manual/guides/deployment/nhost-one-click.rst rename to docs/graphql/manual/deployment/deploying/nhost-one-click.rst index 1b47eeae45f..b58d27463fa 100644 --- a/docs/graphql/manual/guides/deployment/nhost-one-click.rst +++ b/docs/graphql/manual/deployment/deploying/nhost-one-click.rst @@ -17,7 +17,7 @@ Introduction This guide shows how to deploy the Hasura GraphQL engine on `Nhost `__. -One-Click deploy on Nhost +One-click deploy on Nhost ------------------------- .. note:: diff --git a/docs/graphql/manual/guides/deployment/render-one-click.rst b/docs/graphql/manual/deployment/deploying/render-one-click.rst similarity index 97% rename from docs/graphql/manual/guides/deployment/render-one-click.rst rename to docs/graphql/manual/deployment/deploying/render-one-click.rst index 814fd47dc05..4d4f7e98652 100644 --- a/docs/graphql/manual/guides/deployment/render-one-click.rst +++ b/docs/graphql/manual/deployment/deploying/render-one-click.rst @@ -12,9 +12,12 @@ Deploying Hasura GraphQL engine on Render :depth: 1 :local: +Introduction +------------ + This guide shows how to deploy the Hasura GraphQL engine on `Render `__. -One-Click Deploy on Render +One-click Deploy on Render -------------------------- .. note:: diff --git a/docs/graphql/manual/deployment/docker/logging.rst b/docs/graphql/manual/deployment/docker/logging.rst deleted file mode 100644 index dcee4e250e8..00000000000 --- a/docs/graphql/manual/deployment/docker/logging.rst +++ /dev/null @@ -1,34 +0,0 @@ -.. meta:: - :description: Get Hasura GraphQL engine server logs with Docker deployment - :keywords: hasura, docs, deployment, docker, logs - -.. _docker_logs: - -Hasura GraphQL engine server logs (Docker) -========================================== - -.. contents:: Table of contents - :backlinks: none - :depth: 1 - :local: - -You can check the logs of the Hasura GraphQL engine deployed using Docker by checking the logs of the -GraphQL engine container: - -.. code-block:: bash - - $ docker ps - - CONTAINER ID IMAGE ... - cdfbc6b94c70 hasura/graphql-engine.. ... - - $ docker logs cdfbc6b94c70 - - {"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}} - ... - -**See:** - -- https://docs.docker.com/config/containers/logging for more details on logging in Docker. - -- :ref:`hge_logs` for more details on Hasura logs. diff --git a/docs/graphql/manual/deployment/docker/securing-graphql-endpoint.rst b/docs/graphql/manual/deployment/docker/securing-graphql-endpoint.rst deleted file mode 100644 index db633c76a95..00000000000 --- a/docs/graphql/manual/deployment/docker/securing-graphql-endpoint.rst +++ /dev/null @@ -1,36 +0,0 @@ -.. meta:: - :description: Secure Hasura GraphQL endpoint with Docker deployment - :keywords: hasura, docs, deployment, docker, secure - -.. _docker_secure: - -Securing the GraphQL endpoint (Docker) -====================================== - -.. contents:: Table of contents - :backlinks: none - :depth: 1 - :local: - -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 ---------------------------------------------------- - -.. code-block:: bash - :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 - - -.. note:: - - The ``HASURA_GRAPHQL_ADMIN_SECRET`` should never be passed from the client to the Hasura GraphQL engine as it would - give the client full admin rights to your Hasura instance. See :ref:`auth` for information on - setting up authentication. diff --git a/docs/graphql/manual/deployment/docker/updating.rst b/docs/graphql/manual/deployment/docker/updating.rst deleted file mode 100644 index 11bbb8096b1..00000000000 --- a/docs/graphql/manual/deployment/docker/updating.rst +++ /dev/null @@ -1,50 +0,0 @@ -.. meta:: - :description: Update Hasura GraphQL engine with Docker deployment - :keywords: hasura, docs, deployment, docker, update - -.. _docker_update: - -Updating Hasura GraphQL engine running with Docker -================================================== - -.. contents:: Table of contents - :backlinks: none - :depth: 1 - :local: - -This guide will help you update the Hasura GraphQL engine running with Docker. This guide assumes that you already have -Hasura GraphQL engine running with Docker. - -Step 1: Check the latest release version ----------------------------------------- - -The current latest version is: - -.. raw:: html - - hasura/graphql-engine:latest - -All the versions can be found at: https://github.com/hasura/graphql-engine/releases - -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 -latest version. - -For example, if you had: - -.. raw:: html - - docker run hasura/graphql-engine:v1.0.0-alpha01 ... - -you should change it to: - -.. raw:: html - - docker run hasura/graphql-engine:latest ... - -.. note:: - - If you are downgrading to an older version of the GraphQL engine you might need to downgrade your metadata catalogue version - as described in :ref:`downgrade_hge` diff --git a/docs/graphql/manual/deployment/heroku/index.rst b/docs/graphql/manual/deployment/heroku/index.rst deleted file mode 100644 index c16389161f2..00000000000 --- a/docs/graphql/manual/deployment/heroku/index.rst +++ /dev/null @@ -1,125 +0,0 @@ -.. meta:: - :description: Deploy Hasura GraphQL engine with Heroku - :keywords: hasura, docs, deployment, heroku - -.. _deploy_heroku: - -Run Hasura GraphQL engine on Heroku -=================================== - -.. contents:: Table of contents - :backlinks: none - :depth: 2 - :local: - -This guide will help you get the Hasura GraphQL engine running as a "git push to deploy" app on -`Heroku `__ and connecting it to a `Heroku Postgres `__ -instance. If you want a simple, quick deployment on Heroku, follow this :ref:`Heroku one-click -guide `. - -Clone the Hasura GraphQL engine Heroku app ------------------------------------------- - -The Hasura app with Heroku buildpack/configuration is available at: - -https://github.com/hasura/graphql-engine-heroku - -Configure database URL -^^^^^^^^^^^^^^^^^^^^^^ - -Edit the command in the ``Dockerfile`` to change which database the Hasura GraphQL engine connects to. -By default, it connects to the primary database in your app which is available at ``DATABASE_URL``. - -.. code-block:: dockerfile - :emphasize-lines: 6 - - FROM hasura/graphql-engine:latest - - # Change $DATABASE_URL to your Heroku Postgres URL if you're not using - # the primary Postgres instance in your app - CMD graphql-engine \ - --database-url $DATABASE_URL \ - serve \ - --server-port $PORT \ - --enable-console - -Read about more configuration options :ref:`here `. - -.. note:: - - Hasura GraphQL engine needs access permissions to your Postgres database as described in - :ref:`Postgres permissions `. - - -Deploying ---------- - -These are some sample deployment instructions while creating a new app. - -Step 1: Create an app with **--stack=container** -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Use the `Heroku CLI `__ to create a new Heroku app. Let's call -the app ``graphql-on-postgres``. - -.. code-block:: bash - - # Replace graphql-on-postgres with whatever you'd like your app to be called - $ heroku create graphql-on-postgres --stack=container - - Creating ⬢ graphql-on-postgres... done, stack is container - https://graphql-on-postgres.herokuapp.com/ | https://git.heroku.com/graphql-on-postgres.git - -**Note**: - -- ``HEROKU_GIT_REMOTE``: `https://git.heroku.com/graphql-on-postgres.git` -- ``HEROKU_APP_URL``: `https://graphql-on-postgres.herokuapp.com/` - -Step 2: Create the Heroku Postgres add-on -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Create the Postgres add-on in your Heroku app. - -.. code-block:: bash - - $ heroku addons:create heroku-postgresql:hobby-dev -a graphql-on-postgres - - Creating heroku-postgresql:hobby-dev on ⬢ graphql-on-postgres... free - Database has been created and is available - ! This database is empty. If upgrading, you can transfer - ! data from another database with pg:copy - Created postgresql-angular-20334 as DATABASE_URL - Use heroku addons:docs heroku-postgresql to view documentation - -Step 3: **git push** to deploy -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Remember to change ``HEROKU_GIT_REMOTE`` to your git remote below. In our case: -``https://git.heroku.com/graphql-on-postgres.git``. - -.. code-block:: bash - - $ git init && git add . - $ git commit -m "first commit" - $ git remote add heroku HEROKU_GIT_REMOTE - $ git push heroku master - -Visit ``https://graphql-on-postgres.herokuapp.com`` (replace ``graphql-on-postgres`` with your app name) and -you should see the Hasura console. - -Advanced --------- - -- :ref:`Securing your GraphQL endpoint ` -- :ref:`heroku_existing_db` -- :ref:`GraphQL engine server logs ` -- :ref:`Updating GraphQL engine ` -- :ref:`Setting up migrations ` - -.. toctree:: - :titlesonly: - :hidden: - - Securing your GraphQL endpoint - using-existing-heroku-database - GraphQL engine server logs - Updating GraphQL engine diff --git a/docs/graphql/manual/deployment/heroku/logging.rst b/docs/graphql/manual/deployment/heroku/logging.rst deleted file mode 100644 index 0643ca04408..00000000000 --- a/docs/graphql/manual/deployment/heroku/logging.rst +++ /dev/null @@ -1,29 +0,0 @@ -.. meta:: - :description: Get Hasura GraphQL engine server logs with Heroku deployment - :keywords: hasura, docs, deployment, heroku, logs - -.. _heroku_logs: - -Hasura GraphQL engine server logs (Heroku) -========================================== - -.. contents:: Table of contents - :backlinks: none - :depth: 1 - :local: - -You can use the `Heroku CLI `__ to check the logs -of the Hasura GraphQL engine deployed on Heroku: - -.. code-block:: bash - - $ heroku logs --app - - 2018-10-09T11:18:21.306000+00:00 app[web.1]: {"timestamp":"2018-10-09T11:18:21.305+0000", "level":"info", "type":"http-log", "detail":{"status":200, "query_hash":"48c74f902b53a886f9ddc1b7dd12a4a6020d70c3", "http_version":"HTTP/1.1", "query_execution_time":9.477913e-3, "request_id":"b7bb6fb3-97b3-4c6f-a54a-1e0f71a190e9", "url":"/v1/graphql", "user":{"x-hasura-role":"admin"}, "ip":"171.61.77.16", "response_size":15290, "method":"POST", "detail":null}} - ... - -**See:** - -- https://devcenter.heroku.com/articles/logging for more details on logging on Heroku. - -- :ref:`hge_logs` for more details on Hasura logs diff --git a/docs/graphql/manual/deployment/heroku/securing-graphql-endpoint.rst b/docs/graphql/manual/deployment/heroku/securing-graphql-endpoint.rst deleted file mode 100644 index 7c65ac9a9b8..00000000000 --- a/docs/graphql/manual/deployment/heroku/securing-graphql-endpoint.rst +++ /dev/null @@ -1,48 +0,0 @@ -.. meta:: - :description: Secure Hasura GraphQL endpoint with Heroku deployment - :keywords: hasura, docs, deployment, heroku, secure - -.. _heroku_secure: - -Securing the GraphQL endpoint (Heroku) -====================================== - -.. contents:: Table of contents - :backlinks: none - :depth: 1 - :local: - -To make sure that your GraphQL endpoint and the Hasura console are not publicly accessible, you need to -configure an admin secret key. - - -Add the HASURA_GRAPHQL_ADMIN_SECRET env var -------------------------------------------- - -Head to the config-vars URL on your Heroku dashboard and set the ``HASURA_GRAPHQL_ADMIN_SECRET`` environment variable. - -.. thumbnail:: /img/graphql/manual/deployment/secure-heroku.png - :alt: Add an admin secret - -Setting this environment variable will automatically restart the dyno. Now when you access your console, you'll be -prompted for the admin secret key. - -.. thumbnail:: /img/graphql/manual/deployment/access-key-console.png - :alt: Prompt for the admin secret - -.. 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 :ref:`auth` for information on - setting up authentication. - - -(optional) Use the admin secret with the CLI --------------------------------------------- - -In case you're using the CLI to open the Hasura console, use the ``admin-secret`` flag when you open the console: - -.. code-block:: bash - - hasura console --admin-secret=myadminsecretkey - diff --git a/docs/graphql/manual/deployment/heroku/updating.rst b/docs/graphql/manual/deployment/heroku/updating.rst deleted file mode 100644 index c275fe33386..00000000000 --- a/docs/graphql/manual/deployment/heroku/updating.rst +++ /dev/null @@ -1,86 +0,0 @@ -.. meta:: - :description: Update Hasura GraphQL engine with Heroku deployment - :keywords: hasura, docs, deployment, heroku, update - -.. _heroku_update: - -Updating Hasura GraphQL engine on Heroku -======================================== - -.. contents:: Table of contents - :backlinks: none - :depth: 1 - :local: - -This guide will help you update the Hasura GraphQL engine running on Heroku. This guide assumes that you already have a -Hasura GraphQL engine running on Heroku. - -The current latest version is: - -.. raw:: html - - hasura/graphql-engine:latest - -Follow these steps to update Hasura GraphQL engine to the lastest version: - -Step 1: Clone the Hasura GraphQL engine Heroku app --------------------------------------------------- - -The Hasura app with Heroku buildpack/configuration is available at: -https://github.com/hasura/graphql-engine-heroku. - -Clone the above repository. - -.. code-block:: bash - - git clone https://github.com/hasura/graphql-engine-heroku - cd graphql-engine-heroku - -If you already have this, then pull the latest changes which will have the updated GraphQL engine Docker image. - -Step 2: Attach your Heroku app ------------------------------- - -Let's say your Heroku app is called ``hasura-heroku`` and is running on ``https://hasura-heroku.herokuapp.com``. - -Navigate to your project directory, use the `Heroku CLI `__ to configure the git repo you cloned in Step 1 -to be able to push to this app. - -.. code-block:: bash - - # Replace with your Heroku app's name - heroku git:remote -a - heroku stack:set container -a - -You can find your Heroku git repo in your Heroku - Settings - Info - Heroku Git URL - -Step 3: **git push** to deploy the latest Hasura GraphQL engine ---------------------------------------------------------------- - -When you ``git push`` to deploy, the Heroku app will get updated with the latest changes: - -.. code-block:: bash - - git push heroku master - -Deploy a specific version of the Hasura GraphQL engine ------------------------------------------------------- - -Head to the ``Dockerfile`` in the git repo you cloned in step 1. -Change the ``FROM`` line to the specific version you want. A list of all releases can be found -at https://github.com/hasura/graphql-engine/releases. - -.. code-block:: Dockerfile - :emphasize-lines: 1 - - FROM hasura/graphql-engine:v1.0.0 - - ... - ... - -Change ``v1.0.0`` to ``v1.1.0`` for example, commit this and then ``git push heroku master`` to deploy. - -.. note:: - - If you are downgrading to an older version of the GraphQL engine you might need to downgrade your metadata catalogue version - as described in :ref:`downgrade_hge` diff --git a/docs/graphql/manual/deployment/heroku/using-existing-heroku-database.rst b/docs/graphql/manual/deployment/heroku/using-existing-heroku-database.rst deleted file mode 100644 index eb4253745b6..00000000000 --- a/docs/graphql/manual/deployment/heroku/using-existing-heroku-database.rst +++ /dev/null @@ -1,65 +0,0 @@ -.. meta:: - :description: Use an existing database with Heroku deployment - :keywords: hasura, docs, deployment, heroku, existing database - -.. _heroku_existing_db: - -Using an existing Heroku database -================================= - -.. contents:: Table of contents - :backlinks: none - :depth: 1 - :local: - -Let's say you have an existing `Heroku Postgres `__ database with data in it, and you'd -like add GraphQL on it. - -.. note:: - - In case you're exposing an existing database (esp. if it is production), please configure an admin secret key - for the console and the GraphQL endpoint. - -Step 1: Deploy Hasura on Heroku -------------------------------- - -Deploy Hasura on Heroku by clicking on this button: - -.. image:: https://camo.githubusercontent.com/83b0e95b38892b49184e07ad572c94c8038323fb/68747470733a2f2f7777772e6865726f6b7563646e2e636f6d2f6465706c6f792f627574746f6e2e737667 - :width: 200px - :alt: heroku_deploy_button - :class: no-shadow - :target: https://heroku.com/deploy?template=https://github.com/hasura/graphql-engine-heroku - -Follow the Heroku instructions to deploy, check if the Hasura console loads up when you click on **View app** and then head -to the **Manage App** screen on your Heroku dashboard. - -This will deploy Hasura with a free Postgres add-on automatically provisioned. - -Step 2: Remove the created Postgres add-on in the app ------------------------------------------------------ - -Head to your Heroku dashboard and delete the Postgres add-on created in the previous step: - -.. thumbnail:: /img/graphql/manual/deployment/remove-heroku-postgres-addon.png - :alt: Delete the Postgres add-on - -Step 3: Configure environment variables ---------------------------------------- - -Now configure the ``DATABASE_URL`` with your existing Heroku Postgres database URL and a ``HASURA_GRAPHQL_ADMIN_SECRET`` -if you want to secure your endpoint. - -.. thumbnail:: /img/graphql/manual/deployment/heroku-database-url-access.png - :alt: Configure environment variables - -.. note:: - - The Hasura GraphQL engine needs access permissions to your Postgres database as described in - :ref:`Postgres permissions `. - -Step 4: Track tables and relationships --------------------------------------- - -Wait for the GraphQL engine to restart and then see :ref:`schema_existing_db` to enable GraphQL -over the database. diff --git a/docs/graphql/manual/deployment/index.rst b/docs/graphql/manual/deployment/index.rst index b9ba7120d18..3e32baa9923 100644 --- a/docs/graphql/manual/deployment/index.rst +++ b/docs/graphql/manual/deployment/index.rst @@ -12,28 +12,22 @@ Deploying Hasura GraphQL engine :depth: 1 :local: -.. note:: - This section talks in depth about deploying the Hasura GraphQL engine for a **production-like environment**. - If you would simply like to take the Hasura GraphQL engine for a quick spin, choose from our - :ref:`Getting started guides `. - Deployment guides ----------------- -The Hasura GraphQL engine is a binary that is shipped as a Docker container. +This section contains guides to deploy the Hasura GraphQL engine and connect it to a Postgres database. -Choose from the following guides to deploy the Hasura GraphQL engine and connect it to a Postgres database: +If you're looking for quick deployment options, check out the following guides: -- `Deploy using Hasura Cloud `__ -- :ref:`Deploy using Heroku ` -- :ref:`Deploy using Docker ` -- :ref:`Deploy using Kubernetes ` +- :ref:`One-click deployment guides ` -You can also check :ref:`guides_deployment` for more specific examples. +The following is a list of all deployment guides: + +- :ref:`Deployment guides ` .. admonition:: Custom Docker images or binaries - If you need a custom Docker image or binary for GraphQL engine, please see :ref:`this page ` + If you need a custom Docker image or binary for GraphQL engine, please see :ref:`this page `. Configuration @@ -42,9 +36,15 @@ Configuration By default, Hasura GraphQL engine runs in a very permissive mode for easier development. Check out the below pages to configure the Hasura GraphQL engine for your production environment: -- :ref:`securing_graphql_endpoint` -- :ref:`postgres_permissions` - :ref:`GraphQL engine server configuration ` +- :ref:`Postgres requirements ` +- :ref:`Securing the GraphQL endpoint ` +- :ref:`Enable HTTPS ` +- :ref:`Allow-list of operations ` +- :ref:`HTTP compression ` +- :ref:`Updating GraphQL engine ` +- :ref:`Downgrading GraphQL engine ` + Logs ---- @@ -53,23 +53,28 @@ For access to Hasura GraphQL engine logs, check the below page for details: - :ref:`Logging ` +Production checklist +-------------------- + +If you're moving your Hasura GraphQL engine to production, consult the following guide: + +- :ref:`Production checklist ` + .. toctree:: :maxdepth: 1 :titlesonly: :hidden: - Using Heroku - Using Docker - Using Kubernetes + Deployment guides Server configuration postgres-requirements - securing-graphql-endpoint + Securing GraphQL endpoint Server logs Enable HTTPS allow-list HTTP Compression Production checklist Custom Docker images or binaries - Updating GraphQL engine + Updating GraphQL engine Downgrading GraphQL engine diff --git a/docs/graphql/manual/deployment/kubernetes/index.rst b/docs/graphql/manual/deployment/kubernetes/index.rst deleted file mode 100644 index 292e55f95f7..00000000000 --- a/docs/graphql/manual/deployment/kubernetes/index.rst +++ /dev/null @@ -1,106 +0,0 @@ -.. meta:: - :description: Deploy Hasura GraphQL engine with Kubernetes - :keywords: hasura, docs, deployment, kubernetes - -.. _deploy_kubernetes: - -Run Hasura GraphQL engine on Kubernetes -======================================= - -.. contents:: Table of contents - :backlinks: none - :depth: 1 - :local: - -This guide assumes that you already have Postgres running and helps you set up the Hasura GraphQL engine on Kubernetes -and connect it to your Postgres database. - - -Step 1: Get the Kubernetes deployment and service files -------------------------------------------------------- - -The `hasura/graphql-engine/install-manifests `__ repo -contains all installation manifests required to deploy Hasura anywhere. Get the Kubernetes deployment and service files -from there: - -.. code-block:: bash - - $ wget https://raw.githubusercontent.com/hasura/graphql-engine/stable/install-manifests/kubernetes/deployment.yaml - $ wget https://raw.githubusercontent.com/hasura/graphql-engine/stable/install-manifests/kubernetes/svc.yaml - -Step 2: Set the Postgres database url -------------------------------------- - -Edit ``deployment.yaml`` and set the right database url: - -.. code-block:: yaml - :emphasize-lines: 4 - - ... - env: - - name: HASURA_GRAPHQL_DATABASE_URL - value: postgres://username:password@hostname:port/dbname - ... - -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 ` to see if the database credentials are proper and if Hasura is able - to connect to the database. - - - The Hasura GraphQL engine needs access permissions on your Postgres database as described in - :ref:`Postgres permissions `. - - -Step 3: Create the Kubernetes deployment and service ----------------------------------------------------- - -.. code-block:: bash - - $ kubectl create -f deployment.yaml - $ kubectl create -f svc.yaml - -Step 4: Open the Hasura console -------------------------------- - -The above creates a LoadBalancer type service with port 80. So you should be able to access the console at the -external IP. - -For example, using Docker-for-desktop on Mac: - -.. code-block:: bash - - $ kubectl get svc - NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE - hasura LoadBalancer 10.96.214.240 localhost 80:30303/TCP 4m - kubernetes ClusterIP 10.96.0.1 443/TCP 8m - -Head to: http://localhost and the console should load! - -Step 5: Track existing tables and relationships ------------------------------------------------ - -See :ref:`schema_existing_db` to enable GraphQL over the database. - -Advanced --------- - -- :ref:`Securing your GraphQL endpoint ` -- :ref:`GraphQL engine server logs ` -- :ref:`Updating GraphQL engine ` -- :ref:`Setting up migrations ` - -.. toctree:: - :titlesonly: - :hidden: - - Securing your GraphQL endpoint - GraphQL engine server logs - Updating GraphQL engine diff --git a/docs/graphql/manual/deployment/kubernetes/logging.rst b/docs/graphql/manual/deployment/kubernetes/logging.rst deleted file mode 100644 index d0c0f036386..00000000000 --- a/docs/graphql/manual/deployment/kubernetes/logging.rst +++ /dev/null @@ -1,30 +0,0 @@ -.. meta:: - :description: Get Hasura GraphQL engine server logs with Kubernetes deployment - :keywords: hasura, docs, deployment, kubernetes, logs - -.. _kubernetes_logs: - -Hasura GraphQL engine server logs (Kubernetes) -============================================== - -.. contents:: Table of contents - :backlinks: none - :depth: 1 - :local: - -You can check the logs of the Hasura GraphQL engine deployed on Kubernetes by checking the logs of the GraphQL engine -service, i.e. ``hasura``: - -.. code-block:: bash - - $ kubectl logs -f svc/hasura - - {"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}} - ... - - -**See:** - -- https://kubernetes.io/docs/concepts/cluster-administration/logging for more details on logging in Kubernetes. - -- :ref:`hge_logs` for more details on Hasura logs diff --git a/docs/graphql/manual/deployment/kubernetes/securing-graphql-endpoint.rst b/docs/graphql/manual/deployment/kubernetes/securing-graphql-endpoint.rst deleted file mode 100644 index da18f2a5678..00000000000 --- a/docs/graphql/manual/deployment/kubernetes/securing-graphql-endpoint.rst +++ /dev/null @@ -1,57 +0,0 @@ -.. meta:: - :description: Secure Hasura GraphQL endpoint with Kubernetes deployment - :keywords: hasura, docs, deployment, kubernetes, secure - -.. _kubernetes_secure: - -Securing the GraphQL endpoint (Kubernetes) -========================================== - -.. contents:: Table of contents - :backlinks: none - :depth: 1 - :local: - -To make sure that your GraphQL endpoint and the Hasura console are not publicly accessible, you need to -configure an admin secret key. - - -Add the HASURA_GRAPHQL_ADMIN_SECRET env var -------------------------------------------- - -Update the ``deployment.yaml`` to set the ``HASURA_GRAPHQL_ADMIN_SECRET`` environment variable. - -.. code-block:: yaml - :emphasize-lines: 10,11 - - ... - spec: - containers: - ... - command: ["graphql-engine"] - args: ["serve", "--enable-console"] - env: - - name: HASURA_GRAPHQL_DATABASE_URL - value: postgres://username:password@hostname:port/dbname - - name: HASURA_GRAPHQL_ADMIN_SECRET - value: mysecretkey - ports: - - containerPort: 8080 - protocol: TCP - resources: {} - -.. note:: - - The ``HASURA_GRAPHQL_ADMIN_SECRET`` should never be passed from the client to the Hasura GraphQL engine as it would - give the client full admin rights to your Hasura instance. See :ref:`auth` for information on - setting up authentication. - - -(optional) Use the admin secret key with the CLI ------------------------------------------------- - -In case you're using the CLI to open the Hasura console, use the ``admin-secret`` flag when you open the console: - -.. code-block:: bash - - hasura console --admin-secret=myadminsecretkey diff --git a/docs/graphql/manual/deployment/kubernetes/updating.rst b/docs/graphql/manual/deployment/kubernetes/updating.rst deleted file mode 100644 index b40caa332df..00000000000 --- a/docs/graphql/manual/deployment/kubernetes/updating.rst +++ /dev/null @@ -1,66 +0,0 @@ -.. meta:: - :description: Update Hasura GraphQL engine with Kubernetes deployment - :keywords: hasura, docs, deployment, kubernetes, update - -.. _kubernetes_update: - -Updating Hasura GraphQL engine running on Kubernetes -==================================================== - -.. contents:: Table of contents - :backlinks: none - :depth: 1 - :local: - -This guide will help you update the Hasura GraphQL engine running on Kubernetes. This guide assumes that you already have -the Hasura GraphQL engine running on Kubernetes. - -Step 1: Check the latest release version ----------------------------------------- - -The current latest version is: - -.. raw:: html - - hasura/graphql-engine:latest - -All the versions can be found at: https://github.com/hasura/graphql-engine/releases. - -Step 2: Update the container image ----------------------------------- - -In the ``deployment.yaml`` file, update the image tag to this latest version. - -For example, if you had: - -.. raw:: html - - - containers:
- - image: hasura/graphql-engine:v1.0.0-alpha01 - - -you should change it to: - -.. raw:: html - - - containers:
- - image: hasura/graphql-engine:latest - - -Step 3: Rollout the change --------------------------- - -.. code-block:: bash - - $ kubectl replace -f deployment.yaml - - -.. note:: - - If you are downgrading to an older version of the GraphQL engine you might need to downgrade your metadata catalogue version - as described in :ref:`downgrade_hge` - - - diff --git a/docs/graphql/manual/deployment/logging.rst b/docs/graphql/manual/deployment/logging.rst index f335807923e..7473d051d69 100644 --- a/docs/graphql/manual/deployment/logging.rst +++ b/docs/graphql/manual/deployment/logging.rst @@ -20,6 +20,9 @@ Based on your deployment method, the Hasura GraphQL engine logs can be accessed - :ref:`On Heroku ` - :ref:`On Docker ` - :ref:`On Kubernetes ` +- :ref:`On Digital Ocean ` +- :ref:`On Azure ` +- :ref:`On Google Cloud & Kubernetes ` .. _log-types: diff --git a/docs/graphql/manual/deployment/securing-graphql-endpoint.rst b/docs/graphql/manual/deployment/securing-graphql-endpoint.rst index 4a56603b1d7..cb6df6ea45f 100644 --- a/docs/graphql/manual/deployment/securing-graphql-endpoint.rst +++ b/docs/graphql/manual/deployment/securing-graphql-endpoint.rst @@ -21,6 +21,7 @@ access to your GraphQL endpoint and the Hasura console: - :ref:`For Heroku ` - :ref:`For Docker ` - :ref:`For Kubernetes ` +- :ref:`For Digital Ocean ` .. note:: diff --git a/docs/graphql/manual/deployment/updating.rst b/docs/graphql/manual/deployment/updating-graphql-engine.rst similarity index 95% rename from docs/graphql/manual/deployment/updating.rst rename to docs/graphql/manual/deployment/updating-graphql-engine.rst index 7649d5c77ed..1b90c8a33a7 100644 --- a/docs/graphql/manual/deployment/updating.rst +++ b/docs/graphql/manual/deployment/updating-graphql-engine.rst @@ -22,6 +22,7 @@ Based on your deployment method, follow the appropriate guide to update the Grap - :ref:`Updating on Heroku ` - :ref:`Updating on Docker ` - :ref:`Updating on Kubernetes ` +- :ref:`Updating on Digital Ocean ` Latest available versions ------------------------- @@ -47,3 +48,4 @@ The current latest pre-release version is: .. note:: Full stability with pre-release builds is not guaranteed. They are not recommended for production use. + diff --git a/docs/graphql/manual/getting-started/index.rst b/docs/graphql/manual/getting-started/index.rst index 6f534b8c91b..c6be0d29f74 100644 --- a/docs/graphql/manual/getting-started/index.rst +++ b/docs/graphql/manual/getting-started/index.rst @@ -38,8 +38,6 @@ Get started using an existing database - `Using Hasura Cloud `__ **(recommended)**: Create a new Hasura Cloud project connected to an existing Postgres database. - :ref:`Using Docker `: Run as a docker container and connect to an existing Postgres database. -- :ref:`Using Heroku `: Run on Heroku using an existing Heroku - Postgres database. - :ref:`Using Kubernetes `: Run on Kubernetes and connect to an existing Postgres database. diff --git a/docs/graphql/manual/guides/deployment/heroku-one-click.rst b/docs/graphql/manual/guides/deployment/heroku-one-click.rst deleted file mode 100644 index b0eb6ebb24b..00000000000 --- a/docs/graphql/manual/guides/deployment/heroku-one-click.rst +++ /dev/null @@ -1,66 +0,0 @@ -.. meta:: - :description: Get started with Hasura using Heroku - :keywords: hasura, docs, start, heroku - -.. _heroku_one_click: - -One-click deployment with Heroku -================================ - -.. contents:: Table of contents - :backlinks: none - :depth: 1 - :local: - -Introduction ------------- - -This guide will help you get the Hasura GraphQL engine and Postgres running on `Heroku's free tier `__. -It is the easiest and fastest way of trying out Hasura. - -If you'd like to link this to an existing database, please head to this guide instead: -:ref:`Using an existing database on Heroku `. - -Deploy to Heroku ----------------- - -Click the button below to deploy to Heroku: - -.. image:: https://camo.githubusercontent.com/83b0e95b38892b49184e07ad572c94c8038323fb/68747470733a2f2f7777772e6865726f6b7563646e2e636f6d2f6465706c6f792f627574746f6e2e737667 - :width: 200px - :alt: heroku_deploy_button - :class: no-shadow - :target: https://heroku.com/deploy?template=https://github.com/hasura/graphql-engine-heroku - -.. note:: - If you don't have an account on Heroku, you need to sign up on Heroku. You won't need a credit card, and once you - sign up you'll be redirected to your Heroku app creation page automatically. - -.. thumbnail:: /img/graphql/manual/guides/heroku-app.png - :alt: Deploy to Heroku - -Note that **Heroku's free Postgres add-on** is also automatically provisioned! - -Open the Hasura console ------------------------ - -That's it! Head to ``https://.herokuapp.com`` and open your app. -You should see the Hasura console. - -.. thumbnail:: /img/graphql/manual/guides/heroku-app-deployed.png - :alt: Open the Hasura console - -Hello World (GraphQL or event triggers) ---------------------------------------- - -Make your :ref:`first graphql query ` - -OR - -Set up your :ref:`first event trigger ` - -Advanced --------- - -This was a quickstart guide to get the Hasura GraphQL engine up and running quickly. For more detailed instructions -on deploying using Heroku, check out :ref:`deploy_heroku`. diff --git a/docs/graphql/manual/guides/deployment/index.rst b/docs/graphql/manual/guides/deployment/index.rst deleted file mode 100644 index 196ebe0564f..00000000000 --- a/docs/graphql/manual/guides/deployment/index.rst +++ /dev/null @@ -1,39 +0,0 @@ -.. meta:: - :description: Guides for deploying Hasura - :keywords: hasura, docs, guide, deployment - -.. _guides_deployment: - -Guides: Deployment -================== - -.. contents:: Table of contents - :backlinks: none - :depth: 1 - :local: - -- `One-click deployment with Hasura Cloud `__ -- :ref:`One-click deployment with Heroku ` -- :ref:`Digital Ocean One-click App on Marketplace ` -- :ref:`Azure Container Instances with Postgres ` -- :ref:`Google Cloud Platform with Kubernetes engine and Cloud SQL ` -- :ref:`Render One-click Deploy with Managed PostgreSQL ` -- :ref:`Nhost One-click Deploy with Managed PostgreSQL, Storage, and Auth ` -- `Blog: Instant GraphQL on AWS RDS `__ - -.. note:: - The above are guides to deploy the Hasura GraphQL engine on some specific platforms. - - For more generic guides, see :ref:`deployment`. - -.. toctree:: - :maxdepth: 1 - :titlesonly: - :hidden: - - Heroku One-click deployment - DigitalOcean One-click App on Marketplace - Azure Container Instances with Postgres - Google Cloud Platform with Kubernetes engine and Cloud SQL - Render One-click Deploy with managed PostgreSQL - Nhost One-click Deploy with managed PostgreSQL, Storage, and Auth diff --git a/docs/graphql/manual/guides/index.rst b/docs/graphql/manual/guides/index.rst index 43079257296..f229c2dd3b1 100644 --- a/docs/graphql/manual/guides/index.rst +++ b/docs/graphql/manual/guides/index.rst @@ -17,7 +17,6 @@ Guides / Tutorials / Resources :titlesonly: Data modelling guides - Deployment guides Sample apps & boilerplates Integration/migration tutorials Integrating with monitoring frameworks