Documentation for One Click Deploy to Hasura

PR-URL: https://github.com/hasura/graphql-engine-mono/pull/7499
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Co-authored-by: Rob Dominguez <24390149+robertjdominguez@users.noreply.github.com>
Co-authored-by: Rikin Kachhia <54616969+rikinsk@users.noreply.github.com>
Co-authored-by: Praveen Durairaju <14110316+praveenweb@users.noreply.github.com>
GitOrigin-RevId: 3406f6befa84b0f63e51c829b86d2fe6333f9ca2
This commit is contained in:
Aaysha 2023-02-07 14:04:19 +05:30 committed by hasura-bot
parent d00c2051d3
commit 1add19e2a8
18 changed files with 698 additions and 11 deletions

View File

@ -123,7 +123,7 @@ export default ({ history }: SignUpFormProps) => {
</Button>
<div className="AuthScreen-error">{error}</div>
<span className="AuthScreen-alternative">
Already have an accout? <a onClick={handleSignIn}>Sign in!</a>
Already have an account? <a onClick={handleSignIn}>Sign in!</a>
</span>
</form>
</div>

View File

@ -228,14 +228,21 @@ List of domains, **including scheme (http/https) and port**, to allow for CORS.
[Wildcard domains are allowed](/deployment/graphql-engine-flags/config-examples.mdx#configure-cors). **Setting an empty
value will block requests from all other domains**.
| | |
| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Flag** | `--cors-domain <DOMAINS>` |
| **Env var** | `HASURA_GRAPHQL_CORS_DOMAIN` |
| **Accepted values** | String (comma separated list of domains) |
| **Default** | **CE**, **EE**: `null` <br />**Cloud**: `*` Because the Console runs on the 'cloud.hasura.io' domain, Hasura Cloud automatically adds it as an allowed CORS domain. Setting an empty value will block requests from all other domains. |
| **Example** | "https://\*.foo.bar.com:8080, http://\*.localhost, http://localhost:3000, http://example.com" |
| **Supported in** | CE, EE, Cloud |
| | |
| ------------------- | ----------------------------------------------------------------------------------------------|
| **Flag** | `--cors-domain <DOMAINS>` |
| **Env var** | `HASURA_GRAPHQL_CORS_DOMAIN` |
| **Accepted values** | String (comma separated list of domains) |
| **Default** | **CE**, **EE**: `null` <br />**Cloud**: `*` |
| **Example** | "https://\*.foo.bar.com:8080, http://\*.localhost, http://localhost:3000, http://example.com" |
| **Supported in** | CE, EE, Cloud |
:::info Note
Because the Console on Hasura Cloud runs on the 'cloud.hasura.io' domain, Hasura Cloud automatically adds it as an
allowed CORS domain. Setting an empty value will block requests from all other domains.
:::
### Dev Mode
@ -320,7 +327,7 @@ Enable sending compressed logs to [metrics server](/enterprise/metrics.mdx).
### Enable Maintenance Mode
Enabling [maintenance mode](/projects/maintenance-mode.mdx) disables updating of Metadata on the server.
Enabling [maintenance mode](/hasura-cloud/projects/maintenance-mode.mdx) disables updating of Metadata on the server.
| | |
| ------------------- | ------------------------------------------- |
@ -971,7 +978,7 @@ Whether to use prepared statements for queries.
### v1 Boolean Null Collapse
Evaluate `null` values in `where` input object to `True` instead of `error`. Learn more in our
[upgrade guide](/projects/move-project-v2.mdx#sub-tasks-1).
[upgrade guide](/hasura-cloud/projects/move-project-v2.mdx#sub-tasks-1).
| | |
| ------------------- | -------------------------------------------- |

View File

@ -0,0 +1,4 @@
{
"label": "One Click Deploy to Hasura Cloud",
"position": 15
}

View File

@ -0,0 +1,254 @@
---
description: How to Set up a One Click to Deploy to Hasura Apps
keywords:
- hasura
- cloud
- docs
- preview
- review
- test
- pr
- pull request
- GitHub
sidebar_label: Create a One Click Deploy App
sidebar_position: 10
---
import Thumbnail from "@site/src/components/Thumbnail";
import CloudDeployURLGenerationForm from "@site/src/components/CloudDeployURLGenerationForm";
# Create a One Click Deploy to Hasura Cloud App
<div className="badge badge--primary heading-badge">Available on: Cloud</div>
## Introduction
A One Click Deploy to Hasura Cloud app enables anyone to create a Hasura Cloud Project, based on the Hasura assets
available in a GitHub repository, with a click of a `Deploy to Hasura` button. Below, you can find the step-by-step
guide to setting up a One Click Deploy to Hasura App.
## Step 1: Create a public GitHub repository with Hasura assets
One Click Deploy to Hasura Cloud applies Hasura assets, i.e. Metadata, Migrations and Seeds, from a Hasura CLI project
directory present in a public GitHub repository.
If you haven't set up a Hasura CLI project directory, follow the instructions
[here](/migrations-metadata-seeds/migrations-metadata-setup.mdx) to create one from a running Hasura instance.
The file structure of the project directory containing the Metadata, Migration, Seeds should look something like this:
```text
📂 hasura
├─ 📄 config.yaml
├─ 📂 metadata
├─ 📂 migrations
└─ 📂 seeds
```
Once the project directory is created with the application assets, push them to a public GitHub repository to be used as
the source of your One Click Deploy app.
:::info LOOKING FOR AN EXAMPLE?
Check out what a Hasura project directory looks like with this
[e-commerce app](https://github.com/hasura/data-hub/tree/main/data-models/postgres/ecommerce/hasura).
:::
## Step 2: Add a hasura-cloud-deploy-config.yaml file (optional)
If you want to configure some extra details about the One Click Deploy app, a `hasura-cloud-deploy-config.yaml` file can
be added to the hasura assets directory (i.e., the directory containing Migrations, Metadata, and Seeds).
The file structure of the project directory with the `hasura-cloud-deploy-config.yaml` should look something like this:
```text
📂 hasura
├─ 📄 config.yaml
├─ 📂 metadata
├─ 📂 migrations
├─ 📂 seeds
└─ 📄 hasura-cloud-deploy-config.yaml
```
The `hasura-cloud-deploy-config.yaml` accepts the following fields:
- `name`: user-friendly name for your app
- `static-env`: a list of pre-configured environment variables required by the app
- `user-env`: a list of environment variables required by the app that users need to add during deployment
- `description`: a description for the environment variable to help the user during deployment
- `mandatory`: whether the user can skip setting the environment variable
- `default`: _(optional)_ a default value for the environment variable which the user can override during deployment
**Example**: `hasura-cloud-deploy-config.yaml` file
```yaml
name: "hasura-ecommerce-sample-app"
static-env:
HASURA_GRAPHQL_UNAUTHORIZED_ROLE: anonymous
user-env:
PG_DATABASE_URL:
description: "Postgres database URL"
mandatory: true
NEXTJS_SERVER_URL:
default: "http://localhost:3000"
description: "Next.js Server URL for authentication and custom business logic"
mandatory: true
HASURA_GRAPHQL_JWT_SECRET:
default: '{"key": "this-is-the-hasura-nextjs-secret-key-replace-it-with-something-secure","type": "HS256"}'
description: "JWT Secret key"
mandatory: true
```
The prompt to enter the above set of environment variables during deployment would look like the following:
<Thumbnail
src="/img/deployment/one-click-to-deploy/user_env.png"
alt="Initializing Hasura Cloud Project"
width="700px"
/>
:::note Note
Adding a `hasura-cloud-deploy-config.yaml` is optional if the app doesn't need any special environment variables.
Hasura Cloud automatically detects environment variables used for database connection strings from the app metadata and
prompts users to set them even if a `hasura-cloud-deploy-config.yaml` file is not added.
:::
## Step 3: Add a sample-requests.graphql file (optional)
A `sample-requests.graphql` can be added to the hasura assets directory (i.e. the directory containing Migrations,
Metadata, and Seeds) to pre-fill GraphQL request(s) in the Console API explorer once the project has been set up.
The file structure of the project directory with the `sample-requests.graphql` should look something like this:
```text
📂 hasura
├─ 📄 config.yaml
├─ 📂 metadata
├─ 📂 migrations
├─ 📂 seeds
├─ 📄 hasura-cloud-deploy-config.yaml
└─ 📄 sample-requests.graphql
```
**Example**: ``sample-requests.graphql`` file
```graphql
query users {
user {
id
name
}
}
query usersWithOrders {
user {
id
name
orders {
id
status
}
}
}
```
This will render the Console as follows on deployment completion:
<Thumbnail
src="/img/deployment/one-click-to-deploy/project_console.png"
alt="Project console"
width="1200px"
/>
## Step 4: Generate the Deployment URL and button
The following is the structure of the One Click Deploy URL which can also be linked to a `Deploy to Hasura Cloud`
button:
```html
https://cloud.hasura.io/deploy?github_repo=<LINK-TO-GIT-REPO>&hasura_dir=<PATH-TO-HASURA-DIRECTORY-IN-REPO>&branch=<BRANCH-NAME>
```
### One Click Deploy URL
The following form can be used to generate a One Click Deploy to Hasura Cloud URL:
<CloudDeployURLGenerationForm />
<br />
<br />
The generated URL can now be used to trigger a One Click Deploy workflow for your app.
<br />
<br />
### Deploy to Hasura Cloud Button
You can create a `Deploy to Hasura Cloud` button as shown below that can be used to trigger a One Click Deploy workflow
for your app using the URL generated above.
![Deploy to Hasura Cloud](https://hasura.io/deploy-button.svg)
### Snippets to Embed Button
You can use the following snippets to add this button to a markdown file, such as your GitHub repository `README.md` or your dashboards for users to deploy:
#### Markdown
```md
[![Deploy to Hasura Cloud](https://hasura.io/deploy-button.svg)](https://cloud.hasura.io/deploy?github_repo=<LINK-TO-GIT-REPO>&hasura_dir=<PATH-TO-HASURA-DIRECTORY-IN-REPO>&branch=<BRANCH-NAME>)
```
#### HTML
```html
<a href="https://cloud.hasura.io/deploy?github_repo=<LINK-TO-GIT-REPO>&hasura_dir=<PATH-TO-HASURA-DIRECTORY-IN-REPO>&branch=<BRANCH-NAME>"><img src="https://hasura.io/deploy-button.svg" alt="Deploy to Hasura Cloud"/></a>
```
#### URL
```bash
https://cloud.hasura.io/deploy?github_repo=<LINK-TO-GIT-REPO>&hasura_dir=<PATH-TO-HASURA-DIRECTORY-IN-REPO>&branch=<BRANCH-NAME>
```
The `Deploy to Hasura Cloud` button image asset can be found [here](https://hasura.io/deploy-button.svg).
## Step 5: Verify Deployment URL
Once the One Click Deploy URL is generated, verify the link by executing the One Click Deploy workflow as described
[here](./index.mdx).
## Troubleshooting your app
If you encounter any errors in the One Click Deploy workflow for you app, you can attempt to troubleshoot them by
manually deploying your Hasura app via the [Hasura CLI](/hasura-cli/pro-cli/installing-uninstalling.mdx).
- Navigate to [Hasura Cloud](https://cloud.hasura.io/) and create a new Hasura Cloud project.
- Connect the required database(s) needed for your app as shown [here](/databases/connect-db/index.mdx).
- Set any environment variables required for your app as shown [here](/hasura-cloud/projects/env-vars.mdx).
- Navigate to the project's `hasura` directory in your command prompt:
```bash
cd hasura
```
- Verify your Migrations, Metadata and Seeds are in the right format by deploying your app to Hasura Cloud using this
command:
```bash
hasura deploy --with-seeds --endpoint "<hasura-cloud-project-endpoint>" --admin-secret "<admin-secret>"
```
:::info YOUR ENDPOINT
Please take note that the endpoint should end with `hasura.app` not `hasura.app/v1/graphql`.
:::
This command deploys your Hasura project, including Metadata, Migrations and Seeds. If there is any issue with the
Metadata, Migrations, or Seed data in your `hasura` directory, it will provide detailed logs to help you resolve it.

View File

@ -0,0 +1,151 @@
---
description: One Click Deploy to Hasura Cloud
keywords:
- hasura
- quick-start
- one-click-deploy-to-hasura-cloud
- one-click-deploy
slug: index
---
import Thumbnail from "@site/src/components/Thumbnail";
# One Click Deploy to Hasura Cloud
<div className="badge badge--primary heading-badge">Available on: Cloud</div>
## Introduction
One Click Deploy to Hasura Cloud enables you to instantly deploy a Hasura application from a public GitHub repository to
Hasura Cloud. This feature can be used to share Hasura applications with Metadata, Migrations and Seeds with anyone and
they can try them out instantly on Hasura Cloud.
:::info TRY IT OUT
[Create a One Click Deploy app to share your Hasura application](./create-one-click-to-deploy-apps.mdx)!
:::
## How it works
On initiating a One Click Deploy to Hasura Cloud workflow a new Hasura Cloud Project is spun up for you, the source
repository is cloned and Migrations, Metadata and seeds from it are applied to the created Hasura Cloud Project. You
will then be able to try out queries from the Hasura Console of the project. Environment variables, such as database
connection strings, required for the app to be set up are requested during the project setup workflow.
See the detailed steps in the workflow below:
### Step 1: Initiate the One Click Deploy to Hasura Cloud workflow
Click a `Deploy to Hasura Cloud` button or navigate to a One Click Deploy URL to initiate a One Click Deploy to Hasura
Cloud workflow.
#### One Click Deploy URL
A One Click Deploy to Hasura Cloud URL follows the following format:
```html
https://cloud.hasura.io/deploy?github_repo=<github-repo-link>&hasura_dir=<hasura-dir-path>&branch=<branch-name>
```
- **Base URL**: `https://cloud.hasura.io/deploy`
- **URL Params**:
- `github_repo`: URL of the GitHub repository containing the Hasura assets e.g. `https://github.com/hasura/data-hub`
- `hasura_dir`: Path to the directory in the repository containing the Hasura assets e.g.
`data-models/postgres/ecommerce/hasura`
- `branch`: _(optional)_ Branch in the repository from which the assets are picked. If not provided, the default
branch of the repository is used.
#### One Click Deploy button
The One Click Deploy URL is typically linked to a `Deploy to Hasura Cloud` button shown below which can be clicked to
initiate a One Click Deploy workflow:
![Deploy to Hasura Cloud](https://hasura.io/deploy-button.svg)
### Step 2: Create Hasura Cloud Project
Once you initiate the deployment workflow, we'll auto-generate a new Hasura Cloud Project for the deployment of your
app.
<Thumbnail
src="/img/deployment/one-click-to-deploy/project_loading.png"
alt="Initializing Hasura Cloud Project"
width="600px"
/>
Once the Project is created, you will be redirected to the Project's Console for the next steps.
### Step 3: Clone assets from GitHub
Next, we clone the Hasura assets, i.e. Metadata, Migrations and seeds, from the source GitHub repository to be applied
on your Project.
<Thumbnail
src="/img/deployment/one-click-to-deploy/cloning_assets.png"
alt="Clone assets"
width="800px"
/>
### Step 4: Set Environment Variables
If the app you're deploying requires environment variables, like database connection strings, we'll prompt you to enter
those before the assets can be applied
<Thumbnail
src="/img/deployment/one-click-to-deploy/user_env.png"
alt="Setting env vars"
width="800px"
/>
If the app requires a Postgres database, you can create and connect to a free new Neon Postgres database by clicking
`Create New Database`. You can also connect an existing database by clicking `Connect Existing Database`.
After populating the environment variables as required, click on `Set Environment Variables` to proceed.
### Step 5: Apply Migrations, Metadata and Seeds
Next, the Hasura assets, i.e. Metadata, Migrations and seeds, are applied on your Project to complete the application
setup.
<Thumbnail
src="/img/deployment/one-click-to-deploy/project_ready.png"
alt="Project ready"
width="800px"
/>
### Step 6: Explore!!
Your Hasura Cloud App deployment is now complete!
Play around and explore the capabilities of the Hasura GraphQL Engine's pre-generated GraphQL queries. To get started,
try running a few queries from the Hasura Console to interact with the data. See more information on GraphQL queries
generated by Hasura [here](/queries/index.mdx).
<Thumbnail
src="/img/deployment/one-click-to-deploy/project_console.png"
alt="Project console"
width="1200px"
/>
## Troubleshooting
### Failed cloning assets from GitHub
- There might be an intermittent issue with connecting to GitHub. Retrying should typically fix this.
### Failed setting Environment Variables for the project
- Confirm the env vars entered are of the expected format.
- This could be an intermittent issue. Retrying should typically fix this.
### Applying migrations failed
- There might be an issue with your database connection. Please check if the database URL entered is accurate. You can
see the env vars set for your project on the [Env vars](/hasura-cloud/projects/env-vars.mdx) page. In case the
provided env var is not correct, update its value and hit `Launch console` to continue the One Click
Deploy workflow.
- If an existing database is connected, there might be a conflict between the existing schema and the schema being
deployed by the One Click Deploy workflow. In this case, either connect another database or update the connected
database's schema to not conflict with the app schema. You can update the database connection env vars for your
project on the [Env vars](/hasura-cloud/projects/env-vars.mdx) page.

View File

@ -0,0 +1,131 @@
import React, { useState, useEffect } from 'react';
import styles from './styles.module.scss';
const CloudDeployURLGenerationForm = () => {
// URL state
const [repoName, setRepoName] = useState('');
const [branchName, setBranchName] = useState('');
const [pathToDir, setPathToDir] = useState('');
const [url, setUrl] = useState(null);
// UI state
const [isSubmittable, setIsSubmittable] = useState(false);
const [isSubmitted, setIsSubmitted] = useState(false);
// when the inputs change, check if the form is submittable
useEffect(() => {
repoName !== '' ? setIsSubmittable(true) : setIsSubmittable(false);
}, [repoName, branchName, pathToDir]);
// Handle form input change
const handleChange = (e) => {
const { name, value } = e.target;
switch (name) {
case 'github-repo':
setRepoName(value);
break;
case 'github-branch':
setBranchName(value);
break;
case 'mms-path':
setPathToDir(value);
break;
default:
break;
}
};
// Handle 'form' submission
const handleSubmit = () => {
// check for empty fields
if (repoName === '') {
alert('The repository name is empty. Please fill it out before proceeding.');
return;
}
// check for whitespace or spaces in the fields
if (repoName.includes(' ') || branchName.includes(' ') || pathToDir.includes(' ')) {
alert('One or more fields contain whitespace. Please remove it and try again.');
return;
}
const url = 'https://cloud.hasura.io/deploy'
+ `?github_repo=${repoName}`
+ `&hasura_dir=${pathToDir !== '' ? pathToDir : '/' }`
+ ((branchName !== '') ? `&branch=${branchName}` : '');
setUrl(url);
navigator.clipboard.writeText(url);
setIsSubmitted(true);
};
const handleClear = () => {
setRepoName('');
setBranchName('');
setPathToDir('');
setUrl(null);
setIsSubmitted(false);
};
return (
// we're calling the styles object here to apply the styles to the elements using their class names
<div className={styles['form-container']}>
<div>
<label for='github-repo'>Repository URL</label>
<small>
Enter the URL of the GitHub repository containing the Hasura assets
</small>
<input
type='text'
id='github-repo'
name='github-repo'
value={repoName}
onChange={(e) => handleChange(e)}
placeholder='e.g. https://github.com/your-github-username/repository-name'
/>
</div>
<div>
<label for='mms-path'>Path to directory containing Hasura assets</label>
<small>
Enter the path to the directory containing your Metadata, Migrations and Seeds. If these are present in the root directory of the repository, you can skip this.
</small>
<input
type='text'
id='mms-path'
name='mms-path'
value={pathToDir}
onChange={(e) => handleChange(e)}
placeholder='e.g. hasura'
/>
</div>
<div>
<label htmlFor='github-branch'>Branch name</label>
<small>
Enter the repository branch the Hasura assets should be picked from. If you'd like to use the default branch of your repository, you can skip this.
</small>
<input
type='text'
id='github-branch'
name='github-branch'
value={branchName}
onChange={(e) => handleChange(e)}
placeholder='e.g. main'
/>
</div>
<div className={styles['code-block']} style={{ maxHeight: isSubmitted && `800px` }}>
{isSubmitted && <p>Awesome! We've copied this link to your clipboard for you 🎉</p>}
<code>{url}</code>
</div>
<div className={styles['button-container']}>
<button onClick={() => handleClear()}>Clear form</button>
<button
onClick={() => handleSubmit()}
disabled={!isSubmittable}
style={{ cursor: isSubmittable ? 'pointer' : 'not-allowed' }}
title={isSubmittable ? 'Click to submit' : 'Please fill out all required fields'}
>
Generate URL
</button>
</div>
</div>
);
};
export default CloudDeployURLGenerationForm;

View File

@ -0,0 +1,140 @@
.form-container {
display: flex;
flex-direction: column;
padding: 1rem;
border-radius: 5px;
background: var(--ifm-color-emphasis-100);
div {
display: flex;
flex-direction: column;
margin: 10px;
label {
font-weight: var(--ifm-font-weight-bold);
}
input {
border: none;
border-radius: 6px;
font-size: 1.1rem;
padding: 0.75rem;
font-family: var(--ifm-font-family-base);
color: var(--color-gray-74);
margin-top: 1rem;
margin-bottom: 1.5rem;
box-shadow: var(--ifm-global-shadow-lw);
width: 100%;
&::placeholder {
color: var(--color-gray-36);
}
}
}
small {
color: var(--ifm-color-emphasis-800);
font-size: 0.9rem;
margin-top: 0.5rem;
}
}
.button-container {
display: flex;
flex-direction: row !important;
margin-left: auto;
gap: 1rem;
justify-content: end;
align-self: end;
align-content: flex-end;
button {
width: 150px;
background: var(--ifm-color-primary);
color: white;
font-weight: 500;
font-size: 16px;
font-family: var(--ifm-font-family-base);
border: none;
border-radius: 6px;
padding: 0.5rem 1rem;
cursor: pointer;
&:hover {
background: var(--ifm-color-primary-dark);
}
}
button:first-child {
background: var(--ifm-color-emphasis-600);
&:hover {
background: var(--ifm-color-emphasis-700);
}
}
@media (max-width: 768px) {
flex-direction: column !important;
gap: 0.5rem;
width: 100%;
margin: 0.5rem;
padding: 0.5rem;
align-self: center;
button {
width: 100%;
}
}
}
.code-block {
max-height: 0;
overflow: hidden;
transition: ease-in-out 0.3s;
background: var(--ifm-color-primary);
border-radius: 5px;
code {
display: grid;
place-items: center center;
border-radius: 5px;
padding: 0.75rem;
height: 70px;
white-space: nowrap;
overflow-x: scroll;
margin: 0.5rem;
}
p {
color: white;
margin: 0.5rem;
}
}
html[data-theme='dark'] {
.form-container {
background-color: var(--color-gray-82);
}
.form-container div input {
background-color: var(--color-gray-74);
color: var(--color-gray-20);
}
.button-container {
button {
&:hover {
background: var(--ifm-color-primary-darker);
}
}
button:first-child {
background: var(--ifm-color-emphasis-800);
color: var(--color-gray-60);
&:hover {
background: var(--ifm-color-emphasis-700);
}
}
}
}

Binary file not shown.

After

Width:  |  Height:  |  Size: 28 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 21 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 280 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 230 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 110 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 109 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 197 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 48 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 38 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 59 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 59 KiB