Local development with Catalyst

Developing and running applications using the Catalyst APIs 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

Prerequisites

In order to test the Catalyst APIs you need minimally one, and potentially two, App IDs. For example, if you are end-to-end testing the Publish/Subscribe or Service Invocation APIs you need two App IDs, one to represent the calling app (client/publisher) and one to represent the receiving app (server/subscriber).

If you are testing the State, Workflow or Binding APIs, you likely only need one App ID.

App IDs can be created using the diagrid appid create CLI command or using the Catalyst console.

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 endpoint 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 provide your application with the API token of its associated App ID. 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 start command performs the following:

• Run the local application in the current directory with the provided arguments.
• Inject environment variables from the provided App ID to inform the Dapr SDKs how to connect to Catalyst.
• Stream application logs directly to the terminal.
• Create a local application connection to receive outgoing requests from Catalyst to your app. If an application port is defined, the Diagrid CLI establishes a 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.

Tip

You can find these instructions in each App ID in the App Connection section

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 start --app-id <your-appid> <app-startup-command>

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

diagrid dev start --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 start 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 start --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 start --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 start 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 start --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 start --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 scaffolding a project development configuration file with one or more application definitions. This is useful in scenarios where you want to run multiple applications at the same time, in a repeatable way.

Generate a dev config file

The easiest way to get started with a dev config file is to generate one using the Diagrid CLI as follows.

Prerequisites

Ensure you are logged in and have created any necessary App IDs in Catalyst.

diagrid dev scaffold

This command produces the file dev-<project-name>.yaml containing the app connection details for all the App IDs in the current Catalyst project. The dev config file has the following format:

project: <project-name>  # Project that this file was generated from and connects to
apps:   # List of App IDs in a project to run locally and/or create an app connection for
- appId: <appid>  # App ID name
  appPort: 0  # Optional: Port used by Catalyst to establish a local app connection to your code
  env:  # App environment variables necessary for connecting to the Catalyst APIs
    DAPR_API_TOKEN: <appid-api-token>
    DAPR_APP_ID: <appid>
    DAPR_GRPC_ENDPOINT: <your-project-grpc-url>
    DAPR_HTTP_ENDPOINT: <your-project-http-url>
  workDir: <>  # Work directory to run the start-up command in
  command: []  # Start-up command to run the application

The file is generated only based on the App IDs in Catalyst, and doesn't contain any local app information. 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.

At a minimum, every App ID section in a dev config file, must have either a command, or an appPort value set to establish an application connection.

All subsequent runs of diagrid dev scaffold will update any existing dev config files with remote App ID values, but preserve the locally updated fields.

Run multiple apps with a dev config file

After filling in the local application details, the dev config file can run all applications at once with the following command:

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

For each App ID section in the dev config file, the diagrid dev start command performs the following:

• Runs the local application in the current directory with the provided arguments.
• Injects environment variables from the provided App ID to inform the Dapr SDKs how to connect to Catalyst.
• Streams application logs directly to the terminal.
• Creates a local application connection for forwarding outgoing requests from your Catalyst App ID to your app. If an application port is defined, the Diagrid CLI establishes a 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.

info

If command is defined it will run the application, and if appPort is set, it will also establish a local application connection from the Catalyst APIs.

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

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

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

Run an app using containers and the Diagrid Dev CLI

The Diagrid CLI is available via container image. This will allow containerized applications to interact with Catalyst.

Take this example Dockerfile:

FROM public.ecr.aws/diagrid/cli:latest

# Copy in your compiled app binary e.g. myapp
ARG PKG_FILES
WORKDIR /
COPY /$PKG_FILES /

ENTRYPOINT [ "diagrid", "dev", "start" ]

Build the container image:

docker build -t myapp .

Run the container:

docker run -it myapp --api-key $DIAGRID_API_KEY --project $PROJECT_NAME -a $APPID_NAME -p $APP_PORT -- ./myapp