Published

Grafana

Dashboards and alerting for metrics, logs and traces: Grafana queries data sources such as Prometheus and Loki, draws them as panels and sends alert notifications. It stores dashboards, users and alert rules, not the data itself. Fits a home lab or a team that wants one place to watch its servers and services.

Resources by load level

What the app itself needs at each level, next to what we recommend for a server that runs only this app.

Level	What it means	App requirements	Recommended
LightEstimate	Home lab: up to 5 concurrent users, about 20 dashboards refreshing every minute or slower, up to 50 alert rules, 1-3 data sources such as Prometheus and Loki, SQLite.	1 vCPU · 0.5 GiB RAM · 2.778 GiB disk	1.32 vCPU · 2.1 GiB RAM · 12.625 GiB disk
MediumEstimate	Team: up to 25 concurrent users, up to 200 dashboards (10-20 panels, refresh 30 s or slower), up to 100 alert rules, under 5 data sources: the docs' Small tier.	2 vCPU · 4 GiB RAM · 11.778 GiB disk	2.52 vCPU · 6.3 GiB RAM · 22.975 GiB disk
HeavyEstimate	Department: up to 100 concurrent users, about 1,000 dashboards, up to 500 alert rules, 5-25 data sources, one instance with database=postgres (the docs' Medium tier).	4 vCPU · 8 GiB RAM · 21.778 GiB disk	4.92 vCPU · 11.1 GiB RAM · 34.475 GiB disk

Recommended = app requirements + system baseline + safety headroom, under sizing policy 2026.10.0. Options stay at their defaults. “Estimate” means the sources give no number for that case, so it is worked out from them by the method stated under Components. How the numbers are built

Size it in the Stack Sizer

Ready-to-run files

Support level Supported

Compose template from the official sources; not yet verified by a run.

Create docker-compose

Components

What each component needs at each load level, before baseline and headroom.

vCPU / GiB RAM / GiB disk
Component	Light	Medium	Heavy	Sources
Grafana (UI, data source proxy and alerting) (app)	1 / 0.5 / 2.778	2 / 4 / 11.778	4 / 8 / 21.778	[11][12][13]
PostgreSQL (database)	—	—	—

How the estimates are worked out

Grafana (UI, data source proxy and alerting) · Light: CPU and RAM: the documented minimum (512 MB, 1 core), enough for a few users and a small rule set. Disk: image 482,587,117 B compressed (0.449 GiB) + 1,426,266,112 B unpacked (1.328 GiB), both kept by the containerd store = 1.778 GiB + 1 GiB for grafana.db, plugins and the search index (ANAROQ's assumption) = 2.778.
Grafana (UI, data source proxy and alerting) · Medium: The docs' Small tier (under 25 concurrent users, 100 alert rules, 5 data sources, 200 dashboards) asks for 2 cores, 2-4 GB and a 10-20 GB database disk; this level fills the tier, so it takes the top of the RAM range and the bottom of the disk range. Disk: image 482,587,117 B compressed (0.449 GiB) + 1,426,266,112 B unpacked (1.328 GiB), both kept by the containerd store = 1.778 GiB + 10 GiB = 11.778.
Grafana (UI, data source proxy and alerting) · Heavy: The docs' Medium tier (25-200 concurrent users, 100-1,000 rules, 200-2,000 dashboards) asks for 4-8 cores, 8-16 GB and 20-50 GB per instance, with an external database; this level sits in its lower half on one instance and takes the lower bounds. Disk: image 482,587,117 B compressed (0.449 GiB) + 1,426,266,112 B unpacked (1.328 GiB), both kept by the containerd store = 1.778 GiB + 20 GiB = 21.778.
database · PostgreSQL: GF_DATABASE_MAX_OPEN_CONN=20 in the template keeps Grafana's pool (unbounded by default) inside the sidecar's 20-connection envelope. The database disk of each level stays on the Grafana component, so the sidecar's 5 GiB is extra room. Embedded metadata DB with the image's default config: equals the PostgreSQL profile's light preset (≤ 5 GB data, ≤ 20 concurrent connections) at every load level. Light preset method: shared_buffers 25% of RAM, worst-case work_mem/maintenance_work_mem budget, 0.5 GiB image + 5 GiB data + 1 GiB WAL.

Options that change resources

database

Database engine. SQLite (the default) is a file in /var/lib/grafana and suits small instances; the docs don't recommend it for production and call it unsuitable from the Medium tier on. PostgreSQL adds a separate container.

Default: sqlite

When postgres: PostgreSQL +1 vCPU · +1 GiB RAM · +6.5 GiB disk [4][11][31][32][33][34][35][36][37]

Ports

Public ports are meant to be reached from outside the stack, usually through a reverse proxy; internal ones stay on the stack's own network.

Component	Port	Exposure	Purpose	Sources
Grafana (UI, data source proxy and alerting)	3000/tcp	Public, through a proxy	Web UI and HTTP API (HTTP; put behind a TLS reverse proxy)	[2][5][6]
PostgreSQL	5432/tcp	Internal only	PostgreSQL connections from Grafana (database=postgres only)	[4][36]

Every port in the catalog, with conflicts between apps

User and permissions (UID/GID)

The user each container's process runs as, and the paths it writes to. A bind mount for one of these paths must be writable by that UID:GID.

Component	UID:GID	User	Starts as root	Writes to	Sources
Grafana (UI, data source proxy and alerting)	472:0	`grafana`	No	`/var/lib/grafana`	[2][6][7][8]
PostgreSQL	999:999	`postgres`	Yes, prepares its directories, then drops to this user	`/var/lib/postgresql/var/run/postgresql`	[29][30][36]

Grafana (UI, data source proxy and alerting): The image runs as uid 472 (user grafana, group root, gid 0) from the start; /var/lib/grafana is owned by it with mode 777, so a new named volume works as is. A bind mount must be writable by uid 472, or the container must run with --user set to the directory's owner, as the docs show.

Storage growth

How much each component's data grows per month at each load level, on top of the disk in the profile. A value marked Assumption is ANAROQ's stated assumption, not a figure from the sources; the notes say what it rests on.

GiB per month
Component	Light	Medium	Heavy	Sources
Grafana (UI, data source proxy and alerting)Assumption	0.05	0.25	1	[5][19]
PostgreSQLAssumption	0.05	0.25	1	[5][11]

What the growth figures rest on

Grafana (UI, data source proxy and alerting): Upstream gives no growth rate. Alert state history is written as annotations by default, and annotations are kept forever (max_age 0); each dashboard keeps 20 versions; logs go to the console, not the volume. Assumed: 0.05 GiB a month for this level's rules and dashboards. With database=postgres these rows grow in the PostgreSQL volume instead.
Grafana (UI, data source proxy and alerting): Upstream gives no growth rate. Alert state history is written as annotations by default, and annotations are kept forever (max_age 0); each dashboard keeps 20 versions; logs go to the console, not the volume. Assumed: 0.25 GiB a month for this level's rules and dashboards. With database=postgres these rows grow in the PostgreSQL volume instead.
Grafana (UI, data source proxy and alerting): Upstream gives no growth rate. Alert state history is written as annotations by default, and annotations are kept forever (max_age 0); each dashboard keeps 20 versions; logs go to the console, not the volume. Assumed: 1 GiB a month for this level's rules and dashboards. With database=postgres these rows grow in the PostgreSQL volume instead.
PostgreSQL: Only with database=postgres, and instead of the Grafana figure: the same annotation and dashboard-version rows, 0.05 GiB a month (ANAROQ's assumption). Set retention in [annotations.*] max_age to bound it.
PostgreSQL: Only with database=postgres, and instead of the Grafana figure: the same annotation and dashboard-version rows, 0.25 GiB a month (ANAROQ's assumption). Set retention in [annotations.*] max_age to bound it.
PostgreSQL: Only with database=postgres, and instead of the Grafana figure: the same annotation and dashboard-version rows, 1 GiB a month (ANAROQ's assumption). Set retention in [annotations.*] max_age to bound it.

Upgrade and rollback

How to move to a new version safely, and how to go back if it fails.

Back up first

Stop Grafana and copy the /var/lib/grafana volume (grafana.db and plugins); with database=postgres, take a pg_dump of the grafana database. Keep .env with it: GRAFANA_SECRET_KEY is needed to read the stored data source secrets. [10][22]

Upgrade steps

Read the upgrade guide and the breaking changes of every version you skip. Before a major upgrade (for example 12.x to 13), move to the latest patch of your line and update all plugins first, as the v13 guide orders. [17][18][21]
Back up (see below), set the new pinned tag grafana/grafana:X.Y.Z in the Compose file, then run docker compose pull and docker compose up -d. Settings live in the GF_* variables, so nothing in the container needs to be kept. [2][20]
Grafana migrates its database at start (13.0 also moves dashboards and folders to unified storage). Watch docker compose logs grafana and /api/health, then run docker compose exec grafana grafana cli plugins update-all and restart. [9][18][20]

Roll back

Stop Grafana, restore the pre-upgrade copy of /var/lib/grafana (or the pg_dump), pin the previous tag and run docker compose up -d. Don't start an older version on a migrated database: after 13.0 it reads stale legacy tables. [18][22]

Known breaking changes

In 13.1.0: Zipkin was removed from the core data sources, and Azure and SigV4 authentication were removed from the core Prometheus data source. Check those data sources before upgrading. [17]
In 13.0.0: Dashboards and folders migrate once to unified storage at start; an older version then reads stale tables, so a downgrade needs the pre-upgrade backup. On SQLite the migration can hit 'database is locked'; the guide lists [unified_storage] settings for it. [18]
In 13.0.0: Data source APIs by numeric id are off (use uid), the Image Renderer runs only as a separate service, grafana-cli and grafana-server are gone (use grafana cli and grafana server), and Elasticsearch left the core data sources. [17][18]
In 12.4.0: Plugin processes no longer receive the host's environment variables by default; a backend plugin that read settings from the environment needs them configured another way. [17]
In 12.0.0: AngularJS support was removed, so Angular-based plugins and panels stop working; data source UIDs must match the documented format; from 11.x the annotation table is rewritten, which needs 2-3 times its size in free disk. [17][19]

Limits

SQLite (the default) suits small instances; the docs don't recommend it for production and call it unsuitable from the Medium tier on: use database=postgres. High availability (several instances, a shared session store) is not templated, and moving data from SQLite to another database later is up to you. [11]
These figures cover the Grafana server only. Prometheus, Loki and other data sources have their own sizing, and the Image Renderer (about 1 GB per worker, a separate service since 13.0) is not included. [11][18]
In a generated file Grafana cannot reach Prometheus or Loki as is: each app gets its own network (grafana-internal, prometheus-internal, loki-internal), and names resolve only on a shared one. Add prometheus-internal and/or loki-internal to the networks of the grafana service, then add data sources under Connections > Data sources as http://prometheus:9090 and http://loki:3100. Not localhost, which inside the container is Grafana itself. [25][26][27]
Plugins install at start from GF_PLUGINS_PREINSTALL (a comma-separated list, plugin@version to pin) into /var/lib/grafana/plugins; GF_INSTALL_PLUGINS is deprecated. The template sets none, and a plugin runs its code inside Grafana. [2][3][7]
The template uses grafana/grafana, the open-source edition under AGPLv3. The docs' examples default to grafana/grafana-enterprise, a separate image under another license that unlocks Enterprise features with a license key. [2][3][16]

Security

The admin account comes from GRAFANA_ADMIN_USER and GRAFANA_ADMIN_PASSWORD on the first start only; a later change in .env has no effect. Change the password in the UI, or recover it with docker compose exec grafana grafana cli admin reset-admin-password. [4][24]
Sign-up and anonymous access are off by default; keep them off on a server reachable from the internet. With anonymous access, anyone can list dashboards and data sources and send arbitrary queries to every data source. [5][23]
Data source passwords and tokens are encrypted with keys wrapped by GF_SECURITY_SECRET_KEY. The built-in default is public in defaults.ini, so the template sets GRAFANA_SECRET_KEY from .env; changing it later means re-encrypting the stored secrets. [4][5][10]
Viewers can send any query to the data sources of their organization, and the data source proxy can reach other services on the server's network. Give data sources least-privilege credentials, and restrict proxy targets with data_source_proxy_whitelist or a firewall. [4][23]
Privacy: by default Grafana sends anonymous usage counters to stats.grafana.org every 24 hours and checks grafana.com for new versions every 10 minutes. The disable-reporting option turns the counters off. [4][5]

Backup

Back up the /var/lib/grafana volume with Grafana stopped: grafana.db (SQLite) holds users, dashboards, alert rules and encrypted data source secrets, and plugins/ holds the installed plugins. With database=postgres, add a pg_dump of the grafana database. [3][22]
Store GRAFANA_SECRET_KEY from .env with the backup (encrypted, off the server): a restored database with a different key cannot decrypt its data source and notification secrets. [10][22]