> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/grafana/grafana/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

<Note>
  For production deployments, pre-built binaries and Docker images are available that don't require development dependencies.
</Note>

## Installation

<Steps>
  <Step title="Clone the Repository">
    First, clone the Grafana repository:

    ```bash theme={null}
    git clone https://github.com/grafana/grafana.git
    cd grafana
    ```
  </Step>

  <Step title="Install Dependencies">
    Install frontend dependencies using Yarn:

    ```bash theme={null}
    yarn install --immutable
    ```

    <Note>
      Grafana uses Yarn 4.11.0 via Corepack. Run `corepack enable` if the `yarn` command is not found.
    </Note>
  </Step>

  <Step title="Start the Backend">
    Build and start the Grafana backend with hot-reload:

    ```bash theme={null}
    make run
    ```

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

    <Warning>
      Wait for the message "HTTP Server Listen" before proceeding to the next step.
    </Warning>
  </Step>

  <Step title="Start the Frontend (Optional)">
    In a separate terminal, start the webpack dev server for frontend development:

    ```bash theme={null}
    yarn start
    ```

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

  <Step title="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.
  </Step>
</Steps>

## Configuration

Grafana uses a configuration file system with defaults and overrides:

* **Default configuration**: `conf/defaults.ini`
* **Custom overrides**: `conf/custom.ini`

### Key Configuration Options

```ini theme={null}
# 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

<Steps>
  <Step title="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**
  </Step>

  <Step title="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

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

  <Step title="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"
  </Step>
</Steps>

### Data Source API Example

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

```go theme={null}
// 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

<Steps>
  <Step title="Create a New Dashboard">
    1. Click the **+** icon in the sidebar
    2. Select **Dashboard**
    3. Click **Add visualization**
  </Step>

  <Step title="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.
  </Step>

  <Step title="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
  </Step>

  <Step title="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
  </Step>

  <Step title="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**
  </Step>
</Steps>

## Understanding the Dashboard Model

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

```typescript theme={null}
// 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

<CardGroup cols={2}>
  <Card title="Explore Core Concepts" icon="book" href="/core-concepts">
    Learn about dashboards, panels, queries, variables, and alerting in depth.
  </Card>

  <Card title="Add Real Data Sources" icon="database">
    Connect Grafana to Prometheus, Loki, PostgreSQL, MySQL, InfluxDB, and more.
  </Card>

  <Card title="Create Variables" icon="sliders">
    Make your dashboards dynamic with template variables for filtering and navigation.
  </Card>

  <Card title="Set Up Alerting" icon="bell">
    Define alert rules and configure notification channels for your metrics.
  </Card>
</CardGroup>

## Common Issues

### Backend Fails to Start

<Warning>
  **Error**: "failed to open database"

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

### Port 3000 Already in Use

Edit `conf/custom.ini` and change the port:

```ini theme={null}
[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`

<Note>
  Congratulations! You've successfully set up Grafana and created your first dashboard. Continue to [Core Concepts](/core-concepts) to deepen your understanding.
</Note>