Getting started

This page covers the local developer loop only — how to clone, install dependencies, build, and run Grafana with hot reload. For installing pre-built Grafana for end users, see grafana.com/get.

Prerequisites

Tool	Version	Used for
Go	1.26.x (track go.mod)	Backend, plugins, CLI
Node.js	v24.x (see .nvmrc)	Frontend tooling
Yarn	4.11.x via Corepack (.yarn/releases/)	Workspace package manager
GCC / Clang	Any recent	CGo builds (SQLite backend)
Make	GNU Make	Top-level build orchestration

The full canonical setup guide lives in contribute/developer-guide.md. The summary below mirrors the entries in AGENTS.md.

First-time setup

# 1. Install JS dependencies (frozen lockfile)
yarn install --immutable

# 2. Optional: install pre-commit hooks
make lefthook-install

No external database is required by default — Grafana ships with embedded SQLite and stores data under data/ in the repo root.

Running Grafana locally

Grafana runs as two independent dev processes that talk to each other over HTTP:

# Backend, with hot reload (air): localhost:3000, login admin/admin
make run

# In another terminal — Frontend dev server (webpack watch)
yarn start

The first make run build is slow (~3 min) because the backend is compiled with -gcflags all=-N -l for debugging. Subsequent rebuilds are seconds. The first yarn start compile is ~45 s.

The Go server proxies asset requests to the webpack dev server, so visiting http://localhost:3000 gives you live-reloaded frontend changes against the locally built backend.

Building artifacts

make build-backend         # Compiles bin/<arch>/grafana
yarn build                 # Production frontend bundle into public/build/

To build a packaged release locally see scripts/build/ and packaging/.

Running tests

The repo has three independent test suites. Match the suite to what you changed.

# Backend
go test -run TestName ./pkg/services/myservice/   # one targeted test
make test-go-unit                                 # all unit tests
make test-go-integration                          # integration tests (needs a DB for some)

# Frontend
yarn test path/to/file                            # NOTE: defaults to --watch
yarn jest --no-watch path/to/file                 # one-shot
yarn test:ci                                      # full CI run

# End-to-end
yarn e2e:playwright path/to/test.spec.ts          # one Playwright test

See How to contribute / Testing for an in-depth tour.

Backing services for richer dev environments

The devenv/ directory contains Docker Compose stacks for testing against real datasources or non-SQLite databases:

make devenv sources=postgres,influxdb,loki        # bring up just those
make devenv-down                                  # tear them all down

For Postgres/MySQL integration tests:

make devenv sources=postgres_tests,mysql_tests
make test-go-integration-postgres

Code generation

Several pieces of generated code must be regenerated when their inputs change:

make gen-go                       # Wire DI graph (pkg/server/wire_gen.go)
make gen-cue                      # CUE schemas in kinds/ → Go + TS
make gen-apps                     # Grafana App SDK apps under apps/
make swagger-gen                  # OpenAPI specs (api-merged.json)
make gen-feature-toggles          # Feature flags table (pkg/services/featuremgmt/)
make i18n-extract                 # i18n message catalog
make update-workspace             # Refresh go.work after adding/removing modules

If a build fails with "missing module" or "wire injector not found", re-run the matching make gen-* target.

Common gotchas

• Frontend yarn test defaults to --watch. Use yarn jest --no-watch or pass --watchAll=false.
• Backend pkg/api/ test compilation is slow because of the dependency graph. Prefer -run TestName with a tight package path.
• Build tags oss, enterprise, pro gate enterprise-only files — most contributors only ever touch oss.
• .nvmrc is authoritative for Node version. Use nvm use if you have multiple Node versions installed.
• First-run corepack enable is required if yarn isn't found (Yarn 4 ships through Corepack rather than a global install).