Skip to main content

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:

Bash
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:

Bash
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 grafana

The 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

Bash
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:

Bash
read -rsp "Choose a Grafana admin password: " GF_PW; echo
Bash
sudo 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_password

The 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:

Bash
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
INI

Next, 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:

Bash
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
YAML

Start Grafana now, and at every boot:

Bash
sudo systemctl enable --now grafana-server
sudo systemctl status grafana-server --no-pager

The status shows active (running). The first start takes several seconds, because Grafana builds its database.

Check it worked

The health address needs no login:

Bash
curl -s http://127.0.0.1:3000/api/health

The 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:

Bash
ss -tln | grep ':3000'
curl -s -o /dev/null -w '%{http_code}\n' -u admin:admin http://127.0.0.1:3000/api/org

The address is 127.0.0.1:3000, and the second command prints 401.

Troubleshooting

  • The service does not start, or curl cannot connect: read the log with sudo journalctl -u grafana-server -n 30 --no-pager. A typo in grafana.ini is 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-stdin and type the new password, then press Ctrl+D. Check grafana cli admin reset-admin-password --help for 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:

Bash
ssh -L 3000:127.0.0.1:3000 you@your-server

Replace 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:

Bash
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 .message

The 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.

Bash
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": [] }
    }
  ]
}
JSON
  • schemaVersion records 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 gridPos fields place each panel on a 24-column grid: w is the width in columns, h the height, x and y the position.
  • The gauge's thresholds colour it red below 10 percent available memory, yellow below 25 and green above.
  • $__rate_interval is a Grafana variable that picks a sensible window for rate() 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": true asks 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:

Bash
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
YAML

Grafana reads provider files only at startup, so restart it. After that it re-reads the dashboard folder every 30 seconds:

Bash
sudo systemctl restart grafana-server

Check it worked

Ask Grafana for the dashboard through its API:

Bash
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:

Bash
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 upgrade installs new releases, and the package is set to restart the service after an upgrade (RESTART_ON_UPGRADE=true in /etc/default/grafana-server). Check with sudo systemctl status grafana-server afterwards. 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.db for 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:

Bash
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 update

Prometheus 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

Need this done for you?

Padding does this work for growing companies, from the first diagnosis to a system that keeps working.

Platform Engineering

Get new tutorials

New tutorials, about twice a month.