grafana/grafana

Deployment

A high-level summary of how Grafana ships and runs in production. The canonical user-facing docs live at grafana.com/docs — this page focuses on what's in this repo.

Artifacts

Linux/macOS/Windows binaries — grafana-cli and grafana server. Built by make build.
Container image — built from Dockerfile. Published to grafana/grafana on Docker Hub.
Distro packages — .deb, .rpm, MSI under packaging/.

The build orchestration is split between scripts/build/, the per-step Makefile targets, and the GitHub Actions in .github/workflows/.

Process model

A single grafana server process handles:

HTTP API serving (port 3000 default).
The frontend (served as static files from the embedded bundle).
Datasource plugin host (in-process for built-ins, subprocesses for external plugins).
Alerting scheduler (ngalert).
Live coordinator (Centrifuge).
Background services (cleanup, update checks, plugin manager).

For HA, multiple grafana server replicas run behind a load balancer. They share state via:

The relational database (SQLite for single-node only; Postgres or MySQL for HA).
Redis (only when [live] ha_engine = redis is configured).
The unified storage resource server (when configured for multi-node).

Configuration

Two-tier:

conf/defaults.ini — bundled defaults.
conf/custom.ini (or --config <path>) — operator overrides.

Environment variables are also honored: GF_<SECTION>_<KEY>=value.

See Configuration reference.

Database

SQLite — default. Single file under data/grafana.db. Sufficient for single-node deployments and most dev/staging setups.
Postgres / MySQL — required for HA. Migrations run forward-only on every startup.

Schema changes happen via pkg/services/sqlstore/migrations/ — see SQL store and migrations.

Server-side image rendering (alert screenshots, PDF reports, snapshot previews) is delegated to a separate plugin process — grafana-image-renderer. Configure with the [rendering] section. The plugin uses Chrome internally; in containers, ensure you have the dependencies (grafana/grafana ships with the renderer pre-installed in some flavors).

Reverse proxies

Grafana is typically behind nginx, Traefik, or an ingress controller. WebSocket support is required for Live; SSE works as a fallback.

The [server] domain and root_url settings must match the public URL for OAuth callbacks and absolute URLs in emails.

Provisioning

For configuration-as-code, pkg/services/provisioning/ reads YAML/JSON from conf/provisioning/ at startup:

datasources/ — pre-configured datasources.
dashboards/ — pre-loaded dashboards from disk.
notifiers/ (legacy), alerting/ — alerting state.
plugins/ — pre-installed apps.

Newer GitOps-style provisioning is implemented in apps/provisioning/ — operators can drive Grafana state from a Git repository.

Backups

For SQLite, copy data/grafana.db while the server is stopped (or use SQLite's online backup API). For Postgres/MySQL, follow the standard DB backup procedure. Dashboards can also be exported as JSON via the API for selective backup.

Upgrading

Read the release notes — schema migrations are listed there.
Run a single replica through the upgrade first if HA. Other replicas should be stopped while migrations run.
Test plugins on the new version in staging — major version bumps occasionally require plugin updates.

Containers

The container image runs Grafana as the grafana user. Mount data/ and conf/ as volumes for persistence. The image entrypoint is /run.sh which forwards to grafana server.