Creating a Hello World! app

This tutorial will walk you through the process of creating your first Private App on your local machine.

The steps we’ll follow are:

1. Setting up your environment
2. Create a new app using the CLI
3. Testing your new app
4. Connecting your app to your Tempest organization

1: Setting up your environment

Requirements

• Go 1.23+

In order to install the tempest CLI on your system, run:

go install github.com/tempestdx/cli/tempest@latest

---

2: Create a new app and your first resource

In your terminal, you can quickly scaffold the file structure for your app by running tempest app init in your desired working directory.

mkdir tempest & cd tempest
tempest app init helloworld

This will create the following folder structure:

├── apps
│   └── hello-world
│       └── v1
│           └── helloworld.go
├── go.mod
├── go.sum
└── tempest.yaml

This scaffolds the entire structure for your helloworld app, and creates the first resource in v1/helloworld.go. This is folder structure is conventional and allows enables Tempest CLI to easily manage all your apps, resources, and future versions.

Let’s see what capabilities our new app supports out of the box.

tempest app describe helloworld:v1
# Tempest App Description
# -----------------------

# Describing app: helloworld
# Location: /Users/kenneth/tempest/apps/helloworld/v1

# Resource Type: Example Resource

# Links:

# Operations Supported:
# - ❌ Read
# - ❌ List
# - ✅ Create
# - ❌ Update
# - ❌ Delete

# Health Check Supported: ❌

We can see that the CLI scaffolded a basic app with only the Create operation implemented. Let’s go ahead and customize your app with a custom schema for your app’s Create operation, as well as adding a health check.

In your apps/helloworld/v1/app.go , we’ll make the following changes to modify the arguments for Create and add a HealthCheck.

// We load the file using Go embed
// but you can just as easily use os.ReadFile
//go:embed create.json
var createInputSchema []byte

func App() *app.App {
	resourceDefinition.CreateFn(
		createFn,
		app.MustParseJSONSchema(createInputSchema),
	)

	resourceDefinition.HealthCheckFn(func(_ context.Context) (*app.HealthCheckResponse, error) {
		// This is a simple health check that always returns healthy
		// You can implement your own health check logic here
		return &app.HealthCheckResponse{
			Status: app.HealthCheckStatusHealthy,
		}, nil
	})

	return app.New(
		app.WithResourceDefinition(resourceDefinition),
	)
}

Now we can create a new file in the same directory as app.go called create.json. In this file, paste the following schema in:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://schema.tempestdx.io/sdk/helloworld_create.json",
  "$comment": "This is a generic empty schema that can be used as a placeholder for schemas that do not have any properties.",
  "type": "object",
  "properties": {
    "name": {
      "title": "Name",
      "type": "string",
      "description": "Example name."
    }
  },
  "required": ["name"],
  "additionalProperties": false
}

To recap, we just created a new app and resource. Then we added the following capabilities in a few lines of code:

• We created a custom schema for Create to change the API contract for this resource, as setting this field as configurable by other users in your Tempest organization
• We added a simple HealthCheck so that Tempest can regularly call our app to check it’s health

Private Apps are easy to get started with, but can be deeply customized beyond this simple example. Learn more by reading our SDK reference.

Next, lets test our app locally.

---

3: Testing your Private App implementation locally

You can test the operations implemented by your Private App by running them locally. To do so, you can run tempest app test from the directory your tempest.yaml is located in. This will test your app, and all the resources you’ve defined for it. In this simple app, it’ll test the helloworld resource defined in app.go.

tempest app test helloworld:v1 --operation create --type example --input '{"name": "hello"}'

The CLI allows you to granularly test your apps. To understand what options are available, you can use the tempest app test --help or visit the CLI reference documentation.

Now that we’ve tested our Private App locally, we’ll create it in the Tempest web console and connect your instrumentation to your Tempest web console.

---

4: Create your Private App in the Tempest web console

Connecting your local app to Tempest to enable it to be managed in recipes and deployed in projects. To start this process, login to your Tempest web console. From here, follow these steps to create your Private App:

1. From the navigation of the left of your app, click Apps
2. From upper-right corner of your Apps page, click Create New App

Next, we’ll ask you for some information that’ll be used to display your app in your Tempest organization:

After creating your app, you’ll be redirected to your new app’s homepage. New apps need to be connected to a local or deployed implementation of a Private App before they’re usable in Tempest by your users.

If this is your first time connecting a Private App, follow the instructions to create an API key. Since we started development locally, we can go ahead and create our first version! Select Create New Version from your app’s homepage.

Creating a new version will redirect you to the homepage for that app version. From here, you can view logs and health checks to verify that Tempest is communicating correctly with your app.

Great, now that we have our new app and version created in Tempest, we can connect our local implementation to Tempest.

5. Connecting your local app to your Tempest organization

In the previous step, we created our app in Tempest and also created our API key. To connect our local app to our Tempest organization, we’ll return to our terminal:

First, let’s login using our API token.

tempest auth login
Input your API Key:

You’ll be given a prompt to input your API token, or you can explicitly pass in a key with the tempest auth login --with-key.

Next, let’s connect your local app to your Tempest organization:

tempest app connect helloworld:v1
tempest app serve

And now that we’ve connected the app to Tempest, we can run the serve the app locally. This will start communication with Tempest. On the homepage for the v1 version of your app, you’ll be able to see the health check we implemented earlier.