Grafana Configuration File
Every Grafana server reads a settings file at startup. The file controls the web address, the database, the login rules, the email server, and dozens of other behaviours. Knowing how the file works lets you change Grafana without touching any code and keeps your setup repeatable.
The Phone Settings Analogy
A new phone ships with factory settings. You open the settings menu to change the language, the screen brightness, and the notification sounds. Your choices override the factory values and the phone remembers them. Grafana behaves the same way. Built-in defaults give you a working server, and the configuration file holds your personal overrides.
Priority (lowest to highest)
1. Built-in defaults defaults.ini
2. Your settings file grafana.ini
3. Environment variables GF_SERVER_HTTP_PORT=3001
(highest priority wins)
Find the File
| Installation | Typical Location |
|---|---|
| Linux package (deb or rpm) | /etc/grafana/grafana.ini |
| Windows installer | conf\custom.ini inside the install folder |
| Standalone archive | conf/custom.ini inside the extracted folder |
| Docker | Environment variables, or a mounted file at /etc/grafana/grafana.ini |
Never edit defaults.ini. Upgrades replace that file and erase your changes. Place every override in your own settings file.
File Structure
The file groups settings into sections. A section name sits in square brackets, and each setting below it uses a key and a value. Place a semicolon at the start of a line to turn the setting into a comment, so Grafana ignores it.
[server]
http_port = 3000
domain = grafana.mycompany.com
[security]
admin_user = admin
;admin_password = set-this-outside-the-file
[users]
allow_sign_up = false
Remove the semicolon from a line to activate it. Keep the semicolon on settings you do not need.
Important Sections
Paths
The [paths] section tells Grafana where to keep its data, logs, plugins, and provisioning files. Change these values when you want storage on a larger disk.
Server
The [server] section sets the port, the domain, and the public address. Behind a reverse proxy, the root_url key matters because links in emails and alerts use that address.
Database
The [database] section selects SQLite, MySQL, or PostgreSQL. Larger teams move to PostgreSQL or MySQL for reliability.
[database]
type = postgres
host = db.internal:5432
name = grafana
user = grafana
Security
The [security] section holds the admin account and the secret key that protects stored data source passwords. Keep the secret key private and consistent across servers in a cluster.
Users
The [users] section controls sign-up, the default role for new users, and the default theme. Switch off allow_sign_up on any server that faces the internet.
SMTP
The [smtp] section configures the email server that sends alert emails and invitations.
[smtp]
enabled = true
host = smtp.mycompany.com:587
from_address = grafana@mycompany.com
Logging
The [log] section sets the log level. Choose info for daily work and debug while you investigate a problem.
Environment Variables
Any setting accepts an environment variable. Write GF_, the section name, an underscore, and the key, all in capital letters.
| File Setting | Environment Variable |
|---|---|
| [server] http_port | GF_SERVER_HTTP_PORT |
| [users] allow_sign_up | GF_USERS_ALLOW_SIGN_UP |
| [log] level | GF_LOG_LEVEL |
Containers and cloud platforms favour environment variables, because they avoid file mounts and keep secrets out of the repository.
Apply Your Changes
Grafana reads the file only at startup. Save the file and restart the service.
sudo systemctl restart grafana-server
Check the log file if the service refuses to start. A typing mistake in a section name is the usual cause.
Safe Habits
- Back up the file before each edit.
- Store the file in version control, and keep passwords out of it.
- Change one setting at a time, so you know which change caused a problem.
- Keep a short comment above each custom setting that explains the reason.