Getting Started & Development Setup
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
Setting up the Grafana development environment requires configuring both frontend and backend components to create a functional local instance. The project follows a trunk-based development workflow where the main branch serves as the primary target for all contributions. Developers must manage dependencies across different ecosystems, including Go for the backend and Node.js for the frontend, while adhering to strict architectural and style guidelines.
This guide covers the end-to-end process from initial environment configuration to running localized test suites. It provides the necessary technical context for new contributors to align with Grafana's internal standards, such as the use of RTK Query for state management and structured Go patterns for backend services.
Sources: contribute/developer-guide.md:3-8, WORKFLOW.md:55-58, public/app/features/alerting/unified/AGENTS.md:143-145
Core Dependencies and Environment Setup
The development environment relies on several critical tools across different operating systems. Grafana uses corepack to manage package managers like Yarn and lefthook for pre-commit automation.
Required Software
| Dependency | Usage | Minimum / Supported Version |
|---|---|---|
| Git | Source control management | Latest stable |
| Go | Backend compilation | See go.mod |
| Node.js | Frontend development | LTS (See .nvmrc) |
| GCC | Optional CGO support | Needed for SQLite on Windows |
| Docker | Running background databases | Latest stable |
Sources: contribute/developer-guide.md:5-20, contribute/developer-guide.md:124-128
OS-Specific Setup
- macOS: Installation via Homebrew is recommended for Git, Go, and Node.js.
- Windows: Development is recommended through Windows Subsystem for Linux (WSL). For native builds, MinGW x64 or Scoop should be used to provide GCC and binutils for SQLite compilation.
- Pre-commit Hooks: lefthook is used to lint and format code. Installation is performed via
make lefthook-install.
Sources: contribute/developer-guide.md:23-40, contribute/developer-guide.md:61-68, contribute/developer-guide.md:124-127
Frontend Development Workflow
The frontend is built using React and TypeScript. Modern state management favors RTK Query over traditional Redux for data fetching.
Build Process
The following flowchart illustrates the frontend initialization and build cycle:
The frontend build process includes generating SASS theme files and building external plugins before starting the asset watcher.
Sources: contribute/developer-guide.md:73-95
Key Frontend Commands
yarn start: Starts the development build and watcher.yarn plugin:build:dev: Builds and watches all core plugins.yarn test: Executes the Jest test suite.yarn lint:prune: Removes unused ESLint suppressions fromeslint-suppressions.json.
Sources: contribute/developer-guide.md:89-106, contribute/create-pull-request.md:120-123
Backend Development Workflow
The backend is a Go-based web server that defaults to an embedded SQLite database for local development.
Server Lifecycle
The backend server manages API requests, authentication, and data source proxying.
Running make run compiles the Go source code and starts the web server.
Sources: contribute/developer-guide.md:115-121
Backend Configuration
Configuration is managed via .ini files. Developers should not modify defaults.ini directly but should use a custom.ini for overrides.
# conf/custom.ini
app_mode = development
| File Path | Description |
|---|---|
conf/defaults.ini | Default settings (do not edit) |
conf/custom.ini | Local overrides and dev mode |
conf/sample.ini | Reference for configuration options |
Sources: contribute/developer-guide.md:215-225, contribute/create-pull-request.md:225-230
Testing and Quality Assurance
Grafana employs a three-tier testing strategy: unit, integration, and end-to-end.
Testing Matrix
| Test Type | Tool | Command |
|---|---|---|
| Frontend Unit | Jest / RTL | yarn test |
| Backend Unit | Standard Go Tool | go test -v ./pkg/... |
| Integration | Go + Docker | make test-go-integration-mysql |
| End-to-End | Playwright | yarn e2e:playwright |
Sources: contribute/developer-guide.md:154-190
Database Integration Tests
Integration tests for PostgreSQL and MySQL require running Docker containers as background data sources.
# Start test databases
make devenv sources=mysql_tests,postgres_tests
# Run specific integration suite
make test-go-integration-postgres
Sources: contribute/developer-guide.md:167-175
Troubleshooting and Performance
High-resource tasks like yarn start or make run may require system-level adjustments.
Common Issues and Fixes
- Too Many Open Files: Use
ulimit -S -n 8000on UNIX systems to prevent crashes duringmake run. - File Watcher Limits: Increase
fs.inotify.max_user_watchesto524288on Linux to accommodate the large number of frontend files. - JS Heap Out of Memory: Increase Node memory limits by setting
NODE_OPTIONS="--max-old-space-size=8192". - CGO and Production Builds: In production, Grafana is built with
CGO_ENABLED=0for static binaries, whereas local dev uses CGO for the SQLite driver.
Sources: contribute/developer-guide.md:131-137, contribute/developer-guide.md:255-265, contribute/developer-guide.md:313-328, contribute/developer-guide.md:337-340
Summary
Setting up Grafana for development involves a multi-stack approach where frontend and backend components must be synchronized. By leveraging make for backend tasks and yarn for frontend assets, developers can establish a robust local environment. Adherence to the trunk-based workflow, proper configuration of custom.ini, and the utilization of Docker for data source testing are critical for successful contributions to the Grafana ecosystem.
Sources: contribute/developer-guide.md:3-8, WORKFLOW.md:55-58