Local development with Catalyst

Developing and running Dapr applications using Catalyst requires minimal code changes. The Diagrid CLI provides tooling that enables a quick onboarding and inner-loop development experience.

This document details how to connect to Catalyst from local applications:

• Develop with the Dapr SDKs
• Run an app using the Diagrid CLI
• Run multiple apps with the Diagrid CLI

Develop with the Dapr SDKs

The recommended approach for developing applications which interact with the Catalyst APIs is to use the existing Dapr SDKs. Based on your programming language of choice, you will import the respective Dapr SDK into your application and configure the Dapr Client.

By default, the Dapr Client will attempt to connect and send Dapr API requests to a Dapr process running on http://localhost. To connect the Dapr Client to the remote Catalyst APIs, you will need override the default Dapr host endpoint with a value corresponding to the HTTP or gRPC Catalyst project endpoint:

export DAPR_GRPC_ENDPOINT=<your-project-grpc-url>
export DAPR_HTTP_ENDPOINT=<your-project-http-url>

Important: All Dapr SDKs use the gRPC protocol by default, except for JavaScript, which uses HTTP.

All App IDs in a project will use the same endpoints to establish connectivity from the Dapr Client to Catalyst. You can retrieve the project endpoints from the diagrid project list command or using the Connect to Project button at the top of the Catalyst console.

In addition to configuring the Dapr host endpoint, you will also need to configure each Dapr application with the API token from its corresponding Catalyst App ID (remote Dapr sidecar). This API Token will be sent to the Catalyst APIs as the dapr-api-token request header for Catalyst API authentication and App ID request routing. Each App ID has a unique API token which can be regenerated as needed.

Run the diagrid appid get command to retrieve the API token value for an App ID. Alternatively, you can retrieve the API token in Catalyst Console from the App ID details page. Once retrieved, set the API token environment variable as follows:

export DAPR_API_TOKEN=<your-appid-api-token>

Once set, the Dapr SDKs are configured to retrieve these environment variables automatically without the need to pass them explicitly to the Dapr client constructor. After configuring the Dapr Client using the above env variables, you can proceed to develop against the Catalyst APIs without any local Dapr dependencies.

For SDK download instructions and Dapr Client configuration examples, visit Connect Dapr SDKs to Catalyst APIs.

Run an app using the Diagrid Dev CLI

In a single Diagrid CLI command you can set up the the necessary environment variables described in the previous section and start a local application that both makes and receives calls from the Catalyst APIs.

The diagrid dev run command:

• Runs the local application in the current directory with the provided arguments.

• Streams application logs directly to the terminal.

• Injects environment variables from the provided App ID to inform the Dapr SDKs how to connect to Catalyst.

• Creates a local application connection to receive outgoing requests from Catalyst to your app. If an application port is defined, the Diagrid CLI establishes a private network tunnel from Catalyst to your local machine. This overrides the App ID's application endpoint value so that all traffic from Catalyst is routed to your local app.

note

Unlike the multi-app run file experience, this command does not create the App ID dynamically, therefore it must already exist in the specified project to connect your application

Run an app that makes Catalyst API requests

For an application that only makes requests to the Catalyst APIs, you can fetch and set all the required environment variables and run your application as follows:

Prerequisites

Ensure you are logged in and have created the associated App ID in Catalyst.

diagrid dev run --app-id <your-appid> <app-startup-command>

For example, to run a Java application that connects to an App ID called publisher:

diagrid dev run --app-id publisher "java -jar target/Main-0.0.1-SNAPSHOT.jar"

Run an application that receives outgoing requests from Catalyst

Applications that are subscribed to a topic, have input binding triggers, or are invoked by other Catalyst services receive outgoing request from their Catalyst App IDs.

When you run these apps locally, the Diagrid CLI can connect to your local machine to route all traffic to the local instance of your app. This is enabled by passing in the port number to the diagrid dev run command that your local application is listening on.

tip

Ensure you are logged in and have created the associated App ID in Catalyst.

diagrid dev run --app-id <your-appid> --app-port <local-port-number> <app-startup-command>

For example, to run a Java application that connects to the subscriber App ID, listening on port 9001:

diagrid dev run --app-id subscriber --app-port 9001  "java -jar target/Main-0.0.1-SNAPSHOT.jar --port=9001"

Manage local app connections

Sometimes you might want to start or stop your application outside of the Diagrid CLI, for example when debugging. In these scenarios, diagrid dev run can be used without an application startup command as a local application connection that will route all calls from the Catalyst APIs to a local port.

diagrid dev run --app-id <your-appid> --app-port <local-port-number>

For example, to route all Catalyst API traffic for the subscriber App ID to http://localhost:9001, run the following:

diagrid dev run --app-id subscriber --app-port 9001

In this case, the subscriber App ID's application endpoint value is modified to point to your local CLI instance while the local network tunnel is running. Reset the application endpoint for your App ID by stopping the local app connection.

diagrid dev stop -a <your-appid>

Check for local app connections using the diagrid dev status command.

diagrid dev status

For additional options using the diagrid dev CLI commands, see diagrid dev.

Run multiple apps with the Diagrid CLI

The Diagrid CLI supports connecting local applications to Catalyst using a Dapr multi-app run file.

Generate a multi-app run file from an existing Catalyst project

If you have already created a Catalyst project and deployed resources, you can scaffold a multi-app run file which can be used to connect from your local machine.

diagrid dev scaffold

This command produces a dapr multi-app run file with the name dev-<project-name>.yaml, along with any components or subscriptions found in your current project.

version: 1
common:
  logLevel: debug
  appLogDestination: "console"
  resourcesPaths: ["./resources"] # Directory hosting components, subscriptions, etc.
apps: # Outputs all App IDs in the current project 
  - appID: <app-id name> 
    appPort: 0 # Port your local app is running on - used to establish dev tunnel
    appDirPath: # Local application directory 
    env:  # Environment variables for local application
      DAPR_API_TOKEN: <appid-api-token>
      DAPR_APP_ID: <appid>
      DAPR_GRPC_ENDPOINT: <your-project-grpc-url>
      DAPR_HTTP_ENDPOINT: <your-project-http-url>
    command: [] # Start-up command to run local application

You are expected to populate the following values to make this work locally:

• Update workDir with the directory where the application binaries are located.
• Provide the command to start the application.
• If the application is receiving incoming Catalyst traffic and listening on a local port, specify appPort so that a local application connection is established.
• Remove any appId sections that are not relevant locally.

Develop using multi-app run file

To develop using a dapr multi-app run file in Catalyst, use the diagrid dev run -f . command, where the value following -f points to the location of your multi-app run file.

Run diagrid dev run in the root of your code directory to:

• Connect to a Catalyst project: If the project does not exist, the command will create a new project
• Create resources: Create necessary resources on Catalyst such as App IDs, Components, and Diagrid Pub/Sub or KV Store managed services
• Launch local applications: Get your apps up and running based on the specifed configuration values
• Inject environment variables: Configure your application's to connect to Catalyst via the Dapr SDKs
• Create local application connections to receive outgoing requests from Catalyst to your applications. If an application port is defined, the Diagrid CLI establishes a private network tunnel from Catalyst to your local machine. This overrides the App ID's application endpoint value so that all traffic from Catalyst is routed to your local app.

To stop all locally running applications and any local application connections, run the following:

diagrid dev stop -f <project-name>.yaml

For additional options using the diagrid dev CLI commands, see diagrid dev.