Grafana on a Mac: the dashboard always in the same place

Searching for Grafana on a Mac covers two problems that have nothing to do with each other. The first is getting a server running locally, which Grafana Labs documents well and which takes about two minutes on Homebrew. The second arrives a week later: the dashboard is a website, it lives in a browser tab, and the tab keeps getting lost behind everything else. Grafana ships no desktop client, so nobody is coming to fix the second problem. It is solvable anyway, and the solution is different depending on whether one Grafana is in play or three.

Two ways to run the server locally

Grafana Labs documents both routes on the same page. Homebrew is the short one.

brew update
brew install grafana
brew services start grafana

The documentation notes where the files land, and the two paths differ by chip: /usr/local/Cellar/grafana/[version] on Intel Macs and /opt/homebrew/Cellar/grafana/[version] on Apple silicon. That distinction matters later, because every Grafana CLI command on a Homebrew install needs those paths spelled out.

The other route is the standalone binaries. The download page offers a Mac build per version and edition, Enterprise or Open Source, and the documentation is explicit that the two are functionally identical, with Enterprise carrying features that a licence unlocks. After untarring the archive, the server starts from inside the directory.

./bin/grafana server

The download page has two choices on it that trip people up. The version field lists tagged releases only, with nightly builds behind a separate link, so anyone who thinks a needed fix is missing should check whether it has actually shipped. The edition choice between Enterprise and Open Source looks weightier than it is: the documentation states they are functionally identical, and the Enterprise download is the one to take if licensed features might be switched on later.

Which route to pick comes down to whether the machine should keep Grafana running. brew services registers it so it survives a restart. The standalone binary runs while the terminal window that started it is alive, which is fine for an afternoon of testing and annoying as a habit.

One extra note for anyone who has to reset a password on a Homebrew install, because the command is longer than expected. Grafana's own documentation gives the full form, appending the config file, the home path and a data path override before the admin subcommand. Copying it from the documentation rather than typing it from memory saves a frustrating ten minutes.

First login, and the port that is probably taken

The sign in step is documented in one place and worth reading before guessing.

Unless you have configured Grafana differently, it is set to use http://localhost:3000 by default. On the signin page, enter admin for username and password. Source: grafana.com

Grafana prompts for a new password immediately after that first sign in, and the documentation recommends changing it. On a laptop that is easy to wave off. It is worth doing anyway, because a local Grafana with default credentials is reachable by anything else running on the machine.

Port 3000 is the real friction on a developer's Mac. It is Grafana's default, and it is also the default for a long list of other tools, so the first symptom is often a dashboard that will not load because something else answered first. The port is a configuration setting rather than a fixed value.

The port to bind to, defaults to 3000. Source: grafana.com

Changing http_port in grafana.ini moves it. The configuration file for a Homebrew install sits under the Homebrew prefix, at /opt/homebrew/etc/grafana/grafana.ini on Apple silicon. Anyone who runs several local services should pick a port deliberately and write it down, because a dashboard bookmarked at the wrong port produces a connection error that looks like a broken install.

That decision also affects the window question below. A web app remembers the URL it was created with, so moving Grafana to a different port after building the app means editing the app, not just a bookmark.

Or skip the server and use the hosted version

Grafana Labs puts a note at the top of the macOS installation page pointing at the hosted option, and it states the free tier in concrete terms rather than vaguely: free forever access to 10,000 metrics, 50GB of logs, 50GB of traces and 500 virtual user hours of k6 testing.

For a lot of Mac users, that removes the installation question entirely. Someone evaluating Grafana, building dashboards against a cloud database, or learning the query language has no reason to run a server on a laptop. Someone whose data sources are local, or who needs to work on a plane, does.

Either way the interface is the same web application, so everything below applies to both. The difference is only which URL the window opens, and one consequence of that is worth stating plainly: a hosted Grafana sits behind whatever single sign on the organisation uses, while a local one sits behind a local password. Those two kinds of session behave differently when a browser decides to clear cookies, which is the first reason a separate window per instance turns out to be practical rather than decorative.

The dashboard is a web application, and Grafana is designed around that

Grafana's own feature set assumes a browser window that gets out of the way, which is a strong hint about how it should be run day to day.

Kiosk mode is the clearest example. The documentation describes it directly.

In kiosk mode, the main menu and top navigation bar of a dashboard are hidden. This can be useful if you want to display as much information as possible on the screen or use the dashboard to present information to a wider audience. Source: grafana.com

It is reached from the user icon, toggled with d+k, and left with Esc. Grafana is removing its own interface chrome so that the panels get the screen. Doing that inside a browser tab is only half the job, because the tab strip, the bookmarks bar and the address bar are still there above it.

The keyboard shortcut list points the same way. Grafana binds single keys and modifier combinations across the dashboard: f opens the dashboard finder, d+s opens dashboard settings, d+e expands all rows, Ctrl+S saves, Ctrl+K opens the command palette, e edits a hovered panel, v shows it full screen, and ? lists everything the installed version supports. A browser binds some of the same combinations for its own menus, and the browser wins. Removing the browser interface removes the collision.

That is the whole argument for a dedicated window, and it is made by Grafana's documentation rather than by anyone selling software.

The routes for the dashboard window, side by side

Route	Setup	Own Dock icon	Separate session per instance	Survives a browser restart
Browser tab	None	No	No, shares the browser session	Only as part of a session restore
Safari, Add to Dock	Two clicks in Safari	Yes	Yes, own cookie store	Yes
Chrome, Install page as app	Two clicks in Chrome	Yes	No, inherits the Chrome profile	Needs Chrome running
Site to app tool	Paste the URL	Yes	Yes, own profile per app	Yes

Apple documents the Safari route in the Safari User Guide, and it costs nothing.

You can open and use a website as if it's an app. Go to the Safari app on your Mac. Go to a website. Click in the toolbar, then choose Add to Dock. Click Add. An icon for the web app is added to the Dock and Spotlight Applications. Source: support.apple.com

Apple's General settings page for web apps allows setting the application name, the URL, the icon, and whether navigation controls appear in the toolbar. For a dashboard, turning the navigation controls off is the point: with kiosk mode on inside Grafana and the toolbar controls off outside it, the window is panels and nothing else.

Chrome's route is under the three dot menu, in Cast, save, and share, then Install page as app. It works, and it ties the result to the Chrome profile it came from, which matters in the next section.

Three Grafanas, three logins

This is where the choice of route stops being cosmetic, and it is the situation most engineers are actually in.

A typical setup has a local Grafana on localhost for development, a company instance behind single sign on, and sometimes a hosted Grafana Cloud stack for a different team or a customer. Three URLs, three sessions, three identities. In one browser profile, a single sign on session and a local admin session coexist awkwardly at best, and any of them can be the one that a saved bookmark lands in.

Three separate applications with three separate cookie stores removes the problem rather than managing it. Each icon opens one Grafana, already signed in as the right identity, and none of them can log another one out. A tool that turns a website into a standalone Mac app assigns each app its own browser profile for this reason, so cookies and sessions do not cross between them. The Features page describes how that isolation is arranged.

The same trick covers the staging and production pair that catches people out. Two Grafana instances that look identical are the setup most likely to produce a change applied to the wrong one. Two visually distinct icons, each locked to one URL, is a cheap safeguard. Custom icons exist for exactly this kind of labelling, and the Guide covers setting them.

Leaving a dashboard up all day

Once the window exists, three settings turn it into something genuinely useful rather than a tidier tab.

Start it with the machine. Adding the application to the login items in System Settings means the dashboard is already loaded before the first meeting. For an on call rotation this is the difference between glancing at a screen and reconstructing a workspace.

Match the refresh to the data. Grafana's dashboard time controls handle relative ranges and auto refresh, and a window left open for eight hours with no refresh is a screenshot pretending to be a monitor. Setting the range and the refresh once, then saving the dashboard, makes the window trustworthy.

Give it a second display if one exists. A dashboard is the ideal occupant of a secondary monitor precisely because it needs no interaction. In a browser tab that is impossible without giving up a whole browser window. As its own application it is natural, and macOS remembers which display it was on.

One caveat belongs here. A local Grafana started from a terminal stops when the terminal does, so a dashboard window pointed at it will show a connection error after a reboot. If the dashboard is meant to be always available, the server needs to be registered as a service rather than run by hand.

What to change first

Install with brew install grafana, start it with brew services start grafana, change the admin password at the first sign in, and decide the port deliberately if anything else on the machine wants 3000. Then take the dashboard out of the tab strip: turn on Grafana's kiosk mode and give the URL its own window. For one instance Safari's Add to Dock is enough, and for a local, a staging and a production Grafana that each need their own session, set up three separate apps with Kagemusha.