Command Palette

Search for a command to run...

GitHubGitHub

Grafana Installation Guide

Install Grafana 13.2 on Linux, Windows, macOS, Docker and Kubernetes, connect Prometheus as a data source, and size the deployment for production.

Grafana is the visualization layer for metrics, logs and traces. It queries Prometheus, Loki, Tempo, Elasticsearch and dozens of other backends, and turns them into dashboards and alerts.

System Requirements

TierCPUMemoryDiskInstances
Small (under 25 users)2 cores2–4 GB10–20 GB SSD1
Medium (25–200 users)4–8 cores8–16 GB20–50 GB SSD2 (load balanced)
Large (200+ users)8–16+ cores16–32+ GB50+ GB SSD3+ (load balanced)
  • A supported database: SQLite 3 (development only), MySQL 8.0+ or PostgreSQL 12+
  • A current browser with JavaScript enabled

Installation Instructions

Ubuntu / Debian (apt)

# Prerequisites
sudo apt-get install -y apt-transport-https wget gnupg
 
# Import the GPG key into a keyring
sudo mkdir -p /etc/apt/keyrings
sudo wget -O /etc/apt/keyrings/grafana.asc https://apt.grafana.com/gpg-full.key
sudo chmod 644 /etc/apt/keyrings/grafana.asc
 
# Add the repository
echo "deb [signed-by=/etc/apt/keyrings/grafana.asc] https://apt.grafana.com stable main" \
  | sudo tee /etc/apt/sources.list.d/grafana.list
 
# Install
sudo apt-get update
sudo apt-get install -y grafana          # OSS
# sudo apt-get install -y grafana-enterprise   # Enterprise
 
# Start and enable the service
sudo systemctl enable --now grafana-server
sudo systemctl status grafana-server

Verifying the Installation

# The service is running
sudo systemctl status grafana-server
 
# The health endpoint
curl -s http://localhost:3000/api/health
 
# The version
curl -s http://localhost:3000/api/health | jq .

Open http://localhost:3000 and sign in with admin / admin — Grafana asks you to change the password immediately.

Configuration

Grafana reads /etc/grafana/grafana.ini. Every setting can also be set with an environment variable: GF_<SECTION>_<KEY>, for example GF_SECURITY_ADMIN_PASSWORD or GF_SERVER_HTTP_PORT.

[server]
http_port = 3000
domain = grafana.example.com
root_url = https://grafana.example.com
 
[security]
admin_user = admin
admin_password = change-me
allow_sign_up = false
cookie_secure = true
# Set to "none" when Grafana runs behind a proxy that terminates TLS
cookie_samesite = strict
 
[users]
allow_sign_up = false
default_theme = dark
 
[auth.anonymous]
enabled = false
 
[auth.basic]
enabled = true
 
[auth.oauth.github]
enabled = true
client_id = your-client-id
client_secret = your-client-secret
scopes = user:email
allow_sign_up = true
 
[database]
type = postgres
host = localhost:5432
name = grafana
user = grafana
password = your-password
ssl_mode = require
 
[smtp]
enabled = true
host = smtp.example.com:587
user = grafana@example.com
password = your-app-password
from_address = grafana@example.com
from_name = Grafana
 
[unified_alerting]
enabled = true
 
[alerting]
enabled = true

Connecting Prometheus

  1. Open Connections → Data sources → Add data source
  2. Choose Prometheus
  3. Set the URL to your Prometheus instance (http://prometheus:9090 in Docker, or http://localhost:9090)
  4. Set Prometheus type to Prometheus
  5. Leave Access as Server (default) and click Save & test
# You can also provision it from a file
# /etc/grafana/provisioning/datasources/prometheus.yaml
apiVersion: 1
 
datasources:
  - name: Prometheus
    type: prometheus
    access: proxy
    url: http://localhost:9090
    isDefault: true
    editable: true

Provisioning Dashboards and Datasources

# /etc/grafana/provisioning/datasources/datasources.yaml
apiVersion: 1
 
datasources:
  - name: Prometheus
    type: prometheus
    access: proxy
    url: http://prometheus:9090
    isDefault: true
# /etc/grafana/provisioning/dashboards/dashboards.yaml
apiVersion: 1
 
providers:
  - name: 'default'
    orgId: 1
    folder: ''
    type: file
    disableDeletion: false
    updateIntervalSeconds: 30
    options:
      path: /etc/grafana/dashboards

HTTPS

# Generate a certificate
sudo mkdir -p /etc/grafana/ssl
sudo openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
  -keyout /etc/grafana/ssl/grafana.key \
  -out /etc/grafana/ssl/grafana.crt
 
sudo chown -R grafana:grafana /etc/grafana/ssl
[server]
protocol = https
cert_file = /etc/grafana/ssl/grafana.crt
cert_key = /etc/grafana/ssl/grafana.key

Upgrading

# Check the current version
sudo grafana-server -v
# or
curl -s http://localhost:3000/api/health
 
# Upgrade the package
sudo apt-get update && sudo apt-get install --only-upgrade grafana
sudo systemctl restart grafana-server
# Back up before an upgrade
sudo systemctl stop grafana-server
sudo tar -czf /var/backups/grafana-$(date +%F).tar.gz -C /var/lib/grafana .
sudo systemctl start grafana-server

Troubleshooting

Best Practices

  1. Never use SQLite in production — use MySQL 8.0+ or PostgreSQL 12+.
  2. Provision everything from files — datasources, dashboards and alert rules belong in Git, not in the UI.
  3. Export dashboards as JSON and keep them next to your code.
  4. Use an external identity provider (OAuth/OIDC, SAML or LDAP) instead of local accounts.
  5. Run the image renderer as a separate process — it is the component that needs the most memory.
  6. Set root_url, cookie_secure and cookie_samesite before you put Grafana behind a proxy.
  7. Use the Unified Alerting feature for anything that must page someone.
  8. Pin the Grafana version in Docker images and Kubernetes deployments.
  9. Back up both the database and /var/lib/grafana (plugins, dashboards stored on disk).

Next Steps

Prometheus

Install Prometheus 3.15 with node_exporter 1.12, configure scraping and alerting in the 3.x format, and understand the breaking changes when upgrading from 2.x.

Nagios

Install Nagios Core 4.5.14 and the Nagios Plugins on Linux, configure hosts and services, and verify the checks that keep your infrastructure honest.