Grafana’s dashboarding power is so flexible that its default branding is often the first thing people want to change.
Let’s see it in action. Imagine you’re building a managed observability platform for your clients. Each client needs their own distinct look and feel. Here’s a snippet of how you might configure Grafana’s white-labeling:
# grafana.ini
[auth.basic]
enabled = true
[auth.anonymous]
enabled = true
org_role = viewer
[auth.github]
enabled = true
client_id = YOUR_GITHUB_CLIENT_ID
client_secret = YOUR_GITHUB_CLIENT_SECRET
[external_oauth]
enabled = true
allow_sign_up = true
auto_login = true
client_id = YOUR_OAUTH_CLIENT_ID
client_secret = YOUR_OAUTH_CLIENT_SECRET
scopes = user:email openid profile email
auth_url = https://your-oauth-provider.com/auth
token_url = https://your-oauth-provider.com/token
api_url = https://your-oauth-provider.com/userinfo
tls_skip_verify = false
use_pkce = true
[dataproxy]
timeout = 30
[analytics]
reporting_enabled = false
checking_enabled = false
[paths]
data = /var/lib/grafana/data
logs = /var/log/grafana
plugins = /var/lib/grafana/plugins
provisioning = /etc/grafana/provisioning
[log]
mode = console
[server]
domain = your-grafana.com
root_url = https://your-grafana.com/
enable_gzip = true
http_port = 3000
protocol = http
[unified_alerting]
enabled = true
[grafana_com]
plugins_enabled = false
[feature_toggles]
enable_new_dynamic_table = true
enable_flamegraph_explorer = true
[external_image_renderer]
enabled = true
rendering_timeout = 60
The core problem this solves is brand consistency. When you offer a service, your clients expect their brand, not yours, to be front and center. White-labeling Grafana allows you to embed powerful dashboards into your own application or portal without exposing the Grafana UI’s default identity. This means clients see their logo, their color scheme, and potentially even their own login flow, creating a seamless experience.
Internally, Grafana achieves this through a combination of configuration settings and the ability to override specific assets. The grafana.ini file is your primary tool. You can set custom logos, favicons, and even CSS to completely reskin the interface. Beyond the grafana.ini file, Grafana also supports provisioning files for more dynamic configuration, especially for data sources and dashboards, but for branding, the grafana.ini is where the magic happens.
The root_url setting in grafana.ini is crucial. It tells Grafana the public URL where it’s accessible, and this is used in various parts of the UI, including links and redirects. Setting domain ensures that cookies and session management work correctly. For custom logos, you’ll typically upload them to a location accessible by the Grafana server and then reference them using file paths or URLs in the configuration. Grafana will then serve these custom assets instead of its defaults.
You can also leverage Grafana’s theming capabilities. By creating a custom theme that defines specific colors, fonts, and styles, you can further tailor the look and feel to match a client’s brand guidelines. This goes beyond just logos and favicons, affecting the entire UI’s aesthetic.
Most people focus on the allow_sign_up and auto_login settings within [external_oauth] or [auth.basic] for controlling user access. However, the org_role = viewer in [auth.anonymous] is a powerful lever for controlling the default permissions of unauthenticated users if you decide to expose certain dashboards publicly without strict login requirements, which can be a useful feature for public status pages or overview dashboards.
The next step is integrating these branded dashboards into your application, often using Grafana’s embedding features.