Button

type: button · version 1.3.0 · widget API 1 · Widget collection v0.12.0 · source

Button with example data

A button on a card or in the header that opens a link, or runs a script or a shell command on the dashboard’s server, for jobs such as pulling new images, restarting a stack or starting a backup. Set exactly one of href, script or command; with none or several, the card shows an error.

  • href opens the page in a new tab.
  • script runs a file with bash. A relative path is relative to the config folder (/config in the container), which is also the folder the run starts in.
  • command runs a line with bash -c, such as docker compose -f stacks/media.yaml pull.

While it runs, the button shows a spinner instead of its label and cannot be pressed. A run that succeeds (exit code 0) shows a check for a moment, then the label again. A run that fails opens the dashboard’s result dialog with the output (stdout and stderr together, the last 64 kB) and the exit code; the output can be copied from there. A run that takes longer than timeout seconds (default 300) is stopped, together with everything it started. Values filled in from {{HD_VAR_*}} are scrubbed from the output.

The run gets only PATH and HOME from the dashboard’s environment; set inheritEnv: true to pass all of it (including every HD_VAR_*). It runs as the dashboard’s user (node, uid 1000, in the image), so tools such as curl, jq or docker must be in the image and the Docker socket must allow that user.

Running as root

user: root runs the script as root inside the container, for a script that writes files which must stay owned by root (a proxy’s config, chown). It needs HD_ALLOW_ROOT_SCRIPTS: "true" in the dashboard container’s environment; without it the button says so. The dashboard itself keeps running as node: the image lets it start one fixed runner as root through sudo, and only when that variable is set. HOME is then /root; inheritEnv: true passes the dashboard’s environment to the root script too. A timeout stops the root script and what it started. Once the variable is on, any installed widget could run as root in the container, so set it only on a dashboard you trust. Anyone who can open the dashboard can press the button: put the dashboard behind authentication before you add buttons that change things. script and command are kept on the server; the browser only gets the label.

Several buttons on one card are several button widgets, each one full width.

Display fields

No blocks: the button is drawn by the widget.

Configuration options

Option Type Required Default Description
text string yes   The button’s label
href url     Opens this page in a new tab, e.g. https://grafana.lan/
script string     Secret: stays on the server. A bash script to run, e.g. scripts/update.sh (relative to the config folder)
command string     Secret: stays on the server. A shell command to run with bash -c, e.g. docker compose pull
timeout number   300 Seconds before the run is stopped
inheritEnv boolean   false Give the run the dashboard’s whole environment, not only PATH and HOME
user node / root   node Root needs HD_ALLOW_ROOT_SCRIPTS=true on the dashboard container

Every widget also takes refresh (or refreshInterval in ms), fields and hideErrors; see Services.

Filter attributes

Public values a service’s filter: can read, as widget.<attribute>; see Filtering services.

Attribute Type Description
attention boolean True while the card marks something as needing attention

Example 

# services.yaml
- Media:
    - Jellyfin:
        href: https://jellyfin.lan
        widgets:
          - type: button
            text: Pull new images
            command: docker compose -f stacks/media.yaml pull
            timeout: 600
          - type: button
            text: Back up the library
            script: scripts/backup-jellyfin.sh
          - type: button
            text: Release notes
            href: https://github.com/jellyfin/jellyfin/releases
- Proxy:
    - SWAG:
        widget:
          type: button
          text: Generate proxy configs
          command: cd /srv/configs && ./gen-swag.sh
          user: root                 # needs HD_ALLOW_ROOT_SCRIPTS: "true" on the dashboard container