tyler.durden
/
dashy
mirror of https://github.com/Lissy93/dashy.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
dashy/docs/configuring.md

25 KiB
Raw Blame History

Configuring

All app configuration is specified in /public/conf.yml which is in YAML Format format.

Contents

Tips:

  • You may find it helpful to look at some sample config files to get you started, a collection of which can be found here
  • You can check that your config file fits the schema, by running yarn validate-config
  • After modifying your config, the app needs to be recompiled, by running yarn build - this happens automatically whilst the app is running if you're using Docker
  • It is recommended to make and keep a backup of your config file. You can download your current config through the UI either from the Config menu, or using the /download endpoint. Alternatively, you can use the Cloud Backup feature.
  • The config can also be modified directly through the UI, validated and written to the conf.yml file.
  • All fields are optional, unless otherwise stated.

Top-Level Fields

Field Type Required Description
pageInfo object Required Basic meta data like title, description, nav bar links, footer text. See pageInfo
appConfig object Optional Settings related to how the app functions, including API keys and global styles. See appConfig
sections array Required An array of sections, each containing an array of items, which will be displayed as links. See section

⬆️ Back to Top

PageInfo

Field Type Required Description
title string Required Your dashboard title, displayed in the header and browser tab
description string Optional Description of your dashboard, also displayed as a subtitle
navLinks array Optional Optional list of a maximum of 6 links, which will be displayed in the navigation bar. See navLinks
footerText string Optional Text to display in the footer (note that this will override the default footer content). This can also include HTML and inline CSS
logo string Optional The path to an image to display in the header (to the right of the title). This can be either local, where / is the root of ./public, or any remote image, such as https://i.ibb.co/yhbt6CY/dashy.png. It's recommended to scale your image down, so that it doesn't impact load times

⬆️ Back to Top

pageInfo.navLinks (optional)

Field Type Required Description
title string Required The text to display on the link button
path string Required The URL to navigate to when clicked. Can be relative (e.g. /about) or absolute (e.g. https://example.com or http://192.168.1.1)

⬆️ Back to Top

appConfig (optional)

Field Type Required Description
language string Optional The 2 (or 4-digit) ISO 639-1 code for your language, e.g. en or en-GB. This must be a language that the app has already been translated into. If your language is unavailable, Dashy will fallback to English. By default Dashy will attempt to auto-detect your language, although this may not work on some privacy browsers.
startingView enum Optional Which page to load by default, and on the base page or domain root. You can still switch to different views from within the UI. Can be either default, minimal or workspace. Defaults to default
statusCheck boolean Optional When set to true, Dashy will ping each of your services and display their status as a dot next to each item. This can be overridden by setting statusCheck under each item. Defaults to false
statusCheckInterval boolean Optional The number of seconds between checks. If set to 0 then service will only be checked on initial page load, which is usually the desired functionality. If value is less than 10 you may experience a hit in performance. Defaults to 0
webSearch object Optional Configuration options for the web search feature, set your default search engine, opening method or disable web search. See webSearch
backgroundImg string Optional Path to an optional full-screen app background image. This can be either remote (http) or local (/). Note that this will slow down initial load
enableFontAwesome boolean Optional Where true is enabled, if left blank font-awesome will be enabled only if required by 1 or more icons
fontAwesomeKey string Optional If you have a font-awesome key, then you can use it here and make use of premium icons. It is a 10-digit alpha-numeric string from you're FA kit URL (e.g. 13014ae648)
faviconApi enum Optional Only applicable if you are using favicons for item icons. Specifies which service to use to resolve favicons. Set to local to do this locally, without using an API. Services running locally will use this option always. Available options are: local, faviconkit, google, clearbit, webmasterapi and allesedv. Defaults to faviconkit. See Icons for more info
auth object Optional All settings relating to user authentication. See auth
layout enum Optional App layout, either horizontal, vertical, auto or sidebar. Defaults to auto. This specifies the layout and direction of how sections are positioned on the home screen. This can also be modified from the UI.
iconSize enum Optional The size of link items / icons. Can be either small, medium, or large. Defaults to medium. This can also be set directly from the UI.
theme string Optional The default theme for first load (you can change this later from the UI)
cssThemes string[] Optional An array of custom theme names which can be used in the theme switcher dropdown
customColors object Optional Enables you to apply a custom color palette to any given theme. Use the theme name (lowercase) as the key, for an object including key-value-pairs, with the color variable name as keys, and 6-digit hex code as value. See Theming for more info
externalStyleSheet string or string[] Optional Either a URL to an external stylesheet or an array or URLs, which can be applied as themes within the UI
customCss string Optional Raw CSS that will be applied to the page. This can also be set from the UI. Please minify it first.
hideComponents object Optional A list of key page components (header, footer, search, settings, etc) that are present by default, but can be removed using this option. See appConfig.hideComponents
enableMultiTasking boolean Optional If set to true, will keep apps open in the background when in the workspace view. Useful for quickly switching between multiple sites, and preserving their state, but comes at the cost of performance.
allowConfigEdit boolean Optional Should prevent / allow the user to write configuration changes to the conf.yml from the UI. When set to false, the user can only apply changes locally using the config editor within the app, whereas if set to true then changes can be written to disk directly through the UI. Defaults to true. Note that if authentication is enabled, the user must be of type admin in order to apply changes globally.
enableErrorReporting boolean Optional Enable reporting of unexpected errors and crashes. This is off by default, and no data will ever be captured unless you explicitly enable it. Turning on error reporting helps previously unknown bugs get discovered and fixed. Dashy uses Sentry for error reporting. Defaults to false.
sentryDsn boolean Optional If you need to monitor errors in your instance, then you can use Sentry to collect and process bug reports. Sentry can be self-hosted, or used as SaaS, once your instance is setup, then all you need to do is pass in the DSN here, and enable error reporting. You can learn more on the Sentry DSN Docs. Note that this will only ever be used if enableErrorReporting is explicitly enabled.
disableSmartSort boolean Optional For the most-used and last-used app sort functions to work, a basic open-count is stored in local storage. If you do not want this to happen, then disable smart sort here, but you wil no longer be able to use these sort options. Defaults to false.
disableUpdateChecks boolean Optional If set to true, Dashy will not check for updates. Defaults to false.
disableServiceWorker boolean Optional Service workers cache web applications to improve load times and offer basic offline functionality, and are enabled by default in Dashy. The service worker can sometimes cause older content to be cached, requiring the app to be hard-refreshed. If you do not want SW functionality, or are having issues with caching, set this property to true to disable all service workers.
disableContextMenu boolean Optional If set to true, the custom right-click context menu will be disabled. Defaults to false.

⬆️ Back to Top

appConfig.auth (optional)

Field Type Required Description
users array Optional An array of objects containing usernames and hashed passwords. If this is not provided, then authentication will be off by default, and you will not need any credentials to access the app. See appConfig.auth.users.
Note this method of authentication is handled on the client side, so for security critical situations, it is recommended to use an alternate authentication method.
enableKeycloak object Optional If set to true, then authentication using Keycloak will be anabled. Note that you need to have an instance running, and have also configured auth.keycloak. Defaults to false
keycloak boolean Optional Config options to point Dashy to your Keycloak server. Requires enableKeycloak: true. See auth.keycloak for more info
enableGuestAccess boolean Optional When set to true, an unauthenticated user will be able to access the dashboard, with read-only access, without having to login. Requires auth.users to be configured. Defaults to false.

For more info, see the Authentication Docs

⬆️ Back to Top

appConfig.auth.users (optional)

Field Type Required Description
user string Required Username to log in with
hash string Required A SHA-256 hashed password
type string Optional The user type, either admin or normal

⬆️ Back to Top

appConfig.auth.keycloak (optional)

Field Type Required Description
serverUrl string Required The URL (or URL/ IP + Port) where your keycloak server is running
realm string Required The name of the realm (must already be created) that you want to use
clientId string Required The Client ID of the client you created for use with Dashy

⬆️ Back to Top

appConfig.webSearch (optional)

Field Type Required Description
disableWebSearch string Optional Web search is enabled by default, but can be disabled by setting this property to true
searchEngine string Optional Set the key name for your search engine. Can also use a custom engine by setting this property to custom. Currently supported: duckduckgo, google, whoogle, qwant, startpage, searx-bar and searx-info. Defaults to duckduckgo
customSearchEngine string Optional You can also use a custom search engine, or your own self-hosted instance. This requires searchEngine: custom to be set. Then add the URL of your service, with GET query string included here
openingMethod string Optional Set your preferred opening method for search results: newtab, sametab, workspace. Defaults to newtab

⬆️ Back to Top

appConfig.hideComponents (optional)

Field Type Required Description
hideHeading boolean Optional If set to true, the page title & sub-title will not be visible. Defaults to false
hideNav boolean Optional If set to true, the navigation menu will not be visible. Defaults to false
hideSearch boolean Optional If set to true, the search bar will not be visible. Defaults to false
hideSettings boolean Optional If set to true, the settings menu will not be visible. Defaults to false
hideFooter boolean Optional If set to true, the footer will not be visible. Defaults to false
hideSplashScreen boolean Optional If set to true, splash screen will not be visible while the app loads. Defaults to true (except on first load, when the loading screen is always shown)

⬆️ Back to Top

section

Field Type Required Description
name string Required The title for the section
icon string Optional An single icon to be displayed next to the title. See section.icon
items array Required An array of items to be displayed within the section. See item
displayData object Optional Meta-data to optionally overide display settings for a given section. See displayData

⬆️ Back to Top

section.item

Field Type Required Description
title string Required The text to display/ title of a given item. Max length 18
description string Optional Additional info about an item, which is shown in the tooltip on hover, or visible on large tiles
url string Required The URL / location of web address for when the item is clicked
icon string Optional The icon for a given item. Can be a font-awesome icon, favicon, remote URL or local URL. See item.icon
target string Optional The opening method for when the item is clicked, either newtab, sametab, modal or workspace. Where newtab will open the link in a new tab, sametab will open it in the current tab, and modal will open a pop-up modal with the content displayed within that iframe. Note that for the iframe to load, you must have set the CORS headers to either allow * ot allow the domain that you are hosting Dashy on, for some websites and self-hosted services, this is already set.
hotkey number Optional Give frequently opened applications a numeric hotkey, between 0 - 9. You can then just press that key to launch that application.
tags string[] Optional A list of tags, which can be used for improved search
statusCheck boolean Optional When set to true, Dashy will ping the URL associated with the current service, and display its status as a dot next to the item. The value here will override appConfig.statusCheck so you can turn off or on checks for a given service. Defaults to appConfig.statusCheck, falls back to false
statusCheckUrl string Optional If you've enabled statusCheck, and want to use a different URL to what is defined under the item, then specify it here
statusCheckHeaders object Optional If you're endpoint requires any specific headers for the status checking, then define them here
statusCheckAllowInsecure boolean Optional By default, any request to insecure content will be blocked. Setting this option to true will disable the rejectUnauthorized option, enabling you to ping non-HTTPS services for the current item. Defaults to false
color string Optional An optional color for the text and font-awesome icon to be displayed in. Note that this will override the current theme and so may not display well
backgroundColor string Optional An optional background fill color for the that given item. Again, this will override the current theme and so might not display well against the background
provider string Optional The name of the provider for a given service, useful for when including hosted apps. In some themes, this is visible under the item name

⬆️ Back to Top

section.displayData (optional)

Field Type Required Description
sortBy string Optional The sort order for items within the current section. By default items are displayed in the order in which they are listed in within the config. The following sort options are supported: most-used (most opened apps first), last-used (the most recently used apps), alphabetical, reverse-alphabetical, random and default
collapsed boolean Optional If true, the section will be collapsed initially, and will need to be clicked to open. Useful for less regularly used, or very long sections. Defaults to false
rows number Optional Height of the section, specified as the number of rows it should span vertically, e.g. 2. Defaults to 1. Max is 5.
cols number Optional Width of the section, specified as the number of columns the section should span horizontally, e.g. 2. Defaults to 1. Max is 5.
itemSize string Optional Specify the size for items within this group, either small, medium or large. Note that this will overide any settings specified through the UI
color string Optional A custom accent color for the section, as a hex code or HTML color (e.g. #fff)
customStyles string Optional Custom CSS properties that should be applied to that section, e.g. border: 2px dashed #ff0000;
sectionLayout string Optional Specify which CSS layout will be used to responsivley place items. Can be either auto (which uses flex layout), or grid. If grid is selected, then itemCountX and itemCountY may also be set. Defaults to auto
itemCountX number Optional The number of items to display per row / horizontally. If not set, it will be calculated automatically based on available space. Can only be set if sectionLayout is set to grid. Must be a whole number between 1 and 12
itemCountY number Optional The number of items to display per column / vertically. If not set, it will be calculated automatically based on available space. If itemCountX is set, then itemCountY can be calculated automatically. Can only be set if sectionLayout is set to grid. Must be a whole number between 1 and 12
hideForUsers string[] Optional Current section will be visible to all users, except for those specified in this list
showForUsers string[] Optional Current section will be hidden from all users, except for those specified in this list
hideForGuests boolean Optional Current section will be visible for logged in users, but not for guests (see appConfig.enableGuestAccess). Defaults to false

⬆️ Back to Top

section.icon and section.item.icon

Field Type Required Description
icon string Optional The icon for a given item or section. See Icon Docs for all available supported icon types. To auto-fetch icon from a services URL, aet to favicon. To use font-awesome, specify the category, followed by the icon name, e.g. fas fa-rocket, fab fa-monero or fal fa-duck. Similarly, for branded icons, you can use simple-icons by setting icon to si-[icon-name] or material-design-icons by setting icon to mdi-[icon-name]. If set to generative, then a unique icon is generated from the apps URL or IP. You can also use hosted any by specifying it's URL, e.g. https://i.ibb.co/710B3Yc/space-invader-x256.png. To use a local image, first store it in ./public/item-icons/ (or -v /app/public/item-icons/ in Docker) , and reference it by name and extension - e.g. set image.png to use ./public/item-icon/image.png, you can also use sub-folders if you have a lot of icons, to keep them organised.

⬆️ Back to Top

Notes

About YAML

If you're new to YAML, it's pretty straight-forward. The format is exactly the same as that of JSON, but instead of using curly braces, structure is denoted using whitespace. This quick guide should get you up to speed in a few minutes, for more advanced topics take a look at this Wikipedia article.

Config Saving Methods

When updating the config through the JSON editor in the UI, you have two save options: Local or Write to Disk.

  • Changes saved locally will only be applied to the current user through the browser, and will not apply to other instances - you either need to use the cloud sync feature, or manually update the conf.yml file.
  • On the other-hand, if you choose to write changes to disk, then your main conf.yml file will be updated, and changes will be applied to all users, and visible across all devices. For this functionality to work, you must be running Dashy with using the Docker container, or the Node server. A backup of your current configuration will also be saved in the same directory.

Preventing Changes being Written to Disk

To disallow any changes from being written to disk via the UI config editor, set appConfig.allowConfigEdit: false. If you are using users, and have setup auth within Dashy, then only users with type: admin will be able to write config changes to disk.

Example

---
pageInfo:
  title: Home Lab
sections: # An array of sections
- name: Section 1 - Getting Started
  items: # An array of items
  - title: GitHub
    description: Source code and documentation on GitHub
    icon: fab fa-github
    url: https://github.com/Lissy93/dashy
  - title: Issues
    description: View currently open issues, or raise a new one
    icon: fas fa-bug
    url: https://github.com/Lissy93/dashy/issues
  - title: Demo
    description: A live demo
    icon: far fa-rocket
    url: https://dashy-demo-1.netlify.app 
- name: Section 2 - Local Services
  items:
  - title: Firewall
    icon: favicon
    url: http://192.168.1.1/
  - title: Game Server
    icon: https://i.ibb.co/710B3Yc/space-invader-x256.png
    url: http://192.168.130.1/

For more example config files, see: this gist

If you need any help, feel free to Raise an Issue or Start a Discussion

Happy Configuring 🤓🔧

⬆️ Back to Top