Install and whitelabel Grafana with a custom grafana_icon.svg and a few other minor changes

Grafana is an amazing application, one of the most active open source projects in the world, and they are firmly committed to the Free Software / Open Source way of doing things. You should know up front that the following information enables a feature (whitelabel) which is part of the Enterprise edition from Grafana Labs. So in the spirit of being thankful for the hard work Grafana Labs has done to make this software available for free, please only use the following information for small, private installations. If you can at all afford to use the Enterprise edition -- which has many other excellent features you want -- please do so. But for those of us who have no money to spare, here is how you can whitelabel Grafana.

The dashboard elements inside Grafana can be customized as well, of course, to conclude the whitelabeling.

Quick Install into Ubuntu

First, let's get it installed. These days, installing Grafana in Debian/Ubuntu/etc is extremely easy:

sudo apt install grafana

Grafana defaults to using the lightweight Sqlite database, but for those who prefer MariaDB/MySQL, you can setup the database with the following 4 lines of MYSQL (this assumes you already did "apt install mariadb-server" first, of course, then "mysql_secure_installation" and "mysql -u root -p" as usual when setting up mysql. If not, do those now.):

CREATE DATABASE grafana_db;
GRANT ALL PRIVILEGES ON grafana_db.* TO grafana_admin@localhost IDENTIFIED BY "Scribbeldy!Wonk#$";
FLUSH PRIVILEGES;
QUIT;

Then edit the Grafana config, locate the ';url' entry, and add the following line referring to the mysql database you just created:

sudo nano /etc/grafana/grafana.ini # need to have nano editor installed for this to work
url =mysql://grafana_admin:Scribbeldy!Wonk#$@localhost:3306/grafana_db

Note that Grafana does not default in a started state, as do many applications installed using apt install. Instead, you will either need to reboot the server, or manually start it with a command like this (or the systemctl equivalent):

sudo service grafana-server start

At that point, you could visit the URL that is now live, login with admin/admin, and go to town with the default Grafana install. BUT WAIT. If you do that, you'll put images and files into your browser cache and spend hours wondering why in tarnation the following changes don't work.

So rather than do that, let's shutdown the server in order to make the following changes:

sudo service grafana-server stop

Now you're ready to whitelabel.

Whitelabeling by replacing image files -- yes, it's a hack

The Enterprise version very neatly does whitelabeling with configuration options. You will hackily replace some or all of these image files, and update text in a few others:

/usr/share/grafana/public/img/grafana_icon.svg
/usr/share/grafana/public/img/fav32.png
/usr/share/grafana/public/img/login_background_dark.svg # optional
/usr/share/grafana/public/img/login_background_light.svg # optional

You can also update the following other favicon files mentioned in index.html, using the same techniques described in this how-to, but they are only mentioned here, not described in detail:

<link rel="apple-touch-icon" sizes="180x180" href="https://www.clearhat.org/post/[[.AppleTouchIcon]]" />
<link rel="mask-icon" href="https://www.clearhat.org/post/public/img/grafana_mask_icon.svg" color="#F05A28" />

Now we're ready to replace. First, make a backup of the main logo, the grafana_icon.svg file, in case you want to revert your changes at any point:

sudo mv /usr/share/grafana/public/img/grafana_icon.svg /tmp

Then pull down your replacement .svg file, from wherever you have it located online. You can optionally use FTP to push the file into the correct location:

sudo wget https://clearhat.org/logo_gold_shield_on_transparent_square.svg
sudo cp logo_gold_shield_on_transparent_square.svg /usr/share/grafana/public/img/grafana_icon.svg

Now do the same with the fav32.png:

sudo mv /usr/share/grafana/public/img/fav32.png /tmp
sudo wget https://clearhat.org/favicon-32x32.png
sudo cp favicon-32x32.png /usr/share/grafana/public/img/fav32.png

And the optional background files if you want to change them out:

sudo mv /usr/share/grafana/public/img/login_background_dark.svg /tmp
sudo wget https://clearhat.org/new_login_background_dark.svg
sudo cp new_login_background_dark.svg /usr/share/grafana/public/img/login_background_dark.svg

sudo mv /usr/share/grafana/public/img/login_background_light.svg /tmp
sudo wget https://clearhat.org/new_login_background_light.svg
sudo cp new_login_background_light.svg /usr/share/grafana/public/img/login_background_light.svg

From what I could tell, the Branding component does not seem to be used with the normal open source distribution. Also, the following mentions in various files do not seem to be used:

u.AppTitle="Grafana"
u.LoginTitle="Welcome to Grafana"
document.title v.a.AppTitle

The four snippets that rotate during login can be changed using the sed s//g technique described below; just search for the following text and replace it (quotes included): "Don't get in the way of the data","Your single pane of glass","Built better together","Democratising data"

Now we're going to replace text using sed. You're going to replace the following text in the DashboardPage.****.js file:

document.title=r.title+" - "+f.a.AppTitle

Do not try to edit this file using nano. The source compilation process for Grafana creates an extremely difficult to manage file which is all one long string of text, hard to navigate with a text editor. Instead, use the command line to make your replacement:

You will also replace the following text in the app.****.js file:

Welcome to Grafana

And lastly, in the index.html itself, you'll replace the following:

[[.AppTitle]]

Before you make these changes, change your path:

cd /usr/share/grafana/public/build

Then run these 3 commands (after you come up with a better name than MyAwesomeDashboard):

sudo sed -i 's/"Welcome to Grafana"/"Welcome to MyAwesomeDashboard"/g' `ls|grep ^app.*.js$`
sudo sed -i 's/document\.title=r\.title+" - "+f\.a\.AppTitle/document\.title=r\.title+" - MyAwesomeDashboard"/g' `ls|grep ^DashboardPage.****.js$`
sudo sed -i 's/\[\[\.AppTitle\]\]/MyAwesomeDashboard/g' /usr/share/grafana/public/views/index.html

To briefly explain using the first line as an example: Sed will replace "Welcome to Grafana" with "Welcome to MyAwesomeDashboard" in the file app.****.js. We have to use the funky ls|grep tactic to get around the fact that Grafana inserts the build number into their filenames. The backward-tick marks tell the command shell to execute whatever is inside the backward-ticks, which transforms that ls command into the correct filename. Note this works as long as you're sitting in the /build directory as described earlier, otherwise you need to change the paths a little.

That's it. You should be ready to start or restart your Grafana instance, and have a custom entrance.

sudo service grafana-server restart

Enjoy.

For those who want to dig deeper, here are a couple useful urls:

https://unix.stackexchange.com/questions/32907/what-characters-do-i-need-to-escape-when-using-sed-in-a-sh-script
https://mohitshrestha02.medium.com/grafana-103-customizing-login-screen-for-grafana-playing-with-white-labels-and-many-more-1d63c23a138c Many thanks to Mohit for cracking the code on this style of whitelabeling for an earlier version of Grafana. I'm sure someone else will do the same for this version in the future, as the front page will continue to change over time.

Clearhat