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#

pageInfo - Header text, footer, title, navigation, etc
- navLinks - Links to display in the navigation bar
pages - List of additional config files, for multi-page dashboards
appConfig - Main application settings
- webSearch - Configure web search engine options
- hideComponents - Show/ hide page components
- auth - Built-in authentication setup
  - users - List or users (for simple auth)
  - keycloak - Auth config for Keycloak
  - headerAuth - Auth config for HeaderAuth
sections - List of sections
- displayData - Section display settings
  - show/hideForKeycloakUsers - Set user controls
- icon - Icon for a section
- items - List of items
  - icon - Icon for an item
  - displayData - Item display settings
    - show/hideForKeycloakUsers - Set user controls
- widgets - List of widgets
Notes

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`
`pages`	`array`	Optional	An array additional config files, used for multi-page dashboards. See `pages`

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

Field	Type	Required	Description
`name`	`string`	Required	A unique name for that page
`path`	`string`	Required	The 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

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`. NOTE: This has been replaced by an environmental variable: `VUE_APP_STARTING_VIEW` in V3 onwards
`defaultOpeningMethod`	`enum`	Optional	The 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`
`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`	`number`	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 (relative to /app/public/item-icons/ inside the container). Note that this will slow down initial load
`enableFontAwesome`	`boolean`	Optional	If 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
`enableMaterialDesignIcons`	`boolean`	Optional	If 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
`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`, `iconhorse`, `google`, `clearbit`, `webmasterapi` and `allesedv`. Defaults to `faviconkit`. See Icons for more info
`auth`	`object`	Optional	All settings relating to user authentication. See `auth`
`defaultIcon`	`string`	Optional	An icon to be applied to any items, which don't already have an icon set. See Icon Docs for more info
`layout`	`enum`	Optional	Layout 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.
`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.
`colCount`	`number`	Optional	The 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.
`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`
`routingMode`	`string`	Optional	Can 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`.
`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.
`workspaceLandingUrl`	`string`	Optional	The URL or an app, service or website to launch when the workspace view is opened, before another service has been launched
`preventWriteToDisk`	`boolean`	Optional	If set to `true`, users will be prevented from saving config changes to disk through the UI
`preventLocalSave`	`boolean`	Optional	If set to `true`, users will be prevented from applying config changes to local storage
`disableConfiguration`	`boolean`	Optional	If set to true, no users will be able to view or edit the config through the UI
`disableConfigurationForNonAdmin`	`boolean`	Optional	If 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.
`widgetsAlwaysUseProxy`	`boolean`	Optional	If 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.
`showSplashScreen`	`boolean`	Optional	If set to `true`, a loading screen will be shown. Defaults to `false`.
`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`.
`enableServiceWorker`	`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 `false` to disable all service workers.
`disableContextMenu`	`boolean`	Optional	If set to `true`, the custom right-click context menu will be disabled. Defaults to `false`.

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`	`boolean`	Optional	If 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`
`keycloak`	`object`	Optional	Config options to point Dashy to your Keycloak server. Requires `enableKeycloak: true`. See `auth.keycloak` for more info
`enableHeaderAuth`	`boolean`	Optional	If 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`
`headerAuth`	`object`	Optional	Config options to point Dashy to your headers for authentication. Requires `enableHeaderAuth: true`. See `auth.headerAuth` for more info
`enableOidc`	`boolean`	Optional	If 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`
`oidc`	`object`	Optional	Config options to point Dash to your OIDC configuration. Request `enableOidc: true`. See `auth.oidc` 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`.

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

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
`legacySupport`	`boolean`	Optional	If using Keycloak 17 or older, then set this to `true`

Field	Type	Required	Description
`userHeader`	`string`	Optional	The Header name which contains username (default: REMOTE_USER). Case insensitive
`proxyWhitelist`	`array`	Required	An array of Upstream proxy servers to expect authencticated requests from

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`
`searchBangs`	`object`	Optional	A 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=`)

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 be initially collapsed. Defaults to `false`
`hideFooter`	`boolean`	Optional	If set to `true`, the footer will not be visible. Defaults to `false`

Field	Type	Required	Description
`hideForUsers`	`string[]`	Optional	Current item will be visible to all users, except for those specified in this list
`showForUsers`	`string[]`	Optional	Current item will be hidden from all users, except for those specified in this list
`hideForGuests`	`boolean`	Optional	Current item will be visible for logged in users, but not for guests (see `appConfig.enableGuestAccess`). Defaults to `false`
`hideForKeycloakUsers`	`object`	Optional	Current item will be visible to all keycloak users, except for those configured via these groups and roles. See `hideForKeycloakUsers`
`showForKeycloakUsers`	`object`	Optional	Current item will be hidden from all keycloak users, except for those configured via these groups and roles. See `showForKeycloakUsers`

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`
`cutToHeight`	`boolean`	Optional	By default, sections will fill available space. Set this option to true to match section height with content height
`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 override 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 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`
`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`
`hideForKeycloakUsers`	`object`	Optional	Current section will be visible to all keycloak users, except for those configured via these groups and roles. See `hideForKeycloakUsers`
`showForKeycloakUsers`	`object`	Optional	Current section will be hidden from all keycloak users, except for those configured via these groups and roles. See `showForKeycloakUsers`

Field	Type	Required	Description
`groups`	`string[]`	Optional	Current Section or Item will be hidden or shown based on the user having any of the groups in this list
`roles`	`string[]`	Optional	Current Section or Item will be hidden or shown based on the user having any of the roles in this list

There are three ways to edit the config#

Tips#

Contents#

Top-Level Fields#

PageInfo#

pageInfo.navLinks (optional)#

pages[] (optional)#

appConfig (optional)#

appConfig.auth (optional)#

appConfig.auth.users (optional)#

appConfig.auth.keycloak (optional)#

appConfig.auth.headerAuth (optional)#

appConfig.auth.oidc (optional)#

appConfig.webSearch (optional)#

appConfig.hideComponents (optional)#

section#

section.item#

item.displayData (optional)#

section.widgets (optional)#

section.displayData (optional)#

section.icon and section.item.icon#

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

Notes#

Editing Config through the UI#

About YAML#

Config Saving Methods#

Preventing Changes#

Example#

`PageInfo`#

`pageInfo.navLinks` (optional)#

`pages[]` (optional)#

`appConfig` (optional)#

`appConfig.auth` (optional)#

`appConfig.auth.users` (optional)#

`appConfig.auth.keycloak` (optional)#

`appConfig.auth.headerAuth` (optional)#

`appConfig.auth.oidc` (optional)#

`appConfig.webSearch` (optional)#

`appConfig.hideComponents` (optional)#

`section`#

`section.item`#

`item.displayData` (optional)#

`section.widgets` (optional)#

`section.displayData` (optional)#

`section.icon` and `section.item.icon`#

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