# Getting started with Dashboard-as-Code

!!! info
	See the introduction about the Dashboard-as-Code (DaC) topic [here](../concepts/dashboard-as-code.md).

## Getting started with the CUE SDK

### Prerequisites

- `percli`, the [CLI of Perses](../cli.md). ⚠️ The version should be at least `v0.54.0`.
- `cue`, the [CLI of Cuelang](https://cuelang.org/). ⚠️ The version should be at least `v0.15.0`.

### Repository setup

Create a new folder that will become your DaC repository, then follow the steps below:

#### 1. Initialize the CUE module

You first have to initialize a CUE module in order to be able to import the SDK dependency afterwards:

```bash
cue mod init <module name>
```

See the [CUE documentation](https://cuelang.org/docs/concept/modules-packages-instances/) for more information about this step.

#### 2. Install the Perses SDK

Now you can run the setup command that percli provides in order to install the SDK:

```bash
percli dac setup
```

Check the helper of that command to see the different flags available (e.g to define the SDK version to install).

### Develop dashboards

You are now fully ready to start developing dashboards as code with CUE!

You should first ramp up on [CUE](https://cuelang.org/) if you are not familiar with this technology.

Then you should have a look at the [CUE SDK documentation](../dac/cue/README.md) to better understand how to use it.

For each [plugin](../concepts/plugin.md) you would like to use in your DaC, it is strongly recommended to import its module so that you benefit from its schema validation locally. Optionally the plugin could also provide additional helpers (kind-of SDK additional piece) to help using it. Check the list of available plugins & their corresponding module name at https://github.com/perses/plugins.

!!! note
	To resolve the dependencies added after the initial setup, use `cue mod tidy`.

You can have a look at the minimal example file has been generated by the `setup` command. For a richer DaC example, see below:

```cue
package mydac

import (
	dashboardBuilder "github.com/perses/perses/cue/dac-utils/dashboard"
	panelGroupsBuilder "github.com/perses/perses/cue/dac-utils/panelgroups"
	varGroupBuilder "github.com/perses/perses/cue/dac-utils/variable/group"
	labelValuesVarBuilder "github.com/perses/plugins/prometheus/sdk/cue/variable/labelvalues"
	panelBuilder "github.com/perses/plugins/prometheus/sdk/cue/panel"
	timeseriesChart "github.com/perses/plugins/timeserieschart/schemas:model"
	promQuery "github.com/perses/plugins/prometheus/schemas/prometheus-time-series-query:model"
	promDs "github.com/perses/plugins/prometheus/schemas/datasource:model"
)

dashboardBuilder & {
	#name:    "ContainersMonitoring"
	#project: "MyProject"

	#variables: {varGroupBuilder & {
		#input: [
			labelValuesVarBuilder & {
				#name: "stack"
				#display: name: "My Super PaaS"
				#metric:         "thanos_build_info"
				#label:          "paas"
				#datasourceName: "promDemo"
			},
		]
	}}.variables

	#panelGroups: panelGroupsBuilder & {
		#input: [
			{
				#title: "Resource usage"
				#cols:  3
				#panels: [
					panelBuilder & {
						spec: {
							display: name: "Container memory"
							plugin: timeseriesChart
							queries: [
								{
									kind: "TimeSeriesQuery"
									spec: plugin: promQuery & {
										spec: query: "max by (container) (container_memory_rss{paas=\"$paas\",namespace=\"$namespace\",pod=\"$pod\",container=\"$container\"})"
									}
								},
							]
						}
					},
				]
			},
		]
	}

	#datasources: promDemo: {
		default: true
		plugin: promDs & {
			spec: close({directUrl: "https://demo.prometheus.com"})
		}
	}
}
```

## Getting started with the Go SDK

### Prerequisites

- `percli`, the [CLI of Perses](../cli.md). ⚠️ The version should be at least `v0.54.0`.
- `go`, the [programming language](https://go.dev/).

### Repository setup

Create a new folder that will become your DaC repository, then follow the steps below:

#### 1. Initialize the Go module

You first have to initialize a Go module in order to be able to import the SDK dependency afterwards:

```bash
go mod init <module name>
```

See the [Go documentation](https://go.dev/doc/tutorial/create-module) for more information about this step.

#### 2. Install the Perses SDK


Now you can run the setup command that percli provides in order to install the SDK:

```bash
percli dac setup --language go
```

Check the helper of that command to see the different flags available (e.g to define the SDK version to install).

### Develop dashboards

You are now fully ready to start developing dashboards as code with Go!

You should first ramp up on [Go](https://go.dev/) if you are not familiar with this technology.

Then you should have a look at the [Go SDK documentation](../dac/go/README.md) to better understand how to use the framework.

!!! warning
	Do not log / print on the standard stdout! It would break the output of the `dac build` command.

For each [plugin](../concepts/plugin.md) you would like to use in your DaC, you first have to check if it provides the corresponding piece of the Golang SDK* (it's always the case for official plugins). You will then have to import the corresponding dependency in order to be able to use it. Check the list of official plugins & their corresponding module name at https://github.com/perses/plugins.

!!! warning
	*As already mentioned in the [DaC introduction](../concepts/dashboard-as-code.md), outside official plugins, it is not guaranteed that all plugins would provide such piece of the Golang SDK. It's basically up to each plugin developer to provide a Go package to enable the DaC use case. This statement applies also to any other language we might have a SDK for in the future.

!!! note
	To resolve the dependencies added after the initial setup, use either `go mod tidy` or `go get ...`.

!!! note
	On top of the Perses GO SDK, there is an SDK dedicated to build PromQL queries https://github.com/perses/promql-builder

You can have a look at the minimal example file has been generated by the `setup` command. For a richer DaC example, see below:

```golang
package main

import (
	"flag"

	"github.com/perses/perses/go-sdk"
	"github.com/perses/perses/go-sdk/dashboard"
	"github.com/perses/perses/go-sdk/panel"
	panelgroup "github.com/perses/perses/go-sdk/panel-group"
	listVar "github.com/perses/perses/go-sdk/variable/list-variable"
	promDs "github.com/perses/plugins/prometheus/sdk/go/datasource"
	"github.com/perses/plugins/prometheus/sdk/go/query"
	labelValuesVar "github.com/perses/plugins/prometheus/sdk/go/variable/label-values"
	timeSeriesPanel "github.com/perses/plugins/timeserieschart/sdk/go"
)

func main() {
	flag.Parse()
	exec := sdk.NewExec()
	builder, buildErr := dashboard.New("ContainersMonitoring",
		dashboard.ProjectName("MyProject"),

		dashboard.AddVariable("stack",
			listVar.List(
				labelValuesVar.PrometheusLabelValues("paas",
					labelValuesVar.Matchers("thanos_build_info{}"),
					labelValuesVar.Datasource("promDemo"),
				),
				listVar.DisplayName("My Super PaaS"),
			),
		),

		dashboard.AddPanelGroup("Resource usage",
			panelgroup.PanelsPerLine(3),
			panelgroup.AddPanel("Container memory",
				timeSeriesPanel.Chart(),
				panel.AddQuery(
					query.PromQL("max by (container) (container_memory_rss{paas=\"$paas\",namespace=\"$namespace\",pod=\"$pod\",container=\"$container\"})"),
				),
			),
		),

		dashboard.AddDatasource("promDemo", promDs.Prometheus(promDs.HTTPProxy("https://demo.prometheus.com"))),
	)
	exec.BuildDashboard(builder, buildErr)
}
```

## Build dashboards

Anytime you want to build the final dashboard definition (i.e: Perses dashboard in JSON or YAML format) corresponding to your as-code definition, you can use the `dac build` command, as the following:

```
percli dac build -f main.go -ojson
percli dac build -f my_dashboard.cue -ojson
```

If the build is successful, the result can be found in the generated `built` folder.

!!! note
	the `-o` (alternatively '--output') flag is optional (the default output format is YAML).

### Build multiple dashboards at once

If you want to develop multiple dashboards as code, you should have **1 dashboard per file** and then call the build command with the directory option:

```
percli dac build -d my_dashboards
```

## Development workflow with auto-reload

For an improved development experience, instead of building the files each time manually with `dac build`, you can use the `dac watch` command that automatically rebuilds your dashboards whenever you save changes to your DaC files. This provides a workflow similar to frontend hot-reload development.

### Basic watch mode

Start watching your DaC files for changes:

```bash
# Watch current directory
percli dac watch

# Watch specific directory
percli dac watch ./my-dashboards

# Watch and output as JSON
percli dac watch ./my-dashboards -ojson
```

The watcher will:
- Perform an initial build of all dashboards
- Monitor all `.go` and `.cue` files in the source directory
- Automatically rebuild when files are modified
- Output results to the `built` folder (or custom location via `--dac.output_folder`)

### Integrated development workflow

To get a direct visual feedback of your changes when coding dashboards, you can run Perses with provisioning configured to watch your build directory:

**Step 1: Create a Perses config file** (`perses-dev.yaml`):

```yaml
database:
  file:
    folder: /tmp/perses-dac-dev
    extension: yaml

provisioning:
  interval: 5s  # Check for changes every 5 seconds
  folders:
    - /absolute/path/to/your/built  # Your build output folder

security:
  enable_auth: false  # Disable auth for local development
```

**Step 2: Start both processes**:

```bash
# Terminal 1: Start Perses server with provisioning
perses --config perses-dev.yaml

# Terminal 2: At the root of your DaC repo, start the DaC watcher
percli dac watch
```

**Step 3: Develop with instant feedback**:

1. Open `http://localhost:8080` in your browser
2. Navigate to your dashboards
3. Edit your DaC files (`.go` or `.cue`)
4. Watch the terminal show automatic rebuild
5. Refresh your browser to see changes (provisioning picks them up within 5 seconds)

!!! tip
    The provisioning interval of `5s` provides a good balance between responsiveness and system load. You can adjust it based on your needs.

!!! tip
    The watch command uses a 500ms debounce delay by default to avoid excessive rebuilds while you're actively editing. You can customize this with the `--debounce` flag.

## Deploy dashboards

Once you are satisfied with the result of your DaC definition for a given dashboard, you can finally deploy it to Perses with the `apply` command:

```
percli apply -f built/my_dashboard.json
```

### CI/CD setup

Setting up a CI/CD pipeline for your Dashboard-as-Code workflow is straightforward, as [percli](../cli.md) provides all the necessary commands to automate the process. You can integrate percli with any CI/CD technology of your choice: Jenkins, CircleCI, GitLab CI/CD, etc.

The key steps typically involve:

- Building the dashboards using `percli dac build` to generate the final JSON/YAML definitions.
- Validating the output to ensure correctness before deployment.
- Deploying the dashboards to Perses with `percli apply`.

If you are using GitHub Actions, we provide a [standard library](https://github.com/perses/cli-actions) that simplifies this integration. This includes:

- A pre-configured workflow designed for common DaC CI/CD setups, making it easy to adopt without extensive configuration. 

	Example of usage:
	```yaml
	jobs:
	  dac:
	   uses: perses/cli-actions/.github/workflows/dac.yaml@v0.1.0
	   with:
	     url: https://demo.perses.dev
	     directory: ./dac
	     server-validation: true
	   secrets:
	     username: ${{ secrets.USR }}
	     password: ${{ secrets.PWD }}
	```

- Independent actions for each CLI command, allowing you to build customized workflows.

	Example of usage:
	```yaml
	steps:
	  - name: Deploy the dashboards
	    uses: perses/cli-actions/actions/apply_resources@v0.1.0
	    with:
	      directory: ./testdata/dashboards_folder
	```

	The full list of actions is available [here](https://github.com/perses/cli-actions/blob/main/README.md#actions).

By leveraging these tools, you can ensure that your dashboards are automatically validated and deployed in a consistent and reliable manner.