mirror of
https://github.com/hasura/graphql-engine.git
synced 2024-09-11 10:46:25 +03:00
docs: add cloud manging envs guide
https://github.com/hasura/graphql-engine-mono/pull/2175 Co-authored-by: Rikin Kachhia <54616969+rikinsk@users.noreply.github.com> GitOrigin-RevId: 5fee7757c408e97ddd82f479efb17476f44f6607
This commit is contained in:
parent
7720496b95
commit
487b400445
170
docs/graphql/cloud/projects/environments.rst
Normal file
170
docs/graphql/cloud/projects/environments.rst
Normal file
@ -0,0 +1,170 @@
|
||||
.. meta::
|
||||
:description: Guide for managing development environments for Hasura Cloud
|
||||
:keywords: hasura, docs, cloud, guide, local dev, staging, production, environment
|
||||
|
||||
.. _guide_environments_cloud:
|
||||
|
||||
Managing development environments with Hasura Cloud
|
||||
===================================================
|
||||
|
||||
.. contents:: Table of contents
|
||||
:backlinks: none
|
||||
:depth: 2
|
||||
:local:
|
||||
|
||||
Introduction
|
||||
------------
|
||||
|
||||
This guide will show how to configure your Hasura project for easy switching between development environments.
|
||||
|
||||
Moving from Hasura Cloud to local development
|
||||
---------------------------------------------
|
||||
|
||||
Step 1: Setup local development of Hasura with Docker
|
||||
"""""""""""""""""""""""""""""""""""""""""""""""""""""
|
||||
|
||||
Follow the guide :ref:`here<docker_simple>` to get up and running with Hasura GraphQL engine and Postgres as
|
||||
Docker containers in your local system.
|
||||
Make sure that the ENV variable for database connection in your local setup is same as
|
||||
that in your Cloud project. Also add any other ENV variables that you might have set on the Cloud project.
|
||||
|
||||
Step 2: Install Hasura CLI
|
||||
""""""""""""""""""""""""""
|
||||
|
||||
Follow the instructions in :ref:`install_hasura_cli`
|
||||
|
||||
Step 3: Initialize a Hasura CLI project locally
|
||||
"""""""""""""""""""""""""""""""""""""""""""""""
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
hasura init <project-name>
|
||||
|
||||
Step 4: Initialize the migration files
|
||||
""""""""""""""""""""""""""""""""""""""
|
||||
|
||||
This will get your database schema from the cloud project to your local setup
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
hasura migrate create init --from-server --endpoint <hasura-cloud-project-url> --admin-secret <admin-secret> --database-name <database-name>
|
||||
|
||||
# note down the version
|
||||
|
||||
# mark the migration as applied on the cloud project
|
||||
|
||||
hasura migrate apply --endpoint <hasura-cloud-project-url> --admin-secret <admin-secret> --version <version-number> --skip-execution
|
||||
|
||||
It is important to mark the migration as applied on the Cloud project to ensure that the schema that is already created on Hasura
|
||||
Cloud project is not attempted to be recreated again, which would end in an error state.
|
||||
|
||||
Step 5: Export metadata
|
||||
"""""""""""""""""""""""
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
hasura metadata export --endpoint <hasura-project-url> --admin-secret <admin-secret>
|
||||
|
||||
We have successfully synced our state from Cloud to the Hasura CLI local dev
|
||||
environment.
|
||||
|
||||
Next, we apply all these changes to our local Hasura with Docker setup.
|
||||
|
||||
Step 6: Apply metadata and migrations to your local Hasura instance
|
||||
"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
hasura metadata apply
|
||||
hasura migrate apply --all-databases
|
||||
hasura metadata reload
|
||||
|
||||
By default the metadata and migrations are applied to ``http://localhost:8080`` which
|
||||
is the endpoint specified in the ``config.yaml`` file of your CLI project. If you want to
|
||||
apply the metadata and migrations to any other endpoint, you could go ahead and change the endpoint in
|
||||
the ``config.yaml`` file or use the ``--endpoint`` flag along with the commands above.
|
||||
|
||||
And you're all set now! Go ahead and setup version control for your project for further
|
||||
ease of integration.
|
||||
|
||||
Moving from local development to Hasura Cloud
|
||||
---------------------------------------------
|
||||
|
||||
If you have been using the OSS version of Hasura GraphQL engine locally using Docker
|
||||
and want to move to a Hasura Cloud project, start by creating a project at `<cloud.hasura.io>`__
|
||||
|
||||
Once the project is created, launch console and connect your database. Make sure that the
|
||||
name of the database is same as that in your local setup.
|
||||
Do refer this :ref:`Getting Started guide<cloud_getting_started>` for a step-by-step guide.
|
||||
|
||||
Also ensure the database is connected using the same ENV var in your local setup and the Cloud project. You might
|
||||
have drop and create a new ENV var containing the database URL on your Cloud project if required.
|
||||
|
||||
Also add any other ENV vars that you might have set on your local project.
|
||||
|
||||
Setting up a Git repo for your Hasura project
|
||||
"""""""""""""""""""""""""""""""""""""""""""""
|
||||
|
||||
In order to easily apply your local changes to your new Cloud project, we'll use the
|
||||
Hasura :ref:`GitHub deployment<github_integration>` feature. But before we do that,
|
||||
we need to setup metadata & migrations of your local setup that you can apply to your
|
||||
Cloud project.
|
||||
For a lowdown on Hasura metadata & migrations refer the guide :ref:`here<migrations>`
|
||||
|
||||
Step 1: Install Hasura CLI
|
||||
""""""""""""""""""""""""""
|
||||
|
||||
Follow the instructions in :ref:`install_hasura_cli`
|
||||
|
||||
|
||||
Step 2: Setup a project directory
|
||||
"""""""""""""""""""""""""""""""""
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
hasura init <project-name> --endpoint <local-project-endpoint>
|
||||
|
||||
Your local project endpoint might be ``http://localhost:8080`` (based on how it was setup
|
||||
initially). This creates a project directory with ``migrations`` and ``metadata``
|
||||
directories and a ``config.yaml`` file.
|
||||
|
||||
|
||||
Step 3: Initialize the migration files
|
||||
""""""""""""""""""""""""""""""""""""""
|
||||
|
||||
This will get your database schema from your local setup into the project folder.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
hasura migrate create init --from-server --admin-secret <admin-secret> --database-name <database-name>
|
||||
|
||||
# note down the version
|
||||
|
||||
# mark the migration as already applied on the local server
|
||||
|
||||
hasura migrate apply --admin-secret <admin-secret> --version <version-number> --skip-execution
|
||||
|
||||
Step 4: Initialize Hasura metadata
|
||||
""""""""""""""""""""""""""""""""""
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
hasura metadata export
|
||||
|
||||
This command will export the current Hasura metadata as a bunch of YAML files in the ``metadata`` directory.
|
||||
|
||||
Step 5: Setup version control & Git Deploy
|
||||
""""""""""""""""""""""""""""""""""""""""""
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
# in the project directory
|
||||
|
||||
git init
|
||||
git add .
|
||||
git commit -m "initialize metadata and migrations"
|
||||
|
||||
Push these changes to GitHub repo of your choice.
|
||||
|
||||
Now we're all set to see the magic of our GitHub integration to deploy the metadata and migrations to your
|
||||
Cloud project by following the steps :ref:`here<github_integration>`!
|
@ -60,6 +60,7 @@ Dig deeper
|
||||
Securing projects <secure>
|
||||
Switching pricing plans <pricing>
|
||||
Deployment regions <regions>
|
||||
Managing development environments <environments>
|
||||
GitHub Deployment <github-integration>
|
||||
Heroku database URL Sync <heroku-url-sync>
|
||||
Maintenance mode <maintenance-mode>
|
||||
|
Loading…
Reference in New Issue
Block a user