Midspace: Hasura

We use the Hasura GraphQL engine to power the interface between the frontend and all of our backend services.

Pre-requisites

1. Docker Compose
2. Hasura CLI
3. Full Setup: A SendGrid account per instructions in the main README.

Setting Up

1. cp hasura/.env.example hasura/.env.local
2. In hasura/.env.local set the value of HASURA_GRAPHQL_ADMIN_SECRET to the Hasura admin secret value generated at the beginning of this setup process. Set the value of EVENT_SECRET to another secure random value.
3. Run the Hasura Console -- Local Development task within VSCode: Terminal > Run Task. This will start the GraphQL engine in Docker first, and that VSCode task will prompt for a Docker project name with a default filled in. Press enter to accept the default.
   • If you find that the Docker container runs out of memory or crashes on first startup, then we recommend applying the migrations and writing the Hasura metadata sequentially. To do this, comment out the volume ./hasura/metadata:/hasura-metadata in docker-compose.yaml and run the Hasura Console -- Local Development task. Once complete, uncomment ./hasura/metadata:/hasura-metadata and run Hasura Console -- Local Development again.
4. Check that the Docker Compose task ran successfully in the Task Output
   • If you get an error from this task, make sure the Docker app is running first!
5. Check that the Hasura Console task ran successfully in the Task Output
   • If you get an error message about version check: failed to get version from server: failed making version api call... try running the task again -- there is a race condition that can cause this.
6. Your browser should have opened a tab to the Hasura Console. Open the system.Configuration table (click the DATA tab at top, expand the system schema on the left, and click the Configuration table) and insert the rows listed below. Production: If running Midspace in a production environment, you will need to insert rows into the system.Configuration table for all available keys, not just those listed here. Refer to the description field of each key (in system.ConfigurationKey) for expected values for the remaining keys.

   Key	Value
   SENDGRID_API_KEY	your SendGrid API key, as a JSON string (i.e. wrapped in double quotes)
   SENDGRID_WEBHOOK_PUBLIC_KEY	your SendGrid webhook signed requests public key, as a JSON string (i.e. wrapped in double quotes)
   SENDGRID_SENDER	the 'from' email address you wish to use for emails sent by Midspace, as a JSON string
   SENDGRID_REPLYTO	the 'reply-to' email address you wish to use for emails sent by Midspace, as a JSON string
   HOST_ORGANISATION_NAME	Name of your organization to appear in email footers, as a JSON string
   STOP_EMAILS_CONTACT_EMAIL_ADDRESS	Contact address for emails received in error, as a JSON string
   DEFAULT_FRONTEND_HOST	Either http://localhost:3000 or your public frontend URL, as a JSON string

Now return to the main README.

Local Development

See root ReadMe instructions for local development for which tasks to run.

Note: If the environment configuration for Hasura/Postgres or the Docker Compose configuration change, then the Hasura local-dev tasks will need to be restarted (which will also apply the changes to Docker).

Remote Deployment

We use GitHub Actions (a.k.a. Workflows) to automatically deploy new versions to Hasura Cloud and run migrations.

Branch	Hasura Cloud Instance
develop	ci-testing
staging	staging
main	production

Environment Files

Name	Purpose
.env.local	Local development
.env.ci-test	Hasura Console connection to Hasura Cloud for managing the CI instance
.env.staging	Hasura Console connection to Hasura Cloud for managing the staging instance
.env.production	Hasura Console connection to Hasura Cloud for managing the production instance

Hasura Cloud Configuration

Env Var	Value
HASURA_GRAPHQL_ADMIN_SECRET	A secure random value
HASURA_GRAPHQL_DATABASE_URL	Allow Hasura to configure this
ACTION_BASE_URL	The Heroku Actions Service uri - no trailing slash
REALTIME_BASE_URL	The Heroku Presence Service uri - no trailing slash
EVENT_SECRET	The secret to be sent for event trigger auth
HASURA_GRAPHQL_UNAUTHORIZED_ROLE	unauthenticated