Skip to main content

Configuring

All app configuration is specified in /user-data/conf.yml which is in YAML Format format. If you're using Docker, this file can be passed in as a volume. Changes can either be made directly to this file, or done through the UI. From the UI you can also export, backup, reset, validate and download your configuration file.

There are three ways to edit the config#

  • Directly in the YAML file (5/5 reliability, 3/5 usability)
    • Write changes directly to the conf.yml file, optionally using one of the templates provided. This can be done in your favorite editor and uploading to your server, or directly editing the file via SSH, but the easiest method would be to use Code Server
  • UI JSON Editor (4/5 reliability, 4/5 usability)
    • From the UI, under the config menu there is a JSON editor, with built-in validation, documentation and advanced options
  • UI Visual Editor (3/5 reliability, 5/5 usability)
    • From the UI, enter the Interactive Edit Mode, then click any part of the page to edit. Changes are previewed live, and then saved to disk
  • REST API (Coming soon)
    • Programmatically edit config either through the command line, using a script or a third-party application

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 if you're using Docker
  • It is recommended to keep a backup of your config file. You can download it under Config menu, or use the Cloud Backup feature.
  • You can make use of YAML features, like anchors, comments, multi-line strings, etc to reuse attributes and keep your config file readable
  • Once you have finished configuring your dashboard, you can choose to disable UI config if you wish
  • All fields are optional, unless otherwise stated.

The following file provides a reference of all supported configuration options.

Contents#


Top-Level Fields#

FieldTypeRequiredDescription
pageInfoobjectRequiredBasic meta data like title, description, nav bar links, footer text. See pageInfo
appConfigobjectOptionalSettings related to how the app functions, including API keys and global styles. See appConfig
sectionsarrayRequiredAn array of sections, each containing an array of items, which will be displayed as links. See section
pagesarrayOptionalAn array additional config files, used for multi-page dashboards. See pages

⬆️ Back to Top

PageInfo#

FieldTypeRequiredDescription
titlestringRequiredYour dashboard title, displayed in the header and browser tab
descriptionstringOptionalDescription of your dashboard, also displayed as a subtitle
navLinksarrayOptionalOptional list of a maximum of 6 links, which will be displayed in the navigation bar. See navLinks
footerTextstringOptionalText to display in the footer (note that this will override the default footer content). This can also include HTML and inline CSS
logostringOptionalThe 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)#

FieldTypeRequiredDescription
titlestringRequiredThe text to display on the link button
pathstringRequiredThe 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)
targetstringOptionalThe opening method (external links only). Can be either newtab, sametab, top or parent. Defaults to newtab

⬆️ Back to Top

pages[] (optional)#

FieldTypeRequiredDescription
namestringRequiredA unique name for that page
pathstringRequiredThe path (local or remote) to the config file to use.
For files located within /public, you only need to specify filename, for externally hosted files you must include the full URL

⬆️ Back to Top

appConfig (optional)#

FieldTypeRequiredDescription
languagestringOptionalThe 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.
startingViewenumOptionalWhich 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. NOTE: This has been replaced by an environmental variable: VUE_APP_STARTING_VIEW in V3 onwards
defaultOpeningMethodenumOptionalThe default opening method for items, if no target is specified for a given item. Can be either newtab, sametab, modal, workspace, clipboard, top or parent. Defaults to newtab
statusCheckbooleanOptionalWhen 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
statusCheckIntervalnumberOptionalThe 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
webSearchobjectOptionalConfiguration options for the web search feature, set your default search engine, opening method or disable web search. See webSearch
backgroundImgstringOptionalPath to an optional full-screen app background image. This can be either remote (http) or local (relative to /app/public/item-icons/ inside the container). Note that this will slow down initial load
enableFontAwesomebooleanOptionalIf set to true font-awesome will be loaded, if set to false they will not be. if left blank font-awesome will be enabled only if required by 1 or more icons
enableMaterialDesignIconsbooleanOptionalIf set to true mdi icons will be loaded, if set to false they will not be. Where true is enabled, if left blank material design icons will be enabled only if required by 1 or more icons
fontAwesomeKeystringOptionalIf 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)
faviconApienumOptionalOnly 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, iconhorse, google, clearbit, webmasterapi and allesedv. Defaults to faviconkit. See Icons for more info
authobjectOptionalAll settings relating to user authentication. See auth
defaultIconstringOptionalAn icon to be applied to any items, which don't already have an icon set. See Icon Docs for more info
layoutenumOptionalLayout for homepage, either horizontal, vertical or auto. Defaults to auto. This specifies the layout and direction of how sections are positioned on the home screen. This can also be modified and overridden from the UI.
iconSizeenumOptionalThe size of link items / icons. Can be either small, medium, or large. Defaults to medium. This can also be set directly from the UI.
colCountnumberOptionalThe number of columns of sections displayed on the homepage, using the default view. Should be in integer between 1 and 8. Note that by default this is applied responsively, based on current screen size, and specifying a value here will override this behavior, which may not be desirable.
themestringOptionalThe default theme for first load (you can change this later from the UI)
cssThemesstring[]OptionalAn array of custom theme names which can be used in the theme switcher dropdown
customColorsobjectOptionalEnables 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
externalStyleSheetstring or string[]OptionalEither a URL to an external stylesheet or an array or URLs, which can be applied as themes within the UI
customCssstringOptionalRaw CSS that will be applied to the page. This can also be set from the UI. Please minify it first.
hideComponentsobjectOptionalA 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
routingModestringOptionalCan be either hash or history. Determines the URL format for sub-pages, hash mode will look like /#/home whereas with history mode available you have nice clean URLs, like /home. For more info, see the Vue docs. If you're hosting Dashy with a custom BASE_URL, you will find that a bit of extra server config is necessary to get history mode working, so here you may want to instead use hash mode.Defaults to history.
enableMultiTaskingbooleanOptionalIf 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.
workspaceLandingUrlstringOptionalThe URL or an app, service or website to launch when the workspace view is opened, before another service has been launched
preventWriteToDiskbooleanOptionalIf set to true, users will be prevented from saving config changes to disk through the UI
preventLocalSavebooleanOptionalIf set to true, users will be prevented from applying config changes to local storage
disableConfigurationbooleanOptionalIf set to true, no users will be able to view or edit the config through the UI
disableConfigurationForNonAdminbooleanOptionalIf set to true, only admin users will be able to view or edit the config through the UI. disableConfiguration must not be set to true.
widgetsAlwaysUseProxybooleanOptionalIf set to true, requests made by widgets will always be proxied, same as setting useProxy: true on each widget. Note that this may break some widgets.
showSplashScreenbooleanOptionalIf set to true, a loading screen will be shown. Defaults to false.
enableErrorReportingbooleanOptionalEnable 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.
sentryDsnbooleanOptionalIf 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.
disableSmartSortbooleanOptionalFor 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.
disableUpdateChecksbooleanOptionalIf set to true, Dashy will not check for updates. Defaults to false.
enableServiceWorkerbooleanOptionalService 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 false to disable all service workers.
disableContextMenubooleanOptionalIf set to true, the custom right-click context menu will be disabled. Defaults to false.

⬆️ Back to Top

appConfig.auth (optional)#

[!NOTE] Since the auth is initiated in the main app entry point (for security), a rebuild is required to apply changes to the auth configuration. You can trigger a rebuild through the UI, under Config --> Rebuild, or by running yarn build in the root directory.

[!WARNING] Built-in auth should not be used for security-critical applications, or if your Dashy instance is publicly accessible. For these, it is recommended to use an alternate authentication method.

FieldTypeRequiredDescription
usersarrayOptionalAn 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.
enableKeycloakbooleanOptionalIf set to true, then authentication using Keycloak will be enabled. Note that you need to have an instance running, and have also configured auth.keycloak. Defaults to false
keycloakobjectOptionalConfig options to point Dashy to your Keycloak server. Requires enableKeycloak: true. See auth.keycloak for more info
enableHeaderAuthbooleanOptionalIf set to true, then authentication using HeaderAuth will be enabled. Note that you need to have your web server/reverse proxy running, and have also configured auth.headerAuth. Defaults to false
headerAuthobjectOptionalConfig options to point Dashy to your headers for authentication. Requires enableHeaderAuth: true. See auth.headerAuth for more info
enableOidcbooleanOptionalIf set to true, then authentication using OIDC will be enabled. Note that you need to have a configured OIDC server and configure it with auth.oidc. Defaults to false
oidcobjectOptionalConfig options to point Dash to your OIDC configuration. Request enableOidc: true. See auth.oidc for more info
enableGuestAccessbooleanOptionalWhen 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)#

FieldTypeRequiredDescription
userstringRequiredUsername to log in with
hashstringRequiredA SHA-256 hashed password
typestringOptionalThe user type, either admin or normal

⬆️ Back to Top

appConfig.auth.keycloak (optional)#

FieldTypeRequiredDescription
serverUrlstringRequiredThe URL (or URL/ IP + Port) where your keycloak server is running
realmstringRequiredThe name of the realm (must already be created) that you want to use
clientIdstringRequiredThe Client ID of the client you created for use with Dashy
legacySupportbooleanOptionalIf using Keycloak 17 or older, then set this to true

⬆️ Back to Top

appConfig.auth.headerAuth (optional)#

FieldTypeRequiredDescription
userHeaderstringOptionalThe Header name which contains username (default: REMOTE_USER). Case insensitive
proxyWhitelistarrayRequiredAn array of Upstream proxy servers to expect authencticated requests from

⬆️ Back to Top

appConfig.auth.oidc (optional)#

FieldTypeRequiredDescription
clientIdstringRequiredThe client id registered in the OIDC server
endpointstringRequiredThe URL of the OIDC server that should be used.

⬆️ Back to Top

appConfig.webSearch (optional)#

FieldTypeRequiredDescription
disableWebSearchstringOptionalWeb search is enabled by default, but can be disabled by setting this property to true
searchEnginestringOptionalSet 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
customSearchEnginestringOptionalYou 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
openingMethodstringOptionalSet your preferred opening method for search results: newtab, sametab, workspace. Defaults to newtab
searchBangsobjectOptionalA key-value-pair set of custom search bangs for redirecting query to a specific app or search engine. The key of each should be the bang you will type (typically starting with /, ! or :), and value is the destination, either as a search engine key (e.g. reddit) or a URL with search parameters (e.g. https://en.wikipedia.org/w/?search=)

⬆️ Back to Top

appConfig.hideComponents (optional)#

FieldTypeRequiredDescription
hideHeadingbooleanOptionalIf set to true, the page title & sub-title will not be visible. Defaults to false
hideNavbooleanOptionalIf set to true, the navigation menu will not be visible. Defaults to false
hideSearchbooleanOptionalIf set to true, the search bar will not be visible. Defaults to false
hideSettingsbooleanOptionalIf set to true, the settings menu will be initially collapsed. Defaults to false
hideFooterbooleanOptionalIf set to true, the footer will not be visible. Defaults to false

⬆️ Back to Top

section#

FieldTypeRequiredDescription
namestringRequiredThe title for the section
iconstringOptionalAn single icon to be displayed next to the title. See section.icon
itemsarrayOptionalAn array of items to be displayed within the section. See item. Sections must include either 1 or more items, or 1 or more widgets.
widgetsarrayOptionalAn array of widgets to be displayed within the section. See widget
displayDataobjectOptionalMeta-data to optionally override display settings for a given section. See displayData

⬆️ Back to Top

section.item#

FieldTypeRequiredDescription
titlestringRequiredThe text to display/ title of a given item. Max length 18
descriptionstringOptionalAdditional info about an item, which is shown in the tooltip on hover, or visible on large tiles
urlstringRequiredThe URL / location of web address for when the item is clicked
iconstringOptionalThe icon for a given item. Can be a font-awesome icon, favicon, remote URL or local URL. See item.icon
targetstringOptionalThe opening method for when the item is clicked, either newtab, sametab, modal, workspace, clipboard, top or parent. 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, workspace will open in the Workspace view and clipboard will copy the URL to system clipboard (but not launch app). Defaults to newtab
hotkeynumberOptionalGive frequently opened applications a numeric hotkey, between 0 - 9. You can then just press that key to launch that application.
tagsstring[]OptionalA list of tags, which can be used for improved search
statusCheckbooleanOptionalWhen 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
statusCheckUrlstringOptionalIf you've enabled statusCheck, and want to use a different URL to what is defined under the item, then specify it here
statusCheckHeadersobjectOptionalIf you're endpoint requires any specific headers for the status checking, then define them here
statusCheckAllowInsecurebooleanOptionalBy 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
statusCheckAcceptCodesstringOptionalIf your service's response code is anything other than 2xx, then you can opt to specify an alternative success code. E.g. if you expect your server to return 403, but still want the status indicator to be green, set this value to 403
statusCheckMaxRedirectsnumberOptionalIf your service redirects to another page, and you would like status checks to follow redirects, then specify the maximum number of redirects here. Defaults to 0 / will not follow redirects
colorstringOptionalAn 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
relstringOptionalThe value of the rel attribute for the link. Useful for specifying the relationship between the target link/document and Dashy. Defaults to noopener noreferrer
backgroundColorstringOptionalAn 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
providerstringOptionalThe name of the provider for a given service, useful for when including hosted apps. In some themes, this is visible under the item name
displayDataobjectOptionalMeta-data to optionally override display settings for a given item. See displayData

⬆️ Back to Top

item.displayData (optional)#

FieldTypeRequiredDescription
hideForUsersstring[]OptionalCurrent item will be visible to all users, except for those specified in this list
showForUsersstring[]OptionalCurrent item will be hidden from all users, except for those specified in this list
hideForGuestsbooleanOptionalCurrent item will be visible for logged in users, but not for guests (see appConfig.enableGuestAccess). Defaults to false
hideForKeycloakUsersobjectOptionalCurrent item will be visible to all keycloak users, except for those configured via these groups and roles. See hideForKeycloakUsers
showForKeycloakUsersobjectOptionalCurrent item will be hidden from all keycloak users, except for those configured via these groups and roles. See showForKeycloakUsers

⬆️ Back to Top

section.widgets (optional)#

FieldTypeRequiredDescription
typestringRequiredThe widget type. See Widget Docs for full list of supported widgets
optionsobjectOptionalSome widgets accept either optional or required additional options. Again, see the Widget Docs for full list of options
updateIntervalnumberOptionalYou can keep a widget constantly updated by specifying an update interval, in seconds. See Continuous Updates Docs for more info
useProxybooleanOptionalSome widgets make API requests to services that are not CORS-enabled. For these instances, you will need to route requests through a proxy, Dashy has a built in CORS-proxy, which you can use by setting this option to true. Defaults to false. See the Proxying Requests Docs for more info
timeoutnumberOptionalRequest timeout in milliseconds, defaults to ½ a second (500)
ignoreErrorsbooleanOptionalPrevent an error message being displayed, if a network request or something else fails. Useful for false-positives
labelstringOptionalAdd custom label to a given widget. Useful for identification, if there are multiple of the same type of widget in a single section

⬆️ Back to Top

section.displayData (optional)#

FieldTypeRequiredDescription
sortBystringOptionalThe 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
collapsedbooleanOptionalIf 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
cutToHeightbooleanOptionalBy default, sections will fill available space. Set this option to true to match section height with content height
rowsnumberOptionalHeight of the section, specified as the number of rows it should span vertically, e.g. 2. Defaults to 1. Max is 5.
colsnumberOptionalWidth of the section, specified as the number of columns the section should span horizontally, e.g. 2. Defaults to 1. Max is 5.
itemSizestringOptionalSpecify the size for items within this group, either small, medium or large. Note that this will override any settings specified through the UI
colorstringOptionalA custom accent color for the section, as a hex code or HTML color (e.g. #fff)
customStylesstringOptionalCustom CSS properties that should be applied to that section, e.g. border: 2px dashed #ff0000;
sectionLayoutstringOptionalSpecify which CSS layout will be used to responsively 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
itemCountXnumberOptionalThe 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
itemCountYnumberOptionalThe 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
hideForUsersstring[]OptionalCurrent section will be visible to all users, except for those specified in this list
showForUsersstring[]OptionalCurrent section will be hidden from all users, except for those specified in this list
hideForGuestsbooleanOptionalCurrent section will be visible for logged in users, but not for guests (see appConfig.enableGuestAccess). Defaults to false
hideForKeycloakUsersobjectOptionalCurrent section will be visible to all keycloak users, except for those configured via these groups and roles. See hideForKeycloakUsers
showForKeycloakUsersobjectOptionalCurrent section will be hidden from all keycloak users, except for those configured via these groups and roles. See showForKeycloakUsers

⬆️ Back to Top

section.icon and section.item.icon#

FieldTypeRequiredDescription
iconstringOptionalThe icon for a given item or section.
See Icon Docs for all available supported icon types, including: auto-fetched favicons, generative icons, emoji icons, home-lab service logos, font-awesome, simple-icons, material icons, and icons specified by URL

⬆️ Back to Top

section.displayData.hideForKeycloakUsers, section.displayData.showForKeycloakUsers, item.displayData.hideForKeycloakUsers and item.displayData.showForKeycloakUsers#

FieldTypeRequiredDescription
groupsstring[]OptionalCurrent Section or Item will be hidden or shown based on the user having any of the groups in this list
rolesstring[]OptionalCurrent Section or Item will be hidden or shown based on the user having any of the roles in this list

⬆️ Back to Top


Notes#

Editing Config through the UI#

Config can be modified directly through the UI, and then written to disk, or applied locally. This can be done wither with the raw config editor (introduced in V 0.6.5 / #3), or the interactive editor (introduced in V 1.8.9 / #298).

Interactive Editor
Interactive Editor demo

JSON Editor
Config Editor demo

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#

If you have authentication set up, then any user who is not an admin (with type: admin) will not be able to write changes to disk.

You can also prevent changes from any user being written to disk, using preventWriteToDisk. Or prevent any changes from being saved locally in browser storage, using preventLocalSave.

To disable all UI config features, set disableConfiguration. Alternatively you can disable UI config features for all non Admin users by setting disableConfigurationForNonAdmin to true.

Example#

---pageInfo:  title: Home Labsections: # 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