How to Display Grafana Dashboards on OptiSigns

In this article, we'll walk you through setting up Grafana to display on your OptiSigns digital signs.

• What You'll Need
• Which Setup Applies to You
• Create a Service Account in Grafana
  • Create the Service Account
  • Generate a Token
• Add a Grafana Connection in OptiSigns
  • If You Use Grafana Cloud
  • If You Self-Host Grafana
  • If Grafana Is on Your Own Network
  • If Grafana Is Behind a Firewall
  • If You Use a Public Dashboard Link
• Set Up Live Mode on Your Grafana
• Create a Grafana App in OptiSigns
  • Display Settings
  • Advanced Settings
  • About the Preview
• Deploying a Grafana App
  • How Updates Will Appear Onscreen
  • Which Players Are Supported
• Frequently Asked Questions
  • The connection test says Grafana rejected this token. What's wrong?
  • The connection test says Cloudflare or a firewall blocked our servers. What do I do?
  • OptiSigns says it can't reach my Grafana. Is that a problem?
  • My dashboard list is empty, or I can't find my dashboard. How can I make it appear?
  • OptiSigns won't accept the link I entered. Why?
  • The connection test tells me to install Grafana's image renderer. What do I do?
  • The connection test says embedding is disabled on my Grafana. How do I fix it?
  • My screen says Dashboard unavailable. What does that mean?
  • My screen shows Grafana's login page. Why?
  • My screen is showing an old picture, or says Data unavailable. Why?
  • The preview says it isn't available. Will my screens work?
  • My Grafana dashboard used to display fine, but stopped all of a sudden. What's wrong?

With the Grafana app, you can show a Grafana dashboard on any OptiSigns screen.

Once it is set up, the dashboard appears by itself. Nobody has to log in on the screen.

What You'll Need

• An OptiSigns account with a Pro Plus Plan or higher
• A Grafana instance, either Grafana Cloud or self-hosted
• Admin rights in Grafana
• A dashboard you want to display
• An OptiSigns-enabled device
• A screen, set up and paired with OptiSigns

Depending on your setup, you may also need a service-account token from Grafana. The next section tells you if you do.

Which Setup Applies to You

OptiSigns works out your setup from the Grafana URL you enter, so there's no need to pick one yourself.

If your setup needs a token, start with the next section. If it does not, skip ahead to Add a Grafana Connection in OptiSigns.

Create a Service Account in Grafana

A service account is what OptiSigns uses to read your dashboard. It is a machine identity that belongs to your Grafana, separate from any person's login, so nobody's password ever reaches a screen.

The Viewer role is all OptiSigns needs.

Create the Service Account

In Grafana, open Administration, then Users and access, then Service accounts.

Click Add service account.

Give it a Display name you will recognize later, set Role to Viewer, and click Create.

Generate a Token

Open the service account you just created and click Add service account token.

Give the token a Display name. Leave No expiration selected, or set an expiration date if your security policy requires one. Then click Generate token.

Copy the token and store it somewhere safe. You will paste it into OptiSigns in the next step.

Add a Grafana Connection in OptiSigns

Go to Integrations under your main menu, then click the Grafana tab and click Add Connection.

Fill in the first two fields:

• Name: the name of the connection as displayed in OptiSigns. It does not appear on your screen.
• Grafana URL: your Grafana's base URL, for example https://acme.grafana.net, or a public dashboard link. A link to a regular dashboard won't work here. You'll pick the dashboard later, on the app.

A line then appears under the URL that names your setup. For some addresses, "Checking where this Grafana runs…" shows for a few seconds first.

Follow the section that matches. If the line says our servers can't reach your Grafana, or mentions a login page, follow Grafana on Your Own Network.

If You Use Grafana Cloud

Paste your token into Service-account token (Viewer).

OptiSigns stores the token encrypted and uses it only on our servers. It is never sent to a screen.

The Connection test runs by itself once the URL and token are filled in. A successful test reads "Connection verified. Grafana (version), (number) dashboards." Below it you will see "Grafana Cloud manages the renderer. Nothing to set up."

Click Add to save the connection.

If You Self-Host Grafana

This is a Grafana you host yourself that our servers can reach from the internet.

Paste your token into Service-account token (Viewer). The Connection test runs by itself.

Under the result, one line tells you whether your Grafana is ready for Live mode:

Click Add to save the connection. You can save it whatever the test says.

If Your Grafana Is On Your Own Network

This is a Grafana our servers cannot reach: a private IP address such as 192.168.1.20, localhost, a short name such as grafana, a name ending in .local, .lan or .internal, or any address that only answers inside your network.

Your screens load the dashboard themselves, so they need to be on a network that can reach your Grafana.

You won't need a token here, and there's no connection test. Open the Set up Live mode on your Grafana block and follow Set Up Live Mode on Your Grafana, then click Add.

A few things to know:

• Use https:// where you can. The certificate needs to come from a public certificate authority, because screens won't load a self-signed one.
• http:// works on Android and Windows/Mac players. It isn't available in the Web Player, which is when you use a browser as your screen.
• A login page in front of Grafana. If the form says "A login page sits in front of this Grafana, so our servers can't reach it.", your screens can only load the dashboard if that login lets them through.
• A firewall instead of a private network. If the form says "Our servers can't reach this Grafana.", you can click Behind a firewall? Allow OptiSigns' IP. and follow the next section instead.

If Grafana Is Behind a Firewall

This is a Grafana on the internet that only accepts visitors it knows, for example behind Cloudflare Access, a Cloudflare rule, or a firewall allowlist.

You let our servers in by allowing OptiSigns' fixed IP address. Our servers then fetch a screenshot of your dashboard and send it to your screens.

You'll need:

• A Pro Plus or Engage plan. On other plans the form shows an Upgrade button instead.
• An https:// address on the standard port (443).
• Grafana's image renderer service installed, because screens show screenshots on this path.

When adding a Grafana Connection, you'll need to Allow our IP. The form shows the IP address with a copy button. Add it to your firewall or Cloudflare rule.

Paste your token into Service-account token (Viewer).

Read the test result. The test runs by itself.

Can't allow our IP? Under the test you will see "Can't allow our IP? Screens on an allowed network can load the dashboard directly." Open Set up Live mode on your Grafana there and follow Set Up Live Mode on Your Grafana. Your screens then load the dashboard themselves, so they need to be on a network your firewall allows.

If You Use a Public Dashboard Link

A public dashboard link needs no token and no setup in OptiSigns.

In Grafana, share the dashboard externally (older versions call this a public dashboard) and copy its link. See Grafana's guide to shared dashboards. The link contains /public-dashboards/.

Paste that link into Grafana URL, then click Add.

A few things to know:

• Keep in mind that anyone who has the link can see the dashboard.
• The time range, theme and filters are the ones saved on the public dashboard. To change them, edit the public dashboard in Grafana.
• Some public links open as a full page on the screen instead of inside the app: links on Grafana Cloud, links on your own network, and links where the test says "Its Grafana forbids framing, so screens will open it as a full page." These play on Android and Windows/Mac players, not in the Web Player.

Set Up Live Mode on Your Grafana

Live mode needs a one-time change to your Grafana configuration. This applies to self-hosted Grafana and Grafana on your own network.

OptiSigns generates the exact configuration for your account.

1. In the Grafana connection form, open Set up Live mode on your Grafana. To get back to it later, click Edit on the connection.
2. Pick the grafana.ini or Docker / Kubernetes tab to match how you run Grafana.
3. Click Copy.
4. Add it to your Grafana configuration and restart Grafana.
5. If your form has a connection test, click Re-test.

It turns on two things:

• JWT authentication, so your Grafana accepts a signed token from OptiSigns instead of a password. Your own Grafana logins are unaffected.
• Embedding, so the dashboard can load in the OptiSigns preview and in the Web Player.

After the first screen connects, you'll see a user named optisigns-signage in your Grafana. That's your OptiSigns screens signing in.

If you would rather show screenshots from a self-hosted Grafana, install Grafana's image renderer service. The bundled renderer plugin was removed in Grafana 13, so the standalone service is the only option on current versions. See Grafana's image rendering documentation. You can then switch the mode under Advanced on the app. This is not available for a Grafana on your own network, because our servers cannot reach it to take the screenshot.

Create a Grafana App in OptiSigns

Now that the connection exists, create the asset that your screens will play.

Open OptiSigns and go to Files/Assets → Apps → Grafana.

The app opens with a live preview on the right, so you can see what the screen will show as you fill in the form.

Under Connect:

• Name: the name of your Grafana app. This is for use in OptiSigns and does not appear on your screen.
• Grafana connection: choose one of your Grafana connections (or create a new one)

Under Dashboard, what you see depends on the connection:

• Dashboard: choose from the list of dashboards your service account can see. This is what most connections show.
• Dashboard link: for a Grafana on your own network, there is no list. Open the dashboard in Grafana and copy the link from your browser's address bar, then paste it here.
• For a public dashboard link, there is no dashboard to choose. The link is shown as Public dashboard URL.

• Single panel ID (optional): leave this blank to show the whole dashboard. Enter a panel's ID to show just that one panel, filling the screen. You can find the ID in Grafana's URL when you view a single panel.

Display Settings

Open the Display section to control how the dashboard looks.

• Time range: how far back the dashboard looks. Last 1 hour, Last 6 hours, Last 24 hours, or Last 7 days. The range always ends at the current moment.
• Theme: Dark or Light. Dark is usually the better choice on a wall-mounted screen.

In Image mode you will also see:

• Refresh interval: how often the screen fetches a fresh screenshot, in seconds. 
  • The minimum is 300 seconds (5 minutes), the maximum is 3600 seconds (1 hour), and the default is 600 seconds (10 minutes).
• Image quality: Standard or High (HiDPI). Use High for a 4K screen or when a panel's text looks soft.
• Show "as of" freshness stamp: adds a small timestamp so viewers can tell how current the data is.

Public dashboard links have no Display settings.

Advanced Settings

The Advanced section holds one setting most screens never need.

• Render mode: Image mode (works on Cloud) or Live mode (self-hosted). OptiSigns sets this from your connection. You'd only need to change it if the mode it chose doesn't work on a particular screen.

Click Save when you're done. The dialog stays open so you can keep adjusting. Click Close when you're finished.

About the Preview

• In Live mode and for public links, the preview updates as you fill in the form.
• In Image mode, the preview appears after you click Save for the first time.
• For a Grafana on your own network, or an http:// address, the preview may say Preview not available. Click Open in Browser from a computer on the same network, or push the app to a device to see it. Your screens can still show the dashboard.

Deploying a Grafana App

You can deploy your new Grafana app as an individual asset, or as part of a Split Screen.

To get your new Grafana asset to a screen, go to the Screens tab, then click Edit on the screen you want to assign it to.

This brings up the Edit Screen dialog:

Here, select Asset under Content Type. Or, if you already have an Asset displayed, you can hit Change.

Then select your created Grafana Asset.

Now hit Save. Your Grafana asset will now display on screen.

You can also deploy it as part of a split screen, allowing you to show other assets at the same time. See how in our Split Screen app article. It can also be displayed in a Playlist or Schedule.

How Updates Will Appear Onscreen

In Image mode, the screen fetches a fresh screenshot every refresh interval, so a change you make in Grafana appears within one interval. If a screenshot fails, the screen keeps showing the last good one rather than going blank. The "as of" stamp shows when that picture was taken.

In Live mode, the dashboard runs on the screen itself, so it updates on whatever refresh your Grafana dashboard is set to. About every 8 hours the screen reloads the dashboard, which shows a blank screen for a few seconds.

For Public dashboard links, the screen shows the public dashboard as Grafana serves it.

Which Players Are Supported

Frequently Asked Questions

Here, we'll answer some frequently asked questions our customers have, and solve some common troubleshooting issues.

The connection test says Grafana rejected this token. What's wrong?

The token is expired, has been revoked, or belongs to a different Grafana than the URL you entered. Generate a new service-account token in Grafana and update the connection. Also check that the Grafana URL points at the same instance the service account lives in.

The connection test says Cloudflare or a firewall blocked our servers. What do I do?

Something in front of your Grafana stopped our servers before Grafana saw the request, so we could not check your token. Follow Grafana Behind a Firewall to allow OptiSigns' fixed IP, then click Re-test.

OptiSigns says it can't reach my Grafana. Is that a problem?

Not necessarily. It means our servers could not open your Grafana from the internet, which is normal for a Grafana on a private network. Your screens can still load it on your own network.

If you expected it to be reachable, check the URL for typos and confirm the certificate is issued by a public certificate authority. A self-signed certificate will fail. Then enter the URL again.

My dashboard list is empty, or I can't find my dashboard. How can I make it appear?

There are three usual causes:

• The service account cannot see the dashboard. In Grafana, check that its role is Viewer and that it has permission to view the folder the dashboard lives in.
• Grafana Cloud is asleep. Open your Grafana in a browser once to wake it.
• The connection points at a different Grafana than the one the dashboard lives in.

Then close the app form and open it again, which reloads the list.

OptiSigns won't accept the link I entered. Why?

It depends on the field:

• Grafana URL (on the connection) takes the base URL of your Grafana, such as https://acme.grafana.net, or a public dashboard link. A link to a regular dashboard won't work there, so remove everything after the host name and try again.
• Dashboard link (on the app, for a Grafana on your own network) takes the link from your browser's address bar while the dashboard is open. Shortened links, snapshot links, playlist links and public dashboard links won't work there.

The connection test tells me to install Grafana's image renderer. What do I do?

Your screens will show screenshots, and your self-hosted Grafana has no image renderer to take them. Install and configure the image renderer service, then click Re-test. The bundled renderer plugin was removed in Grafana 13, so the standalone service is the only option on current versions.

The connection test says embedding is disabled on my Grafana. How do I fix it?

Your Grafana is telling browsers not to load it inside another page. Apply the block under Set up Live mode on your Grafana in the connection form, restart Grafana, and click Re-test.

If your Grafana also sends a Content-Security-Policy, its frame-ancestors setting has to allow embedding too.

Android and Windows/Mac players open the dashboard as a full page, so they can show it even while embedding is off. The OptiSigns preview and the Web Player need embedding.

My screen says Dashboard unavailable. What does that mean?

The screen could not load your Grafana. The usual causes are:

• The device cannot reach your Grafana. It may be down, its name may not resolve, or the screen's network may block it.
• Your Grafana's certificate is not from a public certificate authority.

The screen keeps retrying by itself.

My screen shows Grafana's login page. Why?

Your Grafana is not accepting OptiSigns' signed token yet. Check that you applied the whole block under Set up Live mode on your Grafana, that you restarted Grafana afterwards, and that your Grafana server can reach the internet address on the jwk_set_url line.

My screen is showing an old picture, or says Data unavailable. Why?

OptiSigns could not get a fresh screenshot from Grafana. If it has an earlier one, it keeps showing it, and the "as of" stamp tells you how old it is. If it never got one, the screen says Data unavailable.

Check that Grafana is up and that the service-account token has not expired or been revoked. If you use OptiSigns' fixed IP, also check that the IP is still allowed.

The preview says it isn't available. Will my screens work?

Usually yes. The preview runs in your browser, which often cannot reach a Grafana on a private network.

• In the app form, the preview says Preview not available. Click Open in Browser from a computer on the same network as your Grafana, or push the app to a device to check it.
• Elsewhere in OptiSigns, such as the Files/Assets and Screens pages, it says "Preview isn't available for this dashboard. Your screens can still show it."

If you see that second sentence in the Web Player, it isn't able to show this dashboard. See Which Players Are Supported.

My Grafana dashboard used to display fine, but stopped all of a sudden. What's wrong?

Check these first:

• The service-account token. If you set an expiration date when you created it, check whether that date has passed. Generate a new token in Grafana and update your OptiSigns connection.
• Your firewall or Cloudflare rule, if you use OptiSigns' fixed IP. Check that the rule still allows the IP and that your plan is still Pro Plus or Engage.
• Your Grafana configuration, if you use Live mode. An upgrade or a new deployment can drop the block you added under Set up Live mode on your Grafana.

That’s all!

OptiSigns is the leader in digital signage software. If you have any additional questions, concerns or any feedback about OptiSigns, feel free to reach out to our support team at support@optisigns.com.