Quickstart Guide

Get started with Grafana in minutes - from installation to your first dashboard

Quickstart Guide

This guide will walk you through installing Grafana, configuring a data source, and creating your first dashboard in just a few minutes.

What You’ll Build

By the end of this quickstart, you’ll have:

• A running Grafana instance
• A configured data source (TestData DB)
• A functional dashboard with time-series visualizations
• An understanding of basic Grafana workflows

Prerequisites

• Node.js 22.x or later (for development builds)
• Go 1.25.7 or later (for backend)
• GCC (required for CGo/SQLite compilation)
• A modern web browser

For production deployments, pre-built binaries and Docker images are available that don’t require development dependencies.

Installation

1. Clone the Repository

   First, clone the Grafana repository:

   git clone https://github.com/grafana/grafana.git
   cd grafana
   
2. Install Dependencies

   Install frontend dependencies using Yarn:

   yarn install --immutable
   

   Grafana uses Yarn 4.11.0 via Corepack. Run corepack enable if the yarn command is not found.

3. Start the Backend

   Build and start the Grafana backend with hot-reload:

   make run
   

   This starts the backend on localhost:3000 using the embedded SQLite database. The first build takes approximately 3 minutes.

   Wait for the message “HTTP Server Listen” before proceeding to the next step.

4. Start the Frontend (Optional)

   In a separate terminal, start the webpack dev server for frontend development:

   yarn start
   

   The backend automatically proxies to the frontend dev server. First compilation takes about 45 seconds.

5. Access Grafana

   Open your browser and navigate to:

   http://localhost:3000
   

   Use the default credentials:

   • Username: admin
   • Password: admin

   You’ll be prompted to change the password on first login.

Configuration

Grafana uses a configuration file system with defaults and overrides:

• Default configuration: conf/defaults.ini
• Custom overrides: conf/custom.ini

Key Configuration Options

# conf/defaults.ini (excerpt)
[server]
protocol = http
http_port = 3000
domain = localhost
root_url = %(protocol)s://%(domain)s:%(http_port)s/

[database]
type = sqlite3  # or mysql, postgres
path = data/grafana.db

[paths]
data = data
logs = data/log
plugins = data/plugins

Adding Your First Data Source

1. Navigate to Data Sources

   From the Grafana home page:

   1. Click the menu icon (☰) in the top-left
   2. Go to Connections → Data sources
   3. Click Add data source
2. Select TestData DB

   For this quickstart, we’ll use the built-in TestData data source:

   1. Search for “TestData DB” in the data source list
   2. Click on it to open the configuration page

   TestData DB generates random time-series data, perfect for testing and learning Grafana without setting up external databases.

3. Configure the Data Source

   On the configuration page:

   1. Set the Name to “TestData”
   2. Leave all other settings at their defaults
   3. Click Save & Test

   You should see a success message: “Data source is working”

Data Source API Example

Under the hood, Grafana creates a data source record via the API:

// pkg/api/datasources.go (simplified)
type DataSourceSettings struct {
    ID        int64  `json:"id"`
    UID       string `json:"uid"`
    OrgID     int64  `json:"orgId"`
    Name      string `json:"name"`
    Type      string `json:"type"`      // e.g., "testdata"
    Access    string `json:"access"`    // "proxy" or "direct"
    URL       string `json:"url"`
    Database  string `json:"database"`
    IsDefault bool   `json:"isDefault"`
    JsonData  map[string]interface{} `json:"jsonData"`
}

Creating Your First Dashboard

1. Create a New Dashboard

   1. Click the + icon in the sidebar
   2. Select Dashboard
   3. Click Add visualization
2. Configure the Query

   In the query editor at the bottom:

   1. Data source: Select “TestData” (the one you just created)
   2. Scenario: Choose “Random Walk” from the dropdown
   3. Alias: Enter “Series 1”

   The panel will immediately show a random walk time-series visualization.

3. Customize the Panel

   On the right side, customize your panel:

   Panel options:

   • Title: “My First Panel”
   • Description: “A random walk time series”

   Graph styles:

   • Line width: 2
   • Fill opacity: 10
   • Point size: 5
4. Add Field Configuration

   Configure how data is displayed:

   1. Scroll down to Field section
   2. Set Unit to “short” (for readable numbers)
   3. Set Decimals to 2
   4. Under Thresholds, add warning (50) and error (80) thresholds
5. Save the Dashboard

   1. Click Apply in the top-right to return to the dashboard
   2. Click the Save icon (💾) in the top bar
   3. Enter a name: “My First Dashboard”
   4. Click Save

Understanding the Dashboard Model

Dashboards in Grafana are stored as JSON with a structured schema:

// Simplified panel structure from @grafana/schema
interface Panel {
  id: number;              // Unique panel ID within dashboard
  type: string;            // Panel plugin type (e.g., "timeseries")
  title: string;           // Panel title
  gridPos: {
    x: number;             // Grid position X (0-24)
    y: number;             // Grid position Y
    w: number;             // Width in grid units
    h: number;             // Height in grid units
  };
  targets: DataQuery[];    // Array of queries to execute
  fieldConfig: FieldConfigSource;  // Field display configuration
  options: Record<string, any>;    // Panel-specific options
}

Next Steps

Explore Core Concepts

Learn about dashboards, panels, queries, variables, and alerting in depth.

Add Real Data Sources

Connect Grafana to Prometheus, Loki, PostgreSQL, MySQL, InfluxDB, and more.

Create Variables

Make your dashboards dynamic with template variables for filtering and navigation.

Set Up Alerting

Define alert rules and configure notification channels for your metrics.

Common Issues

Backend Fails to Start

Error: “failed to open database”

Solution: Ensure the data/ directory exists and has write permissions. Grafana uses SQLite by default, which requires filesystem access.

Port 3000 Already in Use

Edit conf/custom.ini and change the port:

[server]
http_port = 3001

Then restart Grafana.

Frontend Not Updating

If running yarn start, ensure the webpack dev server is running and check for compilation errors in the terminal.

Resources

• Configuration Reference: See conf/defaults.ini for all available options
• API Documentation: Swagger docs available at /swagger when running in development mode
• Plugin Development: Check packages/ for reusable packages like @grafana/data, @grafana/ui, and @grafana/runtime

Congratulations! You’ve successfully set up Grafana and created your first dashboard. Continue to Core Concepts to deepen your understanding.