Skip to content
Tutorials Center
My learning

Topics

Lesson 7 of 37 ยท Concepts and Setup

Configuring Grafana with grafana.ini and Environment Variables

Configure Grafana with grafana.ini, custom.ini and GF_ environment variables: server, database, security, auth, SMTP and logging sections, plus precedence rules.

Grafana works out of the box, but real deployments need settings: the public URL, the database, SMTP for alert emails, sign-in methods and more. Configuration comes from an INI file and from environment variables, and the environment always wins. This makes the same container image usable in every environment.

Where the files are

Install Config file
Linux package /etc/grafana/grafana.ini
Docker image /etc/grafana/grafana.ini (usually overridden with env vars or a mounted file)
Windows <install dir>\conf\grafana.ini (copy sample.ini or defaults.ini to custom.ini)
Source / tarball conf/defaults.ini, override in conf/custom.ini

Never edit defaults.ini. It is replaced on upgrade. Put your changes in grafana.ini or custom.ini.

Syntax

An INI file has [sections] and key = value lines. Lines starting with ; or # are comments. Most options in the shipped sample are commented with ;, and you remove the semicolon to activate them.

INI
[server]
http_port = 3000
domain = grafana.example.com
root_url = https://grafana.example.com/

[security]
admin_user = admin
disable_gravatar = true

[users]
allow_sign_up = false
default_theme = dark

Environment variables

Any option can be set with GF_<SECTION>_<KEY> in uppercase. Dots in section names become underscores.

INI Environment variable
[server] http_port GF_SERVER_HTTP_PORT
[security] admin_password GF_SECURITY_ADMIN_PASSWORD
[auth.anonymous] enabled GF_AUTH_ANONYMOUS_ENABLED
[smtp] host GF_SMTP_HOST

In Docker: docker run -e GF_SERVER_ROOT_URL=https://grafana.example.com/ ....

File-based secrets

Appending __FILE to an option name makes Grafana read its value from a file, ideal for Docker or Kubernetes secrets: GF_SECURITY_ADMIN_PASSWORD__FILE=/run/secrets/admin_password. This keeps passwords out of process listings and images.

Precedence

  1. Command-line arguments (for example cfg:default.server.http_port=3001)
  2. Environment variables
  3. custom.ini / grafana.ini
  4. defaults.ini

The stand-in below merges layers the same way, so you can predict the result of a config.

JS Stand-in: resolve configuration layers

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Important sections

[server]: protocol, http_addr, http_port, domain, root_url (the public address; essential behind a proxy or for correct links in alert emails), serve_from_sub_path, cert_file / cert_key for HTTPS.

[database]: type (sqlite3 default, mysql, postgres), host, name, user, password. SQLite is fine for small setups; use MySQL or PostgreSQL for high availability or many users.

[security]: admin_user, admin_password (only used when the database is first created), secret_key (encrypts stored data source passwords; back it up), cookie_secure, allow_embedding.

[auth] and sub-sections like [auth.anonymous], [auth.basic], [auth.ldap], [auth.generic_oauth], [auth.github]: sign-in methods.

[smtp]: enabled, host, user, password, from_address, needed for alert emails and invitations.

[log]: mode (console, file), level (debug, info, warn, error).

[paths]: data, logs, plugins, provisioning.

Reload and restart

Most settings need a restart of the Grafana server to take effect. Provisioned files (dashboards, data sources) can be reloaded without a restart via the Admin API or by waiting for the periodic scan. Check Administration > Settings (server admins) to see the final values Grafana is using; sensitive values are hidden.

A quick linter

Typos in INI files fail silently: a misspelled key is simply ignored. The stand-in below parses INI text and warns about unknown keys, which shows why checking the Settings page is worth it.

JS Stand-in: INI parser and key check

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Practical advice

  • Set root_url correctly; wrong values cause broken links and OAuth failures.
  • Keep secrets out of INI files in version control; use __FILE or your secret store.
  • Back up secret_key; losing it makes stored data source passwords unreadable.
  • Document changes: a small grafana.ini with only your overrides is easier to review than a full copy.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which environment variable sets [server] http_port?

    Format: GF_<SECTION>_<KEY> in uppercase.
  2. 2. Which has the highest precedence?

    Command-line args beat env vars, which beat the INI file and defaults.
  3. 3. What does appending __FILE to a setting name do?

    It supports Docker and Kubernetes secrets mounted as files.
  4. 4. Why should you not edit defaults.ini?

    Put overrides in grafana.ini or custom.ini.

Summary

  • Settings come from INI files and GF_ environment variables; env wins.
  • Never edit defaults.ini; use grafana.ini/custom.ini.
  • Key sections: server, database, security, auth, smtp, log, paths.
  • Set root_url, back up secret_key, use __FILE for secrets.
  • Restart after changes and verify in Administration > Settings.

Next: Running Grafana with Docker Compose