Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/grafana/grafana-kiosk

Kiosk Utility for Grafana
https://github.com/grafana/grafana-kiosk

Last synced: 5 days ago
JSON representation

Kiosk Utility for Grafana

Awesome Lists containing this project

README 

        
# Grafana Kiosk



[![Build Status](https://img.shields.io/endpoint.svg?url=https%3A%2F%2Factions-badge.atrox.dev%2Fgrafana%2Fgrafana-kiosk%2Fbadge%3Fref%3Dmain&style=flat)](https://actions-badge.atrox.dev/grafana/grafana-kiosk/goto?ref=main)

[![Go Report Card](https://goreportcard.com/badge/github.com/grafana/grafana-kiosk)](https://goreportcard.com/report/github.com/grafana/grafana-kiosk)

[![Maintainability](https://api.codeclimate.com/v1/badges/8cdc385a20fe3d480455/maintainability)](https://codeclimate.com/github/grafana/grafana-kiosk/maintainability)

[![Test Coverage](https://api.codeclimate.com/v1/badges/8cdc385a20fe3d480455/test_coverage)](https://codeclimate.com/github/grafana/grafana-kiosk/test_coverage)



A very useful feature of Grafana is the ability to display dashboards and playlists on a large TV.



This provides a utility to quickly standup a kiosk on devices like a Raspberry Pi or NUC.



The utility provides these options:



- Login

  - to a Grafana server (local account or bypass OAuth)

  - to a Grafana server with anonymous-mode enabled (same method used on [play.grafana.org](https://play.grafana.org))

  - to a Grafana Cloud instance

  - to a Grafana server with OAuth enabled

  - to an AWS Managed Grafana instance (both with and without MFA)

- Switch to kiosk or kiosk-tv mode

- Display the default home page set for the user

- Display a specified dashboard

- Start a playlist immediately (inactive mode enable)

- Can specify where to start kiosk for multiple displays



Additionally, an initialize option is provided to configure LXDE for Raspberry Pi Desktop.



## Installing on Linux



Download the zip or tar file from [releases](https://github.com/grafana/grafana-kiosk/releases)



The release file includes pre-built binaries. See table below for the types available.



| OS      | Architecture | Description  | Executable                      |

| ------- | ------------ | ------------ | ------------------------------- |

| linux   | amd64        | 64bit        | grafana-kiosk.linux.amd64       |

| linux   | 386          | 32bit        | grafana-kiosk.linux.386         |

| linux   | arm64        | 64bit Arm v7 | grafana-kiosk.linux.arm64       |

| linux   | arm          | ARM v5       | grafana-kiosk.linux.armv5       |

| linux   | arm          | ARM v6       | grafana-kiosk.linux.armv6       |

| linux   | arm          | ARM v7       | grafana-kiosk.linux.armv7       |

| darwin  | amd64        | 64bit        | grafana-kiosk.darwin.amd64      |

| windows | amd64        | 64bit        | grafana-kiosk.windows.amd64.exe |



Extract the zip or tar file, and copy the appropriate binary to /usr/bin/grafana-kiosk:



```BASH

# sudo cp -p grafana-kiosk.linux.armv7 /usr/bin/grafana-kiosk

# sudo chmod 755 /usr/bin/grafana-kiosk

```



## Dependencies/Suggestion Packages



This application can run on most operating systems, but for linux some additional

binaries are suggested for full support.



Suggesting Packages:



`unclutter` (for hiding mouse/cursor)

`rng-tools` (for entropy issues)



## Usage



NOTE: Flags with parameters should use an "equals"

  `-autofit=true`

  `-URL=https://play.grafana.org` when used with any boolean flags.



```TEXT

  -URL string

      URL to Grafana server (default "https://play.grafana.org")

  -apikey string

      apikey

  -audience string

      idtoken audience

  -auto-login

      oauth_auto_login is enabled in grafana config

			(set this flag along with the "local" login-method to bypass OAuth via the /login/local url and use a local grafana user/pass before continuing to the target URL)

  -autofit

      Fit panels to screen (default true)

  -c string

      Path to configuration file (config.yaml)

  -field-password string

      Fieldname for the password (default "password")

  -field-username string

      Fieldname for the username (default "username")

  -ignore-certificate-errors

      Ignore SSL/TLS certificate error

  -keyfile string

      idtoken json credentials (default "key.json")

  -kiosk-mode string

      Kiosk Display Mode [full|tv|disabled]

        full = No TOPNAV and No SIDEBAR

        tv = No SIDEBAR

        disabled = omit option

        (default "full")

  -login-method string

      [anon|local|gcom|goauth|idtoken|apikey|aws] (default "anon")

  -lxde

      Initialize LXDE for kiosk mode

  -lxde-home string

      Path to home directory of LXDE user running X Server (default "/home/pi")

  -password string

      password (default "guest")

  -playlists

      URL is a playlist

  -username string

      username (default "guest")

  -use-mfa

      MFA is enabled for given account (default false)

  -window-position string

      Top Left Position of Kiosk (default "0,0")

  -window-size string

      Size of Kiosk in pixels (e.g. "1920,1080")

  -scale-factor string

      Scale factor of Kiosk. This is sort of like zoom. (default: "1")

```



### Using a configuration file



The kiosk can also be started using a configuration file, along with environment variables.

When using this option, all other arguments passed are ignored.



```YAML

general:

  kiosk-mode: full

  autofit: true

  lxde: true

  lxde-home: /home/pi

  scale-factor: 1.0



target:

  login-method: anon

  username: user

  password: changeme

  playlist: false

  URL: https://play.grafana.org

  ignore-certificate-errors: false

```



```BASH

grafana-kiosk -c config.yaml

```



Environment variables can be set and will override the configuration file.

They can also be used instead of a configuration file.



```TEXT

  KIOSK_AUTOFIT bool

      fit panels to screen (default "true")

  KIOSK_LXDE_ENABLED bool

      initialize LXDE for kiosk mode (default "false")

  KIOSK_LXDE_HOME string

      path to home directory of LXDE user running X Server (default "/home/pi")

  KIOSK_MODE string

      [full|tv|disabled] (default "full")

  KIOSK_WINDOW_POSITION string

      Top Left Position of Kiosk (default "0,0")

  KIOSK_WINDOW_SIZE string

      Size of Kiosk in pixels (e.g. "1920,1080")

  KIOSK_SCALE_FACTOR string

      Scale factor, like zoom

  KIOSK_IGNORE_CERTIFICATE_ERRORS bool

      Ignore SSL/TLS certificate errors (default "false")

  KIOSK_IS_PLAYLIST bool

      URL is a playlist (default "false")

  KIOSK_LOGIN_METHOD string

      [anon|local|gcom|goauth|idtoken|apikey|aws] (default "anon")

  KIOSK_LOGIN_PASSWORD string

      password (default "guest")

  KIOSK_URL string

      URL to Grafana server (default "https://play.grafana.org")

  KIOSK_LOGIN_USER string

      username (default "guest")

  KIOSK_GOAUTH_AUTO_LOGIN bool

      [false|true]

  KIOSK_GOAUTH_FIELD_USER string

      Username html input name value

  KIOSK_GOAUTH_FIELD_PASSWORD string

      Password html input name value

  KIOSK_IDTOKEN_KEYFILE string

      JSON Credentials for idtoken (default "key.json")

  KIOSK_IDTOKEN_AUDIENCE string

      Audience for idtoken, tpyically your oauth client id

  KIOSK_APIKEY_APIKEY string

      APIKEY Generated in Grafana Server

```



### Hosted Grafana using grafana.com authentication



This will login to a Hosted Grafana instance and take the browser to the default dashboard in fullscreen kiosk mode:



```bash

./bin/grafana-kiosk -URL=https://bkgann3.grafana.net -login-method=gcom -username=bkgann -password=abc123 -kiosk-mode=full

```



This will login to a Hosted Grafana instance and take the browser to a specific dashboard in tv kiosk mode:



```bash

./bin/grafana-kiosk -URL=https://bkgann3.grafana.net/dashboard/db/sensu-summary -login-method=gcom -username=bkgann -password=abc123 -kiosk-mode tv

```



This will login to a Hosted Grafana instance and take the browser to a playlist in fullscreen kiosk mode, and autofit the panels to fill the display.



```bash

./bin/grafana-kiosk -URL=https://bkgann3.grafana.net/playlists/play/1 -login-method=gcom -username=bkgann -password=abc123 -kiosk-mode=full -playlists -autofit=true

```



### Grafana Server with Local Accounts



This will login to a grafana server that uses local accounts:



```bash

./bin/grafana-kiosk -URL=https://localhost:3000 -login-method=local -username=admin -password=admin -kiosk-mode=tv

```



If you are using a self-signed certificate, you can remove the certificate error with `-ignore-certificate-errors`



```bash

./bin/grafana-kiosk -URL=https://localhost:3000 -login-method=local -username=admin -password=admin -kiosk-mode=tv -ignore-certificate-errors

```



This will login to a grafana server, configured for AzureAD OAuth and has Oauth_auto_login is enabled, bypassing OAuth and using a manually setup local username and password.



```bash

./bin/grafana-kiosk -URL=https://localhost:3000 -login-method=local -username=admin -password=admin -auto-login=true -kiosk-mode=tv

```



### Grafana Server with Anonymous access enabled



This will take the browser to the default dashboard on play.grafana.org in fullscreen kiosk mode (no login needed):



```bash

./bin/grafana-kiosk -URL=https://play.grafana.org -login-method=anon -kiosk-mode=tv

```



This will take the browser to a playlist on play.grafana.org in fullscreen kiosk mode (no login needed):



```bash

./bin/grafana-kiosk -URL=https://play.grafana.org/playlists/play/1 -login-method=anon -kiosk-mode=tv

```



### Grafana Server with Api Key



This will take the browser to the default dashboard on play.grafana.org in fullscreen kiosk mode:



```bash

./bin/grafana-kiosk -URL=https://play.grafana.org -login-method apikey --apikey "xxxxxxxxxxxxxxx" -kiosk-mode=tv

```



### Grafana Server with Generic Oauth



This will login to a Generic Oauth service, configured on Grafana. Oauth_auto_login is disabeld. As Oauth provider is Keycloak used.



```bash

go run pkg/cmd/grafana-kiosk/main.go -URL=https://my.grafana.oauth/playlists/play/1  -login-method=goauth -username=test -password=test

```



This will login to a Generic Oauth service, configured on Grafana. Oauth_auto_login is disabeld. As Oauth provider is Keycloak used and also the login and password html input name is set.



```bash

go run pkg/cmd/grafana-kiosk/main.go -URL=https://my.grafana.oauth/playlists/play/1 -login-method=goauth -username=test -password=test -field-username=username -field-password=password

```



This will login to a Generic Oauth service, configured on Grafana. Oauth_auto_login is enabled. As Oauth provider is Keycloak used and also the login and password html input name is set.



```bash

go run pkg/cmd/grafana-kiosk/main.go -URL=https://my.grafana.oauth/playlists/play/1 -login-method=goauth -username=test -password=test -field-username=username -field-password=password -auto-login=true

```



### Google Idtoken authentication



This allows you to log in through Google Identity Aware Proxy using a service account through injecting authorization headers with bearer tokens into each request. the idtoken library will generate new tokens as needed on expiry, allowing grafana kiosk mode without exposing a fully privileged google user on your kiosk device.



```bash

./bin/grafana-kiosk -URL=https://play.grafana.org/playlists/play/1 -login-method=idtoken -keyfile /tmp/foo.json -audience myoauthid.apps.googleusercontent.com

```



## LXDE Options



The `-lxde` option initializes settings for the desktop.



Actions Performed:



- sets profile via lxpanel to LXDE

- sets pcmanfs profile to LXDE

- runs `xset s off` to disable screensaver

- runs `xset -dpms` to disable power-saving (prevents screen from turning off)

- runs `xset s noblank` disables blank mode for screensaver (maybe not needed)

- runs `unclutter` to hide the mouse



The `-lxde-home` option allows you to specify a different $HOME directory where the lxde configuration files can be found.



## Automatic Startup



### Session-based



LXDE can start the kiosk automatically by creating this file:



Create/edit the file: `/home/pi/.config/lxsession/LXDE-pi/autostart`



```BASH

/usr/bin/grafana-kiosk -URL=https://bkgann3.grafana.net/dashboard/db/sensu-summary -login-method=gcom -username=bkgann -password=abc123 -kiosk-mode=full -lxde

```



#### Session with disconnected "screen"



Alternatively you can run grafana-kiosk under screen, which can very useful for debugging.



Create/edit the file: `/home/pi/.config/lxsession/LXDE-pi/autostart`



```BASH

screen -d -m bash -c "/usr/bin/grafana-kiosk -URL=https://bkgann3.grafana.net/dashboard/db/sensu-summary -login-method=gcom -username=bkgann -password=abc123 -kiosk-mode=full -lxde"

```



### Desktop Link



Create/edit the file: `/home/pi/.config/autostart/grafana-kiosk.desktop`



```INI

[Desktop Entry]

Type=Application

Exec=/usr/bin/grafana-kiosk -URL=https://bkgann3.grafana.net/dashboard/db/sensu-summary -login-method=gcom -username=bkgann -password=abc123 -kiosk-mode=full -lxde

```



#### Desktop Link with disconnected "screen"



```INI

[Desktop Entry]

Type=Application

Exec=screen -d -m bash -c /usr/bin/grafana-kiosk -URL=https://bkgann3.grafana.net/dashboard/db/sensu-summary -login-method=gcom -username=bkgann -password=abc123 -kiosk-mode=full -lxde

```



## Systemd startup



```BASH

# sudo touch /etc/systemd/system/grafana-kiosk.service

# sudo chmod 664 /etc/systemd/system/grafana-kiosk.service

```



```INI

[Unit]

Description=Grafana Kiosk

Documentation=https://github.com/grafana/grafana-kiosk

Documentation=https://grafana.com/blog/2019/05/02/grafana-tutorial-how-to-create-kiosks-to-display-dashboards-on-a-tv

After=network.target



[Service]

User=pi

Environment="DISPLAY=:0"

Environment="XAUTHORITY=/home/pi/.Xauthority"



# Disable screensaver and monitor standby

ExecStartPre=xset s off

ExecStartPre=xset -dpms

ExecStartPre=xset s noblank



ExecStart=/usr/bin/grafana-kiosk -URL= -login-method=local -username= -password= -playlists=true



[Install]

WantedBy=graphical.target

```



Reload systemd:



```BASH

# sudo systemctl daemon-reload

```



Enable, Start, Get Status, and logs:



```BASH

# sudo systemctl enable grafana-kiosk

# sudo systemctl start grafana-kiosk

# sudo systemctl status grafana-kiosk

```



Logs:



```BASH

journalctl -u grafana-kiosk

```



## Troubleshooting



### Timeout Launching



```LOG

2020/08/24 10:18:41 Launching local login kiosk

panic: websocket url timeout reached

```



Often this is due to lack of entropy, for linux you would need to install `rng-tools` (or an equivalent).



```BASH

apt install rng-tools

```



## Building



A Magefile is provided for building the utility, you can install mage by following the instructions at 



```bash

mage -v

```



This will generate executables in "bin" that can be run on a variety of platforms.



For full build and testing options use:



```BASH

mage -l

```



## TODO



- RHEL/CentOS auto-startup

- Everything in issues!



## References



- [TV and Kiosk Mode](https://grafana.com/docs/guides/whats-new-in-v5-3/#tv-and-kiosk-mode)

- [Grafana Playlists](https://grafana.com/docs/reference/playlist)



## Thanks to our Contributors



- [Michael Pasqualone](https://github.com/michaelp85) for the session-based startup ideas!

- [Brendan Ball](https://github.com/BrendanBall) for contributing the desktop link startup example for LXDE!

- [Alex Heylin](https://github.com/AlexHeylin) for the v7 login fix - and also works with v6!

- [Xan Manning](https://github.com/xanmanning) for the ignore certificate option!

- [David Stäheli](https://github.com/mistadave) for the OAuth implementation!

- [Marcus Ramberg](https://github.com/marcusramberg) for the Google ID Token Auth implementation!

- [Ronan Salmon](https://github.com/ronansalmon) for API token authentication!



Any many others!