Getting started with Radius: Run your first app

This guide will show you how to quickly get started with Radius. You’ll walk through both installing Radius and running your first Radius app.

Estimated time to complete: 10 min

1. Have your Kubernetes cluster handy

Radius runs inside Kubernetes. However you run Kubernetes, get a cluster ready.

If you don’t have a preferred way to create Kubernetes clusters, you could try using k3d, which runs a minimal Kubernetes distribution in Docker. Make sure to apply the recommended configuration.

Ensure your cluster is set as your current context:

kubectl config current-context

2. Install Radius CLI

The rad CLI manages your applications, resources, and environments. You can install it on your local machine with the following installation scripts:

• Linux/WSL
• MacOS
• Windows PowerShell
• GitHub Codespace
• Azure Cloud Shell
• Binaries

wget -q "https://raw.githubusercontent.com/radius-project/radius/main/deploy/install.sh" -O - | /bin/bash -s edge

curl -fsSL "https://raw.githubusercontent.com/radius-project/radius/main/deploy/install.sh" | /bin/bash -s edge

$script=iwr -useb "https://raw.githubusercontent.com/radius-project/radius/main/deploy/install.ps1"; $block=[ScriptBlock]::Create($script); invoke-command -ScriptBlock $block -ArgumentList edge

export RADIUS_INSTALL_DIR=./
wget -q "https://raw.githubusercontent.com/radius-project/radius/main/deploy/install.sh" -O - | /bin/bash

You may be prompted for your sudo password during installation, as the installer places the rad binary under /usr/local/bin. If you are unable to sudo you can install the rad CLI to another directory by setting the RADIUS_INSTALL_DIR environment variable with your intended install path. Make sure you add this to your path (Unix, Windows) if you wish to reference it via rad, like in the docs.

Verify the rad CLI is installed correctly by running rad version.

Example output:

RELEASE     VERSION     BICEP       COMMIT
0.26.0      edge        0.28.1     2e60bfb46de73ec5cc70485d53e67f8eaa914ba7

3. Initialize Radius

Create a new directory for your app and navigate into it:

mkdir first-app
cd first-app

Initialize Radius. For this example, accept all the default options (press ENTER to confirm):

rad init

Example output:

Initializing Radius...

✅ Install Radius edge
    - Kubernetes cluster: k3d-k3s-default
    - Kubernetes namespace: radius-system
✅ Create new environment default
    - Kubernetes namespace: default
    - Recipe pack: local-dev
✅ Scaffold application docs
✅ Update local configuration

Initialization complete! Have a RAD time 😎

In addition to starting Radius services in your Kubernetes cluster, this initialization command creates a default application (app.bicep) as your starting point. It contains a single container definition (demo). rad init also creates a bicepconfig.json file in your application’s directory that has the necessary setup to use Radius with the official Bicep compiler.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

// Import the set of Radius resources (Applications.*) into Bicep
extension radius

@description('The app ID of your Radius Application. Set automatically by the rad CLI.')
param application string

resource demo 'Applications.Core/containers@2023-10-01-preview' = {
  name: 'demo'
  properties: {
    application: application
    container: {
      image: 'ghcr.io/radius-project/samples/demo:latest'
      ports: {
        web: {
          containerPort: 3000
        }
      }
    }
  }
}

This file will run the ghcr.io/radius-project/samples/demo:latest image. This image is published by the Radius team to a public registry, you do not need to create it.

4. Run the app

Use the below command to run the app in your environment, then access the application by opening http://localhost:3000 in a browser.

rad run app.bicep

This command:

• Runs the application in your Kubernetes cluster
• Creates a port-forward from localhost to port 3000 inside the container so you can navigate to the app’s frontend UI
• Creates a port-forward from localhost to port 7007 inside the container so you can navigate to your Radius Dashboard
• Streams container logs to your terminal

Access your Radius Dashboard by opening http://localhost:7007 in a browser. In your browser, you should see the Radius Dashboard, which includes visualizations of the application graph, environments, and recipes:

Congrats! You’re running your first Radius app.
When you’re ready to move on to the next step, use CTRL+ C to exit the command.

5. Add Database

This step will add a database (Redis Cache) to the application.

You can create a Redis Cache using Recipes provided by Radius. The Radius community provides Recipes for running commonly used application dependencies, including Redis.

In this step you will:

• Add Redis to the application using a Recipe.
• Connect to Redis from the demo container using environment variables that Radius automatically sets.

Open app.bicep in your editor and get ready to edit the file.

First add some new code to app.bicep by pasting in the content below at the end of the file. This code creates a Redis Cache using a Radius Recipe:

21
22
23
24
25
26
27
28
29
30

@description('The environment ID of your Radius Application. Set automatically by the rad CLI.')
param environment string

resource db 'Applications.Datastores/redisCaches@2023-10-01-preview' = {
  name: 'db'
  properties: {
    application: application
    environment: environment
  }
}

Next, update your container definition to include connections inside properties. This code creates a connection between the container and the database. Based on this connection, Radius will inject environment variables into the container that inform the container how to connect. You will view these in the next step.

 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

resource demo 'Applications.Core/containers@2023-10-01-preview' = {
  name: 'demo'
  properties: {
    application: application
    container: {
      image: 'ghcr.io/radius-project/samples/demo:latest'
      ports: {
        web: {
          containerPort: 3000
        }
      }
    }
    connections: {
      redis: {
        source: db.id
      }
    }
  }
}

Your updated app.bicep will look like this:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34

// Import the set of Radius resources (Applications.*) into Bicep
extension radius

@description('The app ID of your Radius Application. Set automatically by the rad CLI.')
param application string

resource demo 'Applications.Core/containers@2023-10-01-preview' = {
  name: 'demo'
  properties: {
    application: application
    container: {
      image: 'ghcr.io/radius-project/samples/demo:latest'
      ports: {
        web: {
          containerPort: 3000
        }
      }
    }
    connections: {
      redis: {
        source: db.id
      }
    }
  }
}

param environment string
resource db 'Applications.Datastores/redisCaches@2023-10-01-preview' = {
  name: 'db'
  properties: {
    application: application
    environment: environment
  }
}

6. Rerun the application with a database

Use the command below to run the updated application again, then open the browser to http://localhost:3000.

rad run app.bicep

You should see the Radius Connections section with new environment variables added. The demo container now has connection information for Redis (CONNECTION_REDIS_HOST, CONNECTION_REDIS_PORT, etc.):

Navigate to the Todo List tab and test out the application. Using the Todo page will update the saved state in Redis:

Access your Radius Dashboard again by opening http://localhost:7007 in a browser. You should see a visualization of the application graph for your demo app, including the connection to the db Redis Cache:

Press CTRL+ C when you are finished with the websites.

7. View the application graph

Radius Connections are more than just environment variables and configuration. You can also access the “application graph” and understand the connections within your application with the following command:

rad app graph

You should see the following output, detailing the connections between the demo container and the db Redis Cache, along with information about the underlying Kubernetes resources running the app:

Displaying application: demo

Name: demo (Applications.Core/containers)
Connections:
  demo -> db (Applications.Datastores/redisCaches)
Resources:
  demo (kubernetes: apps/Deployment)
  demo (kubernetes: core/Secret)
  demo (kubernetes: core/Service)
  demo (kubernetes: core/ServiceAccount)
  demo (kubernetes: rbac.authorization.k8s.io/Role)
  demo (kubernetes: rbac.authorization.k8s.io/RoleBinding)

Name: db (Applications.Datastores/redisCaches)
Connections:
  demo (Applications.Core/containers) -> db
Resources:
  redis-r5tcrra3d7uh6 (kubernetes: apps/Deployment)
  redis-r5tcrra3d7uh6 (kubernetes: core/Service)

8. Cleanup

To delete your app, run the rad app delete command to cleanup the app and its resources, including the Recipe resources:

rad app delete first-app -y

Next steps

Now that you’ve run your first Radius app, you can learn more about Radius by reading the following guides:

• Tutorials - Learn how to build and deploy a variety of applications with Radius