Developing with DDN workspace

Introduction

DDN Workspace provides a browser-based development environment for working with Private DDN, eliminating the need to install DDN CLI and its dependencies locally. It features a familiar VS Code-like UI, runs directly on your data plane, and includes all necessary dependencies required to work with DDN pre-installed.

This guide will walk you through the steps for using DDN workspace to develop your API on a Data Plane in Private Hasura DDN. Before proceeding, you'll first need to be invited to a Data Plane.

Prerequisite

To provision a new workspace in Private DDN, please reach out to us here.

We recommend a dedicated workspace for each developer working on Private DDN API development. Once the workspace has been provisioned, it can be launched from the Private DDN page.

Advantages

• Get started with just your browser. No need to install DDN CLI and its dependencies (e.g. Docker Engine) on your local machine.
• Network connectivity - Since the workspace runs on your data plane, it has direct access to all data sources and services within the data plane network. There is no need to set up complex VPN/network policies to access your DBs from your local machine.
• Collaboration - Multiple developers can work on the same project simultaneously within the same workspace, if needed.

Step 1. Launch a workspace

• To launch a workspace, click on the Launch Workspace button on the Private DDN. You can find a list of all available Private DDN instances here. This will open a new tab in your browser with the workspace UI.

• Click on the Copy Password button to copy the password to your clipboard. Use this password to login to the workspace.

Step 2. Authenticate the DDN CLI

Once logged in, you will be greeted with the familiar VS Code UI. You can perform all typical development tasks, such as installing extensions, customizing key bindings, and applying themes—all within your browser.

Bring up the terminal using the shortcut Ctrl + `.

Run the command below to authenticate the CLI with a service account token. If you don't have a token, follow these steps to generate one.

ddn auth login --access-token <service-account-token>

Step 3. Scaffold out a new local project

Next, create a new local project:

ddn supergraph init my-project && cd my-project

After navigating into the directory, you will see the project structure scaffolded for you. You can view the project structure by running ls in the terminal or by exploring it in the VS Code interface.

Step 4. Add a data source

The command below launches a wizard in the DDN CLI to guide you through adding a data connector. You can learn more about adding sources via data connectors here.

Add a data source using the CLI:

ddn connector init <connector_name> -i

This will provision the necessary files using your configuration for connecting a data source to your supergraph API.

Organize your data into subgraphs

You can also organize your API into subgraphs. Subgraphs are generally organized around team functions or business outcomes and allow for independent ownership and governance of data sources. Learn more here.

Step 5. Generate your metadata

First, introspect your data source:

ddn connector introspect <connector_name>

Then, generate the metadata:

ddn model add <connector_name> '*'
ddn command add <connector_name> '*'
ddn relationship add <connector_name> '*'

Metadata files will be generated for each entity in your data source. You can learn more here.

Note

ddn supergraph build local, ddn run docker-start and ddn console --local are not supported in DDN workspace. Once the metadata is generated, create a cloud project and deploy your supergraph to your Private DDN to query the API.

Step 6. Create a project on your Data Plane

Create a new project using the DDN CLI, specifying the data-plane-id and the plan as flags.

Get Data Plane ID

You can find all the Data Planes you have access to on this page: https://console.hasura.io/data-plane

Available Plans

• ddn_free
• ddn_base
• ddn_advanced

Read more about plans here

Create a new project using your Data Plane ID and plan choice:

ddn project init --data-plane-id <data-plane-id> --plan <plan-name>

The CLI will return information about your newly created project.

Step 7. Build and deploy your supergraph

build and deploy you supergraph:

ddn supergraph build create

When this process is complete, the CLI will return a link to the hosted API where you can query your data.

Step 8. Exporting your metadata

To export metadata, right-click the Explorer pane and select Download. This will download the entire workspace directory to your local machine. Since Git is pre-installed in the workspace, you can also configure it and push changes directly to a remote repository.

Logout

To log out of the workspace, click the Menu button in the top-left corner and select Sign out of code-server. This will close the workspace and you will be redirected to the workspace login page. The state of your local project will be preserved and you can login again to continue working on it.