Grafana is an open-source data visualization and monitoring tool that integrates with complex data from sources like Prometheus, InfluxDB, Graphite, and ElasticSearch.
Grafana create alerts, notifications, and ad-hoc filters for your data while also making collaboration with your teammates easier through built-in sharing features.
Prerequisites
To follow this tutorial, you will need:
- One Ubuntu 22.04 server
- A fully registered domain name here we use
your_domain
. - A record with
your_domain
pointing to your server’s public IP address. - A record with
www.your_domain
pointing to your server’s public IP address. - Nginx set up
- Optionally, to set up GitHub authentication, you’ll need a GitHub account associated with an organization.
Step 1 — Installing Grafana
You can install Grafana either by downloading it directly from its official website or by using below list of command from this tutorial:
sudo wget -q -O - https://packages.grafana.com/gpg.key | gpg --dearmor | sudo tee /usr/share/keyrings/grafana.gpg > /dev/null
Now add Grafana repository to your APT sources.
echo "deb [signed-by=/usr/share/keyrings/grafana.gpg] https://packages.grafana.com/oss/deb stable main" | sudo tee -a /etc/apt/sources.list.d/grafana.list
sudo apt update
sudo apt install grafana
sudo systemctl start grafana-server
sudo systemctl status grafana-server
Output
● grafana-server.service - Grafana instance
Loaded: loaded (/lib/systemd/system/grafana-server.service; disabled; vendor preset: enabled)
Active: active (running) since Tue 2022-09-27 14:42:15 UTC; 6s ago
Docs: http://docs.grafana.org
Main PID: 4132 (grafana-server)
Tasks: 7 (limit: 515)
...
Now enable the service to automatically start Grafana on boot.
sudo systemctl enable grafana-server
Grafana is now installed and ready for use
Step 2 — Setting Up the Reverse Proxy
Using an SSL certificate will ensure that your data is secure by encrypting the connection to and from Grafana. We will first need to reconfigure Nginx as a reverse proxy for Grafana.
sudo nano /etc/nginx/sites-available/your_domain
/etc/nginx/sites-available/your_domain
...
location / {
proxy_set_header Host $http_host;
proxy_pass http://localhost:3000;
}
...
This will map the proxy to the appropriate port and will pass a server name in the header.
Also, in order for the Grafana Live WebSocket connections to work correctly, add the following section outside the server
section:
/etc/nginx/sites-available/your_domain
server {
...
location /api/live {
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $connection_upgrade;
proxy_set_header Host $http_host;
proxy_pass http://localhost:3000;
}
...
The final configuration look like this
/etc/nginx/sites-available/your_domain
map $http_upgrade $connection_upgrade {
default upgrade;
'' close;
}
server {
...
root /var/www/your_domain/html;
index index.html index.htm index.nginx-debian.html;
server_name your_domain www.your_domain;
location / {
proxy_set_header Host $http_host;
proxy_pass http://localhost:3000;
}
location /api/live {
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $connection_upgrade;
proxy_set_header Host $http_host;
proxy_pass http://localhost:3000;
}
...
}
Now, test the new settings
sudo nginx -t
Output
nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful
Now reload NGINX
sudo systemctl reload nginx
You can now access the default Grafana login screen by pointing your web browser to https://your_domain
. If you’re unable to reach Grafana, verify that your firewall is set to allow traffic on port 443
and then re-trace the previous instructions.
Step 3 Credentials
The best practice to change your login information as soon as possible.
Enter admin
into both the Email or username and Password fields and then click on the Log in button.
Next screen change the default password:
Step 5 — Setting Up a GitHub App (OAuth)
For an alternative approach to signing in, you can configure Grafana to authenticate through GitHub, which provides login access to all members of authorized GitHub organization. Start by logging in to a GitHub account associated with your organization and then navigate to your GitHub profile page.
On the next screen, you’ll see your Organization profile where you can change settings like your Organization display name, organization Email, and organization URL.
Because Grafana uses OAuth—an open standard for granting remote third parties access to local resources—to authenticate users through GitHub, you’ll need to create a new OAuth application within GitHub. Click the Register an application button to continue.
- Application name: This helps you distinguish your different OAuth applications from one another.
- Homepage URL: This tells GitHub where to find Grafana. Type
https://your_domain
into this field, replacingyour_domain
with your domain. - Application Description: This provides a description of your OAuth application’s purpose.
- Application callback URL: This is the address where users will be sent once successfully authenticated. For Grafana, this field must be set to
https://your_domain/login/github
Now it is redirected to a page of new OAuth application, including the Client ID.
Click the Generate a new client secret button to obtain new Client Secret. Make note of both values, because you will need to add them to Grafana’s main configuration file to complete the setup
Step 6 — Configuring Grafana as a GitHub (OAuth)
To complete GitHub authentication for your Grafana setup, you will now make some changes to your Grafana configuration files.
sudo nano /etc/grafana/grafana.ini
Locate the [auth.github]
heading, and uncomment this section by removing the ;
at the beginning of every line except the following.
;allowed_domains =
;team_ids =
;role_attribute_path =
;role_attribute_strict = false
;allow_assign_grafana_admin = false
Next, make the following changes:
- Set
enabled
andallow_sign_up
totrue
. This will enable GitHub Authentication and permit members of the allowed organization to create accounts themselves. Note that this setting is different from theallow_sign_up
property under[users]
that you changed in Step 4. - Set
client_id
andclient_secret
to the values you got while creating your GitHub OAuth application. - Set
allowed_organizations
to the name of your organization to ensure that only members of your organization can sign up and log in to Grafana
/etc/grafana/grafana.ini
...
[auth.github]
enabled = true
allow_sign_up = true
client_id = your_client_id_from_github
client_secret = your_client_secret_from_github
scopes = user:email,read:org
auth_url = https://github.com/login/oauth/authorize
token_url = https://github.com/login/oauth/access_token
api_url = https://api.github.com/user
;allowed_domains =
;team_ids =
allowed_organizations = your_organization_name
;role_attribute_path =
;role_attribute_strict = false
;allow_assign_grafana_admin = false
...
To complete the setup, you’ll need to enable redirects behind a reverse proxy.
This is done by setting a root_url
value under the [server]
heading.
/etc/grafana/grafana.ini
...
[server]
root_url = https://your_domain
...
Then, restart Grafana to activate the changes:
sudo systemctl restart grafana-server
Verify that the service is up and running:
sudo systemctl status grafana-server
Now we can test new authentication system by navigating to https://your_domain
in Grafana.
Click on the Sign in with GitHub button to be redirected to GitHub, where you’ll sign in to your GitHub account and confirm your intention to Authorize Grafana. Click the green Authorize your_github_organization button
To change the default permissions for new users, open the main Grafana configuration file for editing.
sudo nano /etc/grafana/grafana.ini
Set the directive to one of the following values:
- Locate the
auto_assign_org_role
Viewer
: can only use existing dashboards.Editor
: can use, modify, and add dashboards.Admin
: has permission to do everything.
/etc/grafana/grafana.ini
...
[users]
...
auto_assign_org_role = Viewer
...
Once you’ve saved, close the file and restart Grafana:
sudo systemctl restart grafana-server
Verify Status of Grafana
sudo systemctl status grafana-server
Finale
Now we have installed, configured, and secured Grafana, and also learned how to permit members of your organization to authenticate through GitHub.