Data and monitoring · Intermediate · 25 min
How to Build Your First Grafana Dashboard from Prometheus Data
By Padding · Updated 16 Nov 2026
Ubuntu 26.04.1 LTS · Grafana 13.3.1 · Prometheus 3.16.0
You will install Grafana 13.3 from its apt repository on Ubuntu 26.04, set the admin password before the first start, keep it on localhost, connect it to Prometheus, and build a server overview dashboard with uptime, memory and CPU panels that lives in a file you can keep in Git.
On this page
Prometheus stores your server's numbers and answers queries, but its own page is a tool for asking questions, not for watching a system day after day. Grafana is the usual screen for that. It connects to a data source such as Prometheus, runs the queries you choose on a schedule, and draws the results as panels on a dashboard that you can leave open or share.
This tutorial installs Grafana from Grafana's own apt repository, so apt upgrade keeps it patched. You set the admin password before it starts for the first time, so the well-known default login admin / admin never exists. Grafana listens on 127.0.0.1, and you reach it through an SSH tunnel. Then you connect Prometheus and build a dashboard of three panels. The data source and the dashboard are written as files that Grafana loads at startup (Grafana calls this provisioning), so you can repeat the setup on another server or keep it under version control.
Step 1 · Check what Grafana will connect to
Grafana needs a running Prometheus. Confirm that yours answers and has scraped your server. The query up returns 1 for each target Prometheus can reach:
curl -s http://127.0.0.1:9090/api/v1/query --data-urlencode 'query=up{job="node"}' | jq -r '.data.result[0].value[1]'The output is 1. If it is empty or 0, go back to the Prometheus tutorial and fix that first.
Step 2 · Install Grafana
Add Grafana's package repository and its signing key, then install the open-source edition, the grafana package. The key lets apt check that packages come from Grafana. Grafana's installation page for Debian and Ubuntu, https://grafana.com/docs/grafana/latest/setup-grafana/installation/debian/, lists these steps:
sudo apt update
sudo apt install -y apt-transport-https wget gnupg
sudo mkdir -p /etc/apt/keyrings
sudo wget -O /etc/apt/keyrings/grafana.asc https://apt.grafana.com/gpg-full.key
sudo chmod 644 /etc/apt/keyrings/grafana.asc
echo "deb [signed-by=/etc/apt/keyrings/grafana.asc] https://apt.grafana.com stable main" | sudo tee /etc/apt/sources.list.d/grafana.list
sudo apt update
sudo apt install -y grafanaThe installer creates a grafana user, the folders under /etc/grafana and /var/lib/grafana, and a service called grafana-server. It does not start the service. The repository also carries grafana-enterprise, which is the same program with an Enterprise licence option; the open-source grafana is enough here.
Check it worked
apt-cache policy grafana | sed -n '1,3p'The Installed: line shows 13.3.1, or a later release.
Step 3 · Set the admin password and keep Grafana private
Grafana creates its first administrator, admin, the first time it starts. Its documented default password is admin, which it asks you to change at the first login, but a server that starts with a publicly known password has a window where anyone who reaches it can sign in. Set the password before the first start instead.
Read the password into a shell variable without echoing it. Then write it to a file that only root and the grafana group can read. The file is created with its final permissions first, and printf is a shell built-in, so the password is not shown in a process list:
read -rsp "Choose a Grafana admin password: " GF_PW; echosudo install -m 640 -o root -g grafana /dev/null /etc/grafana/admin_password
printf '%s' "$GF_PW" | sudo tee /etc/grafana/admin_password > /dev/null
sudo ls -l /etc/grafana/admin_passwordThe listing shows -rw-r----- with owner root and group grafana.
Now replace Grafana's configuration with a short file. The packaged grafana.ini is only a list of commented defaults, so keep a copy and write your own. $__file{...} makes Grafana read a value from a file, which keeps the secret out of the configuration. http_addr = 127.0.0.1 makes it listen on the loopback address only. The admin password is read only when Grafana creates its database, at the first start; later changes to it are made inside Grafana:
sudo cp /etc/grafana/grafana.ini /etc/grafana/grafana.ini.orig
sudo tee /etc/grafana/grafana.ini > /dev/null <<'INI'
[server]
http_addr = 127.0.0.1
http_port = 3000
[security]
admin_user = admin
admin_password = $__file{/etc/grafana/admin_password}
[analytics]
reporting_enabled = false
ININext, tell Grafana about Prometheus with a provisioning file. access: proxy means Grafana's server makes the queries, so your browser never needs to reach Prometheus. The uid is the name that dashboards use to refer to the data source:
sudo tee /etc/grafana/provisioning/datasources/prometheus.yaml > /dev/null <<'YAML'
apiVersion: 1
datasources:
- name: Prometheus
uid: prometheus
type: prometheus
access: proxy
url: http://127.0.0.1:9090
isDefault: true
editable: false
YAMLStart Grafana now, and at every boot:
sudo systemctl enable --now grafana-server
sudo systemctl status grafana-server --no-pagerThe status shows active (running). The first start takes several seconds, because Grafana builds its database.
Check it worked
The health address needs no login:
curl -s http://127.0.0.1:3000/api/healthThe output is a small JSON document with "database": "ok" and "version": "13.3.1". Then check that the listener is private and that the default password does not work. The second command sends the old default and expects a refusal. This is a test password and not a secret, so it is fine on the command line:
ss -tln | grep ':3000'
curl -s -o /dev/null -w '%{http_code}\n' -u admin:admin http://127.0.0.1:3000/api/orgThe address is 127.0.0.1:3000, and the second command prints 401.
Troubleshooting
- The service does not start, or
curlcannot connect: read the log withsudo journalctl -u grafana-server -n 30 --no-pager. A typo ingrafana.iniis reported there with its line. - You cannot log in with your password: the admin password is applied only when the database is first created. If Grafana ran before you wrote the file, reset it with
sudo grafana cli admin reset-admin-password --password-from-stdinand type the new password, then press Ctrl+D. Checkgrafana cli admin reset-admin-password --helpfor your version. - Port 3000 is already in use: change
http_port, and the tunnel command below, to a free port.
Step 4 · Sign in and check the data source
Grafana has a login page and no other protection, so reach it through an SSH tunnel and not through an open port. On your laptop, in a new terminal:
ssh -L 3000:127.0.0.1:3000 you@your-serverReplace you@your-server with your own login. Leave that session open, and browse to http://127.0.0.1:3000 on your laptop. Sign in as admin with the password you chose. The menu names below are how Grafana 13 labels things at the time of writing; they can differ slightly between releases, and the API check further down is the proof that matters. Under Connections, then Data sources, you see Prometheus. Open it and press Save and test. A green message says that it successfully queried the Prometheus API. If you ever want Grafana on a public address, put it behind a reverse proxy with HTTPS first, as in free HTTPS with Let's Encrypt and Nginx, and open only ports 80 and 443 in the firewall.
You can run the same test from the server. The HTTP API uses the same login. To keep the password off the command line, this helper passes it to curl on standard input as a config line:
gapi() {
printf 'user = "admin:%s"\n' "$GF_PW" | curl -s -K - "$@"
}
gapi http://127.0.0.1:3000/api/datasources/uid/prometheus/health | jq -r .messageThe output is Successfully queried the Prometheus API..
Step 5 · Build the dashboard as a file
A dashboard is a JSON document: a list of panels, each with a position, a visualisation type and queries. You can click one together in the browser, and the next step shows how, but a file is easier to review, copy to another server and restore. This one has three panels: Uptime as a single number, Memory available as a gauge, and CPU busy as a graph over time. Each runs a PromQL query from the Prometheus tutorial.
sudo install -d -m 0755 /etc/grafana/dashboards
sudo tee /etc/grafana/dashboards/server-overview.json > /dev/null <<'JSON'
{
"uid": "server-overview",
"title": "Server overview",
"tags": ["linux"],
"timezone": "browser",
"schemaVersion": 41,
"refresh": "30s",
"time": { "from": "now-1h", "to": "now" },
"panels": [
{
"id": 1,
"type": "stat",
"title": "Uptime",
"gridPos": { "h": 5, "w": 6, "x": 0, "y": 0 },
"datasource": { "type": "prometheus", "uid": "prometheus" },
"targets": [
{ "refId": "A", "expr": "time() - node_boot_time_seconds", "instant": true }
],
"fieldConfig": { "defaults": { "unit": "s" }, "overrides": [] }
},
{
"id": 2,
"type": "gauge",
"title": "Memory available",
"gridPos": { "h": 5, "w": 6, "x": 6, "y": 0 },
"datasource": { "type": "prometheus", "uid": "prometheus" },
"targets": [
{ "refId": "A", "expr": "100 * node_memory_MemAvailable_bytes / node_memory_MemTotal_bytes", "instant": true }
],
"fieldConfig": {
"defaults": {
"unit": "percent",
"min": 0,
"max": 100,
"thresholds": {
"mode": "absolute",
"steps": [
{ "color": "red", "value": null },
{ "color": "yellow", "value": 10 },
{ "color": "green", "value": 25 }
]
}
},
"overrides": []
}
},
{
"id": 3,
"type": "timeseries",
"title": "CPU busy",
"gridPos": { "h": 8, "w": 12, "x": 0, "y": 5 },
"datasource": { "type": "prometheus", "uid": "prometheus" },
"targets": [
{
"refId": "A",
"legendFormat": "all cores",
"expr": "100 * (1 - avg(rate(node_cpu_seconds_total{mode=\"idle\"}[$__rate_interval])))"
}
],
"fieldConfig": { "defaults": { "unit": "percent", "min": 0, "max": 100 }, "overrides": [] }
}
]
}
JSONschemaVersionrecords the dashboard file format. Grafana upgrades files that carry an older number when it loads them, so an export from your Grafana may show a higher one.- The
gridPosfields place each panel on a 24-column grid:wis the width in columns,hthe height,xandythe position. - The gauge's
thresholdscolour it red below 10 percent available memory, yellow below 25 and green above. $__rate_intervalis a Grafana variable that picks a sensible window forrate()from the zoom level and the scrape interval, so you do not hard-code[1m]. Grafana replaces it before sending the query to Prometheus."instant": trueasks for the latest value only, which is what single-number panels need.
Now a second provisioning file tells Grafana to load every JSON file in that folder. allowUiUpdates: true lets you save changes you make in the browser; without it, Grafana treats the files as read-only:
sudo tee /etc/grafana/provisioning/dashboards/server.yaml > /dev/null <<'YAML'
apiVersion: 1
providers:
- name: server
type: file
updateIntervalSeconds: 30
allowUiUpdates: true
options:
path: /etc/grafana/dashboards
YAMLGrafana reads provider files only at startup, so restart it. After that it re-reads the dashboard folder every 30 seconds:
sudo systemctl restart grafana-serverCheck it worked
Ask Grafana for the dashboard through its API:
gapi 'http://127.0.0.1:3000/api/dashboards/uid/server-overview' | jq -r '.dashboard.title, (.dashboard.panels[].title)'The output lists Server overview, Uptime, Memory available and CPU busy. In the browser, Dashboards now shows Server overview, and opening it draws the three panels with data.
Panels draw their data through Grafana's query API. Run the memory panel's query the way a browser would, and read back the number:
gapi -H 'Content-Type: application/json' -X POST http://127.0.0.1:3000/api/ds/query -d '{
"queries": [{
"refId": "A",
"datasource": { "type": "prometheus", "uid": "prometheus" },
"expr": "100 * node_memory_MemAvailable_bytes / node_memory_MemTotal_bytes",
"instant": true
}],
"from": "now-5m",
"to": "now"
}' | jq '.results.A.frames[0].data.values[1][0]'The output is one number between 0 and 100, the percentage of memory that programs can still use.
Step 6 · Change a panel in the browser
Provisioned files are your starting point. Most people then adjust the dashboard by hand. Button and menu names here may differ slightly in your Grafana version. In the browser, open Server overview, choose Edit at the top right, and hover over the CPU busy panel to open its menu and choose Edit. In the panel editor, the query is in the box under the data source. Change the legend, the unit (the right-hand options list has a Standard options section) or the query itself, and watch the preview. Use Back to dashboard and Save dashboard when you are done. The Grafana documentation for building a dashboard is https://grafana.com/docs/grafana/latest/dashboards/build-dashboards/create-dashboard/.
Dashboard edits are saved in Grafana's own database. To keep a copy in a file, use the dashboard's Export option, choose JSON, and replace the file in /etc/grafana/dashboards/. Grafana picks up the file change within 30 seconds, and the file is then the version you can put in Git and restore on a new server.
Step 7 · Plan for upgrades and backups
- Upgrades. Grafana comes from an apt repository, so
sudo apt update && sudo apt upgradeinstalls new releases, and the package is set to restart the service after an upgrade (RESTART_ON_UPGRADE=truein/etc/default/grafana-server). Check withsudo systemctl status grafana-serverafterwards. Read the release notes before a major version jump. - What to back up. Your configuration and provisioning files in
/etc/grafana, and the database in/var/lib/grafana/grafana.dbfor anything you built in the browser. The provisioned files you can recreate from this tutorial. - Security. Keep the admin account for setup, and create named users for people under Administration, Users and access. Sign-in over plain HTTP sends passwords in the clear, so any public address must use HTTPS.
Step 8 · Remove it
If this was a trial, remove Grafana, its data and the apt repository. purge deletes the configuration as well, including your files in /etc/grafana. This cannot be undone:
sudo systemctl disable --now grafana-server
sudo apt purge -y grafana
sudo rm -rf /var/lib/grafana /etc/grafana
sudo rm /etc/apt/sources.list.d/grafana.list /etc/apt/keyrings/grafana.asc
sudo apt updatePrometheus and Node Exporter from the earlier tutorial are separate and keep running. To remove them as well, use the last step of the Prometheus tutorial once you have finished the series.
Next steps
- Get a message when a number crosses a line: send alerts with Prometheus Alertmanager.
- Understand the numbers you are graphing: monitor a Linux server with Prometheus and Node Exporter.
- Put Grafana behind HTTPS: free HTTPS with Let's Encrypt and Nginx.
- Keep the server healthy underneath it: harden SSH on Ubuntu 26.04.
Related tutorials
- How to Run Your App as a systemd Service on Ubuntu 26.04You will write a systemd unit file that starts your app at boot, restarts it when it crashes, runs it as an unprivileged user, and sends its logs to the journal.
- How to Set Up a UFW Firewall on Ubuntu 26.04You will turn on UFW with a deny-by-default policy, allow SSH before you enable it so you stay connected, open only the web ports your server needs, and learn to list, remove and limit rules.
- How to Harden SSH on Ubuntu 26.04: Keys Only, No Root, Custom LimitsYou will switch an Ubuntu 26.04 server's SSH daemon to key-only logins, turn off root login, limit who can connect and how many guesses they get, and test the change without locking yourself out.
Need this done for you?
Padding does this work for growing companies, from the first diagnosis to a system that keeps working.
Get new tutorials