Building

Build and run Grafana for local development

Grafana consists of two components that can be built independently: the frontend (TypeScript/React) and the backend (Go).

Quick Start

The fastest way to get started:

Backend with hot-reload

make run

Then visit http://localhost:3000 (login: admin / admin).

Building the Backend

The backend is a Go web server that serves the API and frontend assets.

Development Build with Hot-Reload

1. Start the backend with hot-reload

   make run
   

   This:

   • Builds the Go binary
   • Starts the server on localhost:3000
   • Watches for changes and automatically rebuilds
   • Uses Air for hot-reload (configured in .air.toml)

   First build takes ~3 minutes due to debug symbols. Subsequent hot-reload rebuilds are much faster.

2. Log in to Grafana

   Visit http://localhost:3000 and log in:

   Username	Password
   admin	admin

   Grafana will prompt you to change the password on first login.

Production Build

Build the backend without hot-reload:

make build-backend

The binary is created at bin/grafana.

Build Without Make

If you prefer not to use Make:

go run -race ./pkg/cmd/grafana -- server -profile -profile-addr=127.0.0.1 -profile-port=6000 -packaging=dev cfg:app_mode=development

CGO and Static Builds

Development (Default)

make run and make build-go detect GCC and enable CGO automatically if available.

• With CGO: Uses SQLite for the embedded database
• Without CGO: No SQLite support

Production

Production builds use CGO_ENABLED=0 for fully static binaries:

CGO_ENABLED=0 make build-go

This is important when build and runtime environments differ (e.g., building on Debian, running on Alpine).

Windows-Specific Build Instructions

1. Install Wire tool

   Follow the Wire installation instructions.

2. Generate Wire code

   $GOPATH/bin/wire.exe gen -tags oss ./pkg/server ./pkg/cmd/grafana-cli/runner
   
3. Build binaries

   make build
   

   Binaries will be in bin\windows-amd64.

On Windows, you can use Make for Windows in a UNIX shell like Git Bash.

Building the Frontend

The frontend is built with webpack and served by the backend in development.

Development Build with Watch

1. Install dependencies (if not already done)

   yarn install --immutable
   
2. Start the webpack dev server

   yarn start
   

   This:

   • Generates SASS theme files
   • Builds all external plugins
   • Compiles frontend assets
   • Watches for changes and rebuilds automatically
   • Serves via webpack dev server (proxied by backend)

   First compile takes ~45 seconds. Subsequent rebuilds are incremental and faster.

Production Build

Build optimized frontend assets:

yarn build

Assets are output to public/build/.

Build Variations

Development (no minification)

yarn dev

Troubleshooting Frontend Builds

Type-checking errors after git pull

The incremental TypeScript build cache may be stale:

rm tsconfig.tsbuildinfo
yarn start

Checksum mismatch on yarn install

Temporary mismatch for a dependency:

YARN_CHECKSUM_BEHAVIOR=update yarn install --immutable

Building Plugins

Some built-in plugins require separate builds:

Build All Plugins

yarn plugin:build:dev

This is resource-intensive as it starts separate build processes for each plugin.

Build Specific Plugins

Build a single plugin:

yarn workspace @grafana-plugins/tempo dev

Build multiple specific plugins:

yarn nx run-many -t dev --projects="@grafana-plugins/grafana-azure-monitor-datasource,@grafana-plugins/jaeger"

List All Plugins

yarn nx show projects --projects="@grafana-plugins/*"

Plugins Requiring Separate Builds

• azuremonitor
• cloud-monitoring
• grafana-postgresql-datasource
• grafana-pyroscope-datasource
• grafana-testdata-datasource
• jaeger
• loki
• mysql
• parca
• tempo
• zipkin

Building Both Frontend and Backend

Build everything in one command:

make build

This runs:

1. make build-go - Builds backend
2. yarn build - Builds frontend

Code Generation

Some changes require regenerating code:

Wire Dependency Injection

After modifying service initialization:

make gen-go

CUE Schemas

After modifying dashboard/panel schemas in kinds/:

make gen-cue

Feature Toggles

After adding/modifying feature flags in pkg/services/featuremgmt/:

make gen-feature-toggles

App SDK Apps

After modifying apps in apps/:

make gen-apps

Or for a specific app:

make gen-apps app=dashboard

Go Workspace

After adding Go modules:

make update-workspace

OpenAPI/Swagger Specs

After API changes:

make swagger-gen

i18n String Extraction

After adding translatable strings:

make i18n-extract

Building for Docker

Build a development Docker image:

make build-docker-full

The image is tagged as grafana/grafana:dev.

On Docker for macOS, increase memory limit to >2 GiB in Docker Desktop → Preferences → Advanced.

Build Ubuntu-based image:

make build-docker-full-ubuntu

Linting and Formatting

Before committing, ensure your code passes linting:

Backend

make lint-go              # Run golangci-lint
make gofmt                # Format Go code

Frontend

yarn lint                 # ESLint
yarn lint:fix             # ESLint with auto-fix
yarn prettier:write       # Format with Prettier
yarn typecheck            # TypeScript type checking

Build Configuration

Environment Variables

Variable	Purpose
CGO_ENABLED	Enable/disable CGO (0 or 1)
GO_BUILD_TAGS	Go build tags (e.g., oss, enterprise)
NODE_ENV	Node environment (dev or production)
GO_RACE	Enable Go race detector

Makefile Targets

View all available targets:

make help

Common targets:

• make run - Run backend with hot-reload
• make build - Build frontend and backend
• make build-backend - Build backend only
• make test-go - Run backend tests
• make test-js - Run frontend tests
• make devenv - Start development services

Next Steps

Testing

Run tests for your changes

Creating Pull Requests

Submit your changes for review