RFC: One Click Deploy to Hasura Cloud

[vaishnavigvs]

Hey folks, we are working on a new feature that let's you deploy an example Hasura project to Hasura Cloud. We would love to get some feedback and suggestions on the workflow and the approach or anything we're missing out. Any inputs are appreciated!

Problem definition

• It’s currently difficult to share an example Hasura project and then re-deploy it on Hasura Cloud for users to try.
• Current solutions (manual CLI / GitHub Deploy) require knowledge about Hasura and the CLI in order to get started which is too much friction for new users.

Who are we building for?

Hasura users

• May be brand-new to Hasura and want to deploy and demo a solution which has been shared with them.
• May be attempting to try a specific feature or context within Hasura.
• May be trying to see a specific example implementation which they’ve viewed online.

Contributors of sample projects

• A partner looking to create an example of how our integrations can work together (examples being Actions, Postgres extensions, etc.).
• A Hasura employee / team (marketing / documentation) who is creating demos to share with the community.
• Workshop coordinators who create Hasura examples (and currently have their classes use CLI to deploy their final example manually).
• A team looking to share examples of their work within their organization (or outside with stakeholders).
• An individual looking to create an example of their usage to publish with the community.

Who are we not building for?

• Deployments. This is not meant to be a replacement for deployments, but a way to share snapshots within the community / across user groups.
  • A user is essentially forking the sample project into Hasura Cloud, instead of continuously deploying it.
• Secret / proprietary information. Generally, we’re looking to position the majority of the use cases for this feature around sharing public examples which can be viewed without authorization (/ shared in public repos)
  • With the exception of secrets placeholders which can be filled in by the Hasura user at project runtime.

Proposed solution

• Any directory in a public Github repo with the necessary information can be used as a sample project. A Hasura Cloud service accepts a URL to that repo+directory (with optional branch as well) to create a new Hasura Cloud project based on the sample. This URL can be the target of buttons and links (blogs, websites, or shared as is).
• Structure of the directory in the GitHub repository:
  • It will be a Hasura project as generated by the Hasura CLI with metadata and migrations folders (seeds may be added as needed by the example project)
  • A hasuraconfig.yaml for any auxiliary information required, such as additional environment variables
    • Static env vars: to be defined by the author, such as feature flags
    • User input env vars: Will be taken from the user on the UI - Like DB URLs, Action endpoints etc
    • Example hasuraconfig.yaml
  • Sample GraphQL query to help users get started quickly with the example project
• For the first draft of the solution, we’re looking to concentrate on minimizing friction for the Hasura user persona; later versions could also include enhancements to the publishing process.
• By default, the workflow will require no hasuraconfig.yaml file, where we parse the metadata to identify environment variables like database urls. Any additional config needs to be specified in the hasuraconfig.yaml file

Information Architecture

What’s necessary for loading a project?

Available here

User Journey (Happy Path)

How does a user go about launching a shared project?

Available here

Wireframes

Available here

Unhappy States

Shared project error state based on:

1. The share link was invalid.

   • We’ll do some form of parsing when loading the shareable project link and will be able to figure out if the repo is generally viable.
   • Mitigations:
     • Re-check project status.
     • Give the user feedback about what part of the project was erroneous (ie. what was the error in the metadata that caused the check failure).
     • Give the user a link back to the repo they came from with feedback to contact the author.
     • Log projects which are having trouble passing validation (proactively reach-out to authors).

2. The project wasn’t created successfully.

   • Something happened in the account creation process (probably infra based).
   • Mitigations:
     • Retry creating project.

3. Env vars failed updating.

   • Mitigations:
     • Was there a problem with the specific formatting of one of the environment variables? Highlight and call-out the issue at the field level.
     • Was a database not able to be connected to? Give a callout with a trace of the error - highlight that env var field.
     • General / infra based - retry updating env variables.

4. Database cannot connect.

   • Mitigations:
     • Fallback on the database latency cannot connect messaging.
     • Try to re-apply metadata to get the database to connect.
     • Try to update an env var to get the database to connect.

5. Metadata update failed.

   • Mitigations:
     • Is it a server / connectivity issue? Retry applying metadata.
     • Is it a database connectivity issue? Retry / allow the user to edit data sources which are connected to solve the connectivity issue.
     • Any other type of metadata issue? Retry / view metadata / link to repo to contact the author to repair the file.

6. Migrations failed.

   • Mitigations:
     • Show the user the error messaging coming back from the database.
     • Allow the user to attempt re-running the migration.
     • Allow the user to edit the erroneous SQL and re-run.
     • Give the user a link to the repo to contact the author to repair the file.

Measurement of failure states

• Env variables - what kind of projects are causing the most problems (sophisticated variables, databases, etc.)
• Metadata update failures - introspect the metadata which is failing - is there a common pattern to be found (data sources, actions, etc.)?
• Is there a common error code or set of errors which are being triggered by migrations (already exists errors, database timeout, etc.)?
• Malformed projects (count of failures in validation, metadata failure, and migration failure) - proactively follow-up with creators since this is a generally bad experience for users.