Skip to content
Tutorials Center
My learning

Topics

Lesson 3 of 37 ยท Getting Started

Installing Grafana OSS

Install Grafana OSS with Docker, apt or yum on Linux, the Windows installer or Homebrew, start the service, open port 3000 and sign in for the first time.

Grafana is a single Go binary with a built-in web server, so installation is quick. There are several ways to do it; pick the one that matches your machine. For learning, Docker is the least messy because you can delete the container when you are done.

The commands below are real, but they run on your computer, not in the page. Check the official installation page for the latest version numbers before copying release-specific URLs.

Terminal
docker run -d --name grafana -p 3000:3000 grafana/grafana-oss
  • -d runs it in the background, --name gives the container a name.
  • -p 3000:3000 maps port 3000 of your machine to Grafana's port.
  • The image is grafana/grafana-oss; add a tag such as :12.0.0 to pin a version (always pin in production).

To keep dashboards after the container is deleted, store data in a volume:

Terminal
docker volume create grafana-data
docker run -d --name grafana -p 3000:3000 -v grafana-data:/var/lib/grafana grafana/grafana-oss

Useful follow-ups: docker logs grafana, docker stop grafana, docker start grafana, docker rm -f grafana.

Option 2: Debian or Ubuntu (apt)

Grafana Labs publishes an apt repository. The usual steps are: add the repository signing key and source list, then install.

Terminal
sudo apt-get update
sudo apt-get install -y grafana
sudo systemctl daemon-reload
sudo systemctl enable --now grafana-server
sudo systemctl status grafana-server

(Adding the repository first is described on the official install page.) On Red Hat, Fedora or Rocky Linux the equivalent is a yum/dnf repository plus sudo dnf install grafana.

Important paths on Linux packages:

Path Purpose
/etc/grafana/grafana.ini Main configuration
/var/lib/grafana SQLite database, plugins
/var/log/grafana Logs
/etc/grafana/provisioning Provisioning files (chapter 8)

Option 3: Windows

Download the Windows installer (.msi) from the Grafana download page and run it. It installs Grafana, a Windows service and a default configuration under C:\Program Files\GrafanaLabs\grafana. You can also download the standalone .zip, extract it and run bin\grafana-server.exe (or grafana.exe server) from a terminal. Allow the firewall prompt if you want other machines to connect.

Option 4: macOS

With Homebrew:

Terminal
brew update
brew install grafana
brew services start grafana

First sign-in

Open http://localhost:3000 in a browser. The default credentials for a fresh install are user admin, password admin. Grafana then asks you to choose a new password. Do this immediately. If the server is reachable by others, never leave the default.

If you forget the admin password on a package install you can reset it from the command line: grafana cli admin reset-admin-password <new password> (in Docker run it with docker exec).

Checking that it is alive

Grafana exposes a health endpoint that returns JSON with the database status and version. This stand-in shows how a script would check the response; it parses a sample body so it runs here.

JS Stand-in: reading a health response

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Choosing a version

Grafana releases a new major version roughly yearly and minor versions every few months. Dashboards created in older versions are upgraded automatically on load. Before an upgrade: back up grafana.db (or your external database), read the release notes for breaking changes, upgrade a test instance first.

Port conflicts and a quick checker

If port 3000 is taken, map another host port (-p 3001:3000) or change http_port in the configuration. The next stand-in builds the URL you would open from a few settings, which is handy when you run behind a sub-path.

JS Stand-in: build the Grafana URL

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Troubleshooting

  • Page does not load: is the container or service running? Check logs. Is the firewall blocking 3000?
  • Login keeps failing: you may have changed the password earlier; use the reset command.
  • Data disappears after restarting Docker: you forgot the volume.
  • Behind a reverse proxy: set root_url (and serve_from_sub_path if needed) in the configuration, see configuration.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which port does Grafana listen on by default?

    Grafana serves its UI on port 3000. 9090 is Prometheus.
  2. 2. What is the default first login on a fresh install?

    The default admin user has password admin, and Grafana asks you to change it.
  3. 3. Why mount a volume at /var/lib/grafana in Docker?

    Grafana stores its SQLite database in that folder; without a volume it is lost with the container.
  4. 4. Where is the main config file on a Linux package install?

    The package puts grafana.ini in /etc/grafana.

Summary

  • Docker is the fastest way to try Grafana; use a volume to keep data.
  • Packages exist for apt, yum, Windows and Homebrew.
  • Open port 3000 and sign in with admin/admin, then change the password.
  • Know the config, data and log paths.
  • Pin versions and back up before upgrading.

Next: First Login and a Tour of the Interface