mirror of https://github.com/lissy93/dashy
📝 Updes details in configuring and development docs
This commit is contained in:
Alicia Sykes
parent
f7c3c80b33
commit
61bbfcb885
|
|
@ -1,45 +1,53 @@
|
|||
# Configuring
|
||||
|
||||
All app configuration is specified in [`/public/conf.yml`](https://github.com/Lissy93/dashy/blob/master/public/conf.yml) which is in [YAML Format](https://yaml.org/) format. Changes can also be made [directly through the UI](#editing-config-through-the-ui) and previewed live, from here you can also export, backup, reset, validate and download your configuration file.
|
||||
All app configuration is specified in [`/public/conf.yml`](https://github.com/Lissy93/dashy/blob/master/public/conf.yml) which is in [YAML Format](https://yaml.org/) 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](#editing-config-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](https://github.com/coder/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](https://gist.github.com/Lissy93/000f712a5ce98f212817d20bc16bab10)
|
||||
- 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](./docs/backup-restore.md) feature.
|
||||
- You can make use of YAML features, like anchors, comments, multi-line strings, etc to reuse attributes and keep your config file readable
|
||||
- All fields are optional, unless otherwise stated.
|
||||
|
||||
The following file provides a reference of all supported configuration options.
|
||||
|
||||
---
|
||||
|
||||
#### Contents
|
||||
|
||||
- [**`pageInfo`**](#pageinfo) - Header text, footer, title, navigation, etc
|
||||
- [`navLinks`](#pageinfonavlinks-optional) - Navigation bar items and links
|
||||
- [`navLinks`](#pageinfonavlinks-optional) - Links to display in the navigation bar
|
||||
- [**`appConfig`**](#appconfig-optional) - Main application settings
|
||||
- [`webSearch`](#appconfigwebsearch-optional) - Configure web search engine options
|
||||
- [`hideComponents`](#appconfighidecomponents-optional) - Show/ hide page components
|
||||
- [`auth`](#appconfigauth-optional) - Built-in authentication setup
|
||||
- [`users`](#appconfigauthusers-optional) - Setup for simple auth
|
||||
- [`keycloak`](#appconfigauthkeycloak-optional) - Auth using Keycloak
|
||||
- [`webSearch`](#appconfigwebsearch-optional) - Configure web search engine options
|
||||
- [`hideComponents`](#appconfighidecomponents-optional) - Show/ hide page components
|
||||
- [`auth`](#appconfigauth-optional) - Built-in authentication setup
|
||||
- [`users`](#appconfigauthusers-optional) - List or users (for simple auth)
|
||||
- [`keycloak`](#appconfigauthkeycloak-optional) - Auth config for Keycloak
|
||||
- [**`sections`**](#section) - List of sections
|
||||
- [`displayData`](#sectiondisplaydata-optional) - Section display settings
|
||||
- [`icon`](#sectionicon-and-sectionitemicon) - Icon for a section
|
||||
- [`items`](#sectionitem) - List of items
|
||||
- [`icon`](#sectionicon-and-sectionitemicon) - Icon for an item
|
||||
- [`displayData`](#sectiondisplaydata-optional) - Section display settings
|
||||
- [`show/hideForKeycloakUsers`](#sectiondisplaydatahideforkeycloakusers-and-sectiondisplaydatashowforkeycloakusers) - Set user controls
|
||||
- [`icon`](#sectionicon-and-sectionitemicon) - Icon for a section
|
||||
- [`items`](#sectionitem) - List of items
|
||||
- [`icon`](#sectionicon-and-sectionitemicon) - Icon for an item
|
||||
- [`widgets`](#sectionwidget-optional) - List of widgets
|
||||
- [**Notes**](#notes)
|
||||
- [Editing Config through the UI](#editing-config-through-the-ui)
|
||||
- [About YAML](#about-yaml)
|
||||
- [Config Saving Methods](#config-saving-methods)
|
||||
- [Preventing Changes](#preventing-changes-being-written-to-disk)
|
||||
- [About YAML](#about-yaml)
|
||||
- [Config Saving Methods](#config-saving-methods)
|
||||
- [Preventing Changes](#preventing-changes-being-written-to-disk)
|
||||
- [Example](#example)
|
||||
|
||||
---
|
||||
|
||||
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](https://gist.github.com/Lissy93/000f712a5ce98f212817d20bc16bab10)
|
||||
- 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](./docs/backup-restore.md) 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**
|
||||
|
|
|
|||
|
|
@ -94,18 +94,34 @@ If you are not comfortable with making pull requests, or do not want to modify t
|
|||
|
||||
# Adding a new option in the config file
|
||||
|
||||
This section is for, if you're adding a new component or setting, that requires an additional item to be added to the users config file.
|
||||
This section is for, adding a new setting to the config file.
|
||||
|
||||
All of the users config is specified in `./public/conf.yml` - see [Configuring Docs](./configuring.md) for info.
|
||||
Before adding a new option in the config file, first ensure that there is nothing similar available, that is is definitely necessary, it will not conflict with any other options and most importantly that it will not cause any breaking changes. Ensure that you choose an appropriate and relevant section to place it under.
|
||||
It's important to first ensure that there isn't a similar option already available, the new option is definitely necessary, and most importantly that it is fully backwards compatible.
|
||||
|
||||
Next decide the most appropriate place for your attribute:
|
||||
Next choose the appropriate section to place it under
|
||||
- Application settings should be located under `appConfig`
|
||||
- Page info (such as text and metadata) should be under `pageInfo`
|
||||
- Data relating to specific sections should be under `section[n].displayData`
|
||||
- And for setting applied to specific items, it should be under `item[n]`
|
||||
- Settings applied to specific items or widgets, should be under `item[n]` or `widget[n]`
|
||||
|
||||
In order for the user to be able to add your new attribute using the Config Editor, and for the build validation to pass, your attribute must be included within the [ConfigSchema](https://github.com/Lissy93/dashy/blob/master/src/utils/ConfigSchema.js). You can read about how to do this on the [ajv docs](https://ajv.js.org/json-schema.html). Give your property a type and a description, as well as any other optional fields that you feel are relevant. For example:
|
||||
For example, if your option is added under `appConfig`, you can access it within your component using the `$store`, this is typically placed in a computed property, e.g:
|
||||
|
||||
```javascript
|
||||
computed: {
|
||||
appConfig() {
|
||||
return this.$store.getters.appConfig;
|
||||
},
|
||||
...
|
||||
},
|
||||
```
|
||||
|
||||
Then, where you want get the users value within your component, use something like: `this.appConfig.myProperty`. Don't forget to have a fallback or default for then the user hasn't specified it.
|
||||
|
||||
If you have a default fallback value, then this would typically be specified in the [`defaults.js`](https://github.com/Lissy93/dashy/blob/master/src/utils/defaults.js) file.
|
||||
|
||||
You will now need to add the definition of your new attribute into the [ConfigSchema](https://github.com/Lissy93/dashy/blob/master/src/utils/ConfigSchema.js). This will make it available in the UI config editor, and also ensure that the config validation check doesn't fail.
|
||||
For example:
|
||||
|
||||
```json
|
||||
"fontAwesomeKey": {
|
||||
|
|
@ -124,24 +140,21 @@ or
|
|||
}
|
||||
```
|
||||
|
||||
Next, if you're property should have a default value, then add it to [`defaults.js`](https://github.com/Lissy93/dashy/blob/master/src/utils/defaults.js). This ensures that nothing will break if the user does not use your property, and having all defaults together keeps things organised and easy to manage.
|
||||
|
||||
If your property needs additional logic for fetching, setting or processing, then you can add a helper function within [`ConfigHelpers.js`](https://github.com/Lissy93/dashy/blob/master/src/utils/ConfigHelpers.js).
|
||||
|
||||
Finally, add your new property to the [`configuring.md`](./configuring.md) API docs. Put it under the relevant section, and be sure to include field name, data type, a description and mention that it is optional. If your new feature needs more explaining, then you can also document it under the relevant section elsewhere in the documentation.
|
||||
|
||||
Checklist:
|
||||
- [ ] Ensure the new attribute is actually necessary, and nothing similar already exists
|
||||
- [ ] Update the [Schema](https://github.com/Lissy93/dashy/blob/master/src/utils/ConfigSchema.js) with the parameters for your new option
|
||||
- [ ] Set a default value (if required) within [`defaults.js`](https://github.com/Lissy93/dashy/blob/master/src/utils/defaults.js)
|
||||
- [ ] Document the new value in [`configuring.md`](./configuring.md)
|
||||
- [ ] Test that the reading of the new attribute is properly handled, and will not cause any errors when it is missing or populated with an unexpected value
|
||||
- [ ] If required, set a default or fallback value (usually in [`defaults.js`](https://github.com/Lissy93/dashy/blob/master/src/utils/defaults.js))
|
||||
- [ ] Document the new value in [`configuring.md`](./configuring.md), and if required under the relevant section in the docs
|
||||
- [ ] Ensure your changes are backwards compatible, and that nothing breaks if the attribute isn't specified
|
||||
|
||||
---
|
||||
|
||||
## Updating Dependencies
|
||||
|
||||
Running `yarn upgrade` will updated all dependencies based on the ranges specified in the `package.json`. The `yarn.lock` file will be updated, as will the contents of `./node_modules`, for more info, see the [yarn upgrade documentation](https://classic.yarnpkg.com/en/docs/cli/upgrade/). It is important to thoroughly test after any big dependency updates.
|
||||
Running `yarn upgrade` will updated all dependencies based on the ranges specified in the `package.json`. The `yarn.lock` file will be updated, as will the contents of `./node_modules`, for more info, see the [yarn upgrade documentation](https://classic.yarnpkg.com/en/docs/cli/upgrade/). [`npm-check-updates`](https://github.com/raineorshine/npm-check-updates) is a useful tool to help with this.
|
||||
It is important to thoroughly test after any big dependency updates.
|
||||
|
||||
---
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue