mirror of
https://github.com/hasura/graphql-engine.git
synced 2024-12-18 13:02:11 +03:00
352 lines
11 KiB
ReStructuredText
352 lines
11 KiB
ReStructuredText
.. 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: 1
|
|
:local:
|
|
|
|
Introduction
|
|
------------
|
|
|
|
This guide shows how to deploy Hasura GraphQL engine on Heroku.
|
|
|
|
Deploying Hasura with a new Postgres DB
|
|
---------------------------------------
|
|
|
|
.. contents::
|
|
:backlinks: none
|
|
:depth: 1
|
|
:local:
|
|
|
|
.. _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/core/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 <https://devcenter.heroku.com/articles/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 <https://www.heroku.com/postgres>`__ database with data in it, and you'd
|
|
like to add GraphQL to it.
|
|
|
|
.. contents::
|
|
:backlinks: none
|
|
:depth: 1
|
|
:local:
|
|
|
|
.. note::
|
|
|
|
As you're exposing an existing database, please :ref:`configure an admin secret <heroku_secure>`
|
|
to prevent public access of 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 <heroku_one_click>`.
|
|
|
|
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/core/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 <heroku_secure>`.
|
|
|
|
.. thumbnail:: /img/graphql/core/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 <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 <https://www.heroku.com/platform>`__ and connect it to a `Heroku Postgres <https://www.heroku.com/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 <server_flag_reference>`.
|
|
|
|
.. note::
|
|
|
|
Hasura GraphQL engine needs access permissions to your Postgres database as described in
|
|
:ref:`Postgres permissions <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/core/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/core/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 <https://devcenter.heroku.com/articles/heroku-cli>`__ to check the logs
|
|
of the Hasura GraphQL engine deployed on Heroku:
|
|
|
|
.. code-block:: bash
|
|
|
|
$ heroku logs --app <hasura-graphql-engine-app-name>
|
|
|
|
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
|
|
|
|
<code>hasura/graphql-engine:<span class="latest-release-tag">latest</span></code>
|
|
|
|
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 <https://devcenter.heroku.com/articles/heroku-cli>`__ to configure the git repo you cloned in Step 1
|
|
to be able to push to this app.
|
|
|
|
.. code-block:: bash
|
|
|
|
# Replace <hasura-heroku> with your Heroku app's name
|
|
heroku git:remote -a <hasura-heroku>
|
|
heroku stack:set container -a <hasura-heroku>
|
|
|
|
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 <migrations>`
|