Local Development

Nhost’s command-line interface (CLI) lets you run a complete Nhost development environment locally with the following services: PostgreSQL database, Hasura, Authentication, Storage (MinIO), Serverless Functions, and Emails (Mailhog).

Dependencies

Git
Docker

Supported platforms

MacOS
Linux
Windows (via WSL2)¹

Installing Nhost’s CLI

sudo curl -L https://raw.githubusercontent.com/nhost/nhost/main/cli/get.sh | bash

nhost login

Initialize local project

Let’s start by creating a directory to hold your project.

mkdir my-project
cd my-project

We can now initialize and create the necessary project configuration.

nhost init

nhost init creates all the configuration necessary for your project, including database migrations and Hasura metadata.

We can now start your project with nhost up.

nhost up

Once all services are up and running, the following information is displayed for your project:

Nhost development environment started.

URLs:
- Postgres:             postgres://postgres:postgres@localhost:5432/local
- Hasura:               https://local.hasura.local.nhost.run
- GraphQL:              https://local.graphql.local.nhost.run
- Auth:                 https://local.auth.local.nhost.run
- Storage:              https://local.storage.local.nhost.run
- Functions:            https://local.functions.local.nhost.run
- Dashboard:            https://local.dashboard.local.nhost.run
- Mailhog:              https://local.mailhog.local.nhost.run

SDK Configuration:
 Subdomain:             local
 Region:                (empty)

Run `nhost up` to reload the development environment
Run `nhost down` to stop the development environment
Run `nhost logs` to watch the logs

You can use nhost down at any time to tear down your environment.

Access your project’s services

To test that the services are running, let’s curl the Auth endpoint and get its version:

curl https://local.auth.local.nhost.run/v1/version

{"version":"v0.20.1"}

Hurrah! Auth seems to be running on v0.20.1.

We can also test that Postgres is running as expected by using psql (or your favourite Postgres client).

psql postgres://postgres:postgres@localhost:5432/local

psql (14.8 (Ubuntu 14.8-0ubuntu0.22.04.1), server 14.6 (Debian 14.6-1.pgdg110+1))
Type "help" for help.

local=#

Database Migrations and Metadata Changes

All changes to your project should be tested locally first before deploying to your users. In this guide, we will be creating a database migration and setting permissions.

Migration

Let’s create a new table called messages, with the following columns:

id (UUID)
text (Text)
author_id (UUID)
created_at (Timestamp)

There are other ways to generate a migration, here we will use the local Nhost Dashboard running on https://local.dashboard.local.nhost.run/local/local. Please head to the database tab and add the columns as follows:

Nhost Local Dashboard

To confirm that the migration was correctly generated with the correct SQL:

cat nhost/migrations/default/1685452095884_create_table_public_messages/up.sql

CREATE TABLE public.messages (id uuid DEFAULT gen_random_uuid() NOT NULL, text text NOT NULL, author_id uuid NOT NULL, created_at timestamp DEFAULT now() NOT NULL, PRIMARY KEY (id));

Now is a good time to commit the new migration.

git add .
git commit -m 'add database migration to create the table `messages`'

Metadata

Metadata is used to track the state of the API, permissions, event triggers, remote schemas, etc. In this guide, we will use permissions to show how metadata is tracked.

Again on the database tab of the Nhost Dashboard, click on the 3 dots right next to the table name and choose “Edit Permissions” to open the permissions editor.

Permissions Editor

Here we have access to a matrix of permissions for all available roles and actions. We want to set a permission to the user role and insert action as follows:

Permissions Editor

We defined a simple permission to allow a user to insert or create messages. We can look at the underlying metadata that tracks it.

cat nhost/metadata/databases/default/tables/public_messages.yaml

table:
  name: messages
  schema: public
insert_permissions:
  - role: public
    permission:
      check:
        author_id:
          _eq: X-Hasura-User-Id
      set:
        author_id: X-Hasura-User-Id
      columns:
        - text

As before, we can now commit this change:

git add .
git commit -m 'add permission for user insert messages'

Deploy your Project to Nhost

We’ve been developing your project locally, introducing changes via the Dashboard, which in turn creates the actual database migrations and metadata changes that can be properly versioned and tracked. It’s time to deploy your project to the Nhost Platform using Git. If you haven’t already, please head to Nhost and create a project to deploy to. You will also need to connect a GitHub repository to it for automatic deployments with Git.

Link your project

It’s time to link, or associate, your local project to the remote one:

nhost link

    │                      │                                 │                  │              │
 #  │ Subdomain            │ Project                         │ Workspace        │ Region       │
 1  │ kgrbyupffiamgqwnovkb │ local-development               │ Nhost            │ eu-central-1 │
 2  │ odtxlexktkcwdynjssqg │ nbp                             │ Nuno's Workspace │ eu-central-1 │
    │                      │                                 │                  │              │
- Select the workspace # to link: 1
- Enter project subdomain to confirm: kgrbyupffiamgqwnovkb

You have now successfully linked your local project to a hosted project running on the Nhost Cloud.

The final step is to push all changes to GitHub which will trigger a new deployment on Nhost.

git add -A
git push -u origin main

To check out your deployment, head over to the Deployments tab (https://app.nhost.io).

Deployments

You should now have the same messages table (and permissions) on your production instance!