mirror of
https://github.com/Lissy93/dashy.git
synced 2024-12-23 17:03:59 +03:00
📝 Adds Synk badge to readme, adds section docs, and updates configuring.md
This commit is contained in:
Alicia Sykes
parent
2b58b7b414
commit
266c37c326
68
README.md
68
README.md
@ -12,6 +12,7 @@
|
||||
|
||||
|
||||
|
||||
[]
|
||||
|
||||
## Features 🌈
|
||||
|
||||
@ -42,7 +43,7 @@
|
||||
|
||||
#### Recording
|
||||
<p align="center">
|
||||
<img width="800" src="https://i.ibb.co/L8YbNNc/dashy-demo2.gif" alt="Demo">
|
||||
<img width="800" src="https://i.ibb.co/L8YbNNc/dashy-demo2.gif" alt="Demo" />
|
||||
</p>
|
||||
|
||||
#### User Showcase
|
||||
@ -143,7 +144,7 @@ You may find these [example config](https://gist.github.com/Lissy93/000f712a5ce9
|
||||
|
||||
<p align="center">
|
||||
<a href="https://i.ibb.co/BVSHV1v/dashy-themes-slideshow.gif">
|
||||
<img alt="Example Themes" src="https://raw.githubusercontent.com/Lissy93/dashy/master/docs/assets/theme-slideshow.gif" width="400">
|
||||
<img alt="Example Themes" src="https://raw.githubusercontent.com/Lissy93/dashy/master/docs/assets/theme-slideshow.gif" width="400" />
|
||||
</a>
|
||||
</p>
|
||||
|
||||
@ -204,6 +205,16 @@ appConfig:
|
||||
```
|
||||
At present, access control is handled on the frontend, and therefore in security-critical situations, it is recommended to use an alternate method for authentication, such as [Authelia](https://www.authelia.com/), a VPN or web server and firewall rules.
|
||||
|
||||
<p align="center">
|
||||
<img
|
||||
title="Example login screen, using Vapourwave theme"
|
||||
alt="Example login screen, using Vapourwave theme"
|
||||
src="https://i.ibb.co/K52YL1g/dashy-login-form.png"
|
||||
width="400"
|
||||
/>
|
||||
</p>
|
||||
|
||||
|
||||
**[⬆️ Back to Top](#dashy)**
|
||||
|
||||
---
|
||||
@ -217,7 +228,7 @@ Dashy has an optional feature that can display a small icon next to each of your
|
||||
By default, this feature is off, but you can enable it globally by setting `appConfig.statusCheck: true`, or enable/ disable it for an individual item, with `item[n].statusCheck`. You can also specify an time interval in seconds under `appConfig.statusCheckInterval`, which will determine how often to recheck services, if this value is `0`, then status is only checked on initial page load, this is default behavior.
|
||||
|
||||
<p align="center">
|
||||
<img alt="Status Checks demo" src="https://raw.githubusercontent.com/Lissy93/dashy/master/docs/assets/status-check-demo.gif" width="600">
|
||||
<img alt="Status Checks demo" src="https://raw.githubusercontent.com/Lissy93/dashy/master/docs/assets/status-check-demo.gif" width="600" />
|
||||
</p>
|
||||
|
||||
**[⬆️ Back to Top](#dashy)**
|
||||
@ -242,7 +253,7 @@ The modal and workspace views work by rendering the target application in an ifr
|
||||
|
||||
Here's a quick demo of the workspace view:
|
||||
<p align="center">
|
||||
<img alt="Workspace view demo" src="https://raw.githubusercontent.com/Lissy93/dashy/master/docs/assets/workspace-demo.gif" width="600">
|
||||
<img alt="Workspace view demo" src="https://raw.githubusercontent.com/Lissy93/dashy/master/docs/assets/workspace-demo.gif" width="600" />
|
||||
</p>
|
||||
|
||||
**[⬆️ Back to Top](#dashy)**
|
||||
@ -254,13 +265,60 @@ Here's a quick demo of the workspace view:
|
||||
From the Settings Menu in Dashy, you can download, backup, edit and rest your config. An interactive editor makes editing the config file easy, it will tell you if you've got any errors. After making your changes, you can either apply them locally, or export into your main config file. After saving to the config file to the disk, the app will need to be rebuilt. This will happen automatically, but may take a few minutes. You can also manually trigger a rebuild from the Settings Menu. A full list of available config options can be found [here](./docs/configuring.md). It's recommend to make a backup of your configuration, as you can then restore it into a new instance of Dashy, without having to set it up again. [json2yaml](https://www.json2yaml.com/) is very useful for converting between YAML to JSON and visa versa.
|
||||
|
||||
<p align="center">
|
||||
<img alt="Workspace view demo" src="https://raw.githubusercontent.com/Lissy93/dashy/master/docs/assets/config-editor-demo.gif" width="600">
|
||||
<img alt="Workspace view demo" src="https://raw.githubusercontent.com/Lissy93/dashy/master/docs/assets/config-editor-demo.gif" width="600" />
|
||||
</p>
|
||||
|
||||
**[⬆️ Back to Top](#dashy)**
|
||||
|
||||
---
|
||||
|
||||
## Sections & Items 🗃️
|
||||
|
||||
Dashy is made up of a series of sections, each containing a series of items.
|
||||
|
||||
A section an be collapsed by clicking on it's name. This will cause only the title button to be visible until clicked, which is useful for particularly long sections, or those containing less-used apps. The collapse state for each section will be remembered for the next time you visit.
|
||||
|
||||
From the UI, you can also choose a layout, either `grid`, `horizontal` or `vertical`, as well as set the size for items, either `small`, `medium` or `large`, and of course set a theme using the dropdown. All settings specified here will be stored in your browsers local storage, and so won't persist across devices, if you require this then you must set these in the config file instead.
|
||||
|
||||
Within each section, you can set custom layout properties with under `displayData`. For example, you can make a given section double the width by making is span 2 columns with `cols: 2`, or specify how many rows it should span with `rows`. You can also set the layout for items within a given section here, for example, use `itemCountX` to define how many items will be on each row within the section. Sections can also have a custom color, specified as a hex code and defined using the `color` attribute. For full options for items, see the [`section.displayData` docs](https://github.com/Lissy93/dashy/blob/master/docs/configuring.md#sectiondisplaydata-optional)
|
||||
|
||||
Items also have some optional config attributes. As well as `title`, `description`, `URL` and `icon`, you can also specify a specific opening method (`target`), and configure status checks (`statusCheck: true/false`, `statusCheckUrl` and `statusCheckHeaders`), and modify appearance with `color` and `backgroundColor`. For full options for items, see the [`section.item` docs](https://github.com/Lissy93/dashy/blob/master/docs/configuring.md#sectionitem)
|
||||
|
||||
|
||||
**[⬆️ Back to Top](#dashy)**
|
||||
|
||||
---
|
||||
|
||||
## Setting Dashboard Info 🌳
|
||||
|
||||
Page settings are defined under [`pageInfo`](https://github.com/Lissy93/dashy/blob/master/docs/configuring.md#pageinfo). Here you can set things like title, sub-title, navigation links, footer text, etc
|
||||
|
||||
Custom links for the navigation menu are defined under [`pageInfo.navLinks`](https://github.com/Lissy93/dashy/blob/master/docs/configuring.md#pageinfonavlinks-optional).
|
||||
|
||||
You can display either custom text or HTML in the footer, using the `pageInfo.footerText` attribute.
|
||||
|
||||
It's also possible to hide parts of the page that you do not need (e.g. navbar, footer, search, heading, etc). This is done using the [`appConfig.hideComponents`](https://github.com/Lissy93/dashy/blob/master/docs/configuring.md#appconfighidecomponents-optional) attribute.
|
||||
|
||||
For example, a `pageInfo` section might look something like this:
|
||||
|
||||
```yaml
|
||||
pageInfo:
|
||||
title: Home Lab
|
||||
description: Dashy
|
||||
navLinks:
|
||||
- title: Home
|
||||
path: /
|
||||
- title: Server Monitoring
|
||||
path: https://server-start.local
|
||||
- title: Start Page
|
||||
path: https://start-page.local
|
||||
footerText: 'Built with Dashy, by <a href="https://aliciasykes.com">Alicia Sykes</a>, 2021'
|
||||
```
|
||||
|
||||
**[⬆️ Back to Top](#dashy)**
|
||||
|
||||
---
|
||||
|
||||
## Developing 🧱
|
||||
|
||||
> For full development documentation, see: [**Developing**](./docs/developing.md)
|
||||
|
||||
@ -2,24 +2,23 @@
|
||||
|
||||
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 new to YAML, it's pretty straight-forward. The format is exactly the same as that of JSON, but instead of using curley braces, structure is denoted using whitespace. This [quick guide](https://linuxhandbook.com/yaml-basics/) should get you up to speed in a few minutes, for more advanced topics take a look at this [Wikipedia article](https://en.wikipedia.org/wiki/YAML) and for some practicle examples, the [Azure pipelines schema](https://docs.microsoft.com/en-us/azure/devops/pipelines/yaml-schema?view=azure-devops&tabs=schema%2Cparameter-schema) may be useful.
|
||||
|
||||
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).
|
||||
|
||||
There's a couple of things to remember, before getting started:
|
||||
- After modifying your config, the app needs to be recompiled, run `yarn build` (this happens automatically in newer versions)
|
||||
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`
|
||||
- Any which are only saved locally through the UI need to be exported into this file, in order for them to persist across devices
|
||||
- After modifying your config, the app needs to be recompiled, by running `yarn build` - this happens automatically whilst the app is running
|
||||
- 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.
|
||||
- All fields are optional, unless otherwise stated.
|
||||
|
||||
### 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](https://linuxhandbook.com/yaml-basics/) should get you up to speed in a few minutes, for more advanced topics take a look at this [Wikipedia article](https://en.wikipedia.org/wiki/YAML) and for some practicle examples, the [Azure pipelines schema](https://docs.microsoft.com/en-us/azure/devops/pipelines/yaml-schema?view=azure-devops&tabs=schema%2Cparameter-schema) may be useful.
|
||||
|
||||
### 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 to 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.
|
||||
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, then 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.
|
||||
|
||||
It is recommended to make a backup of your config file.
|
||||
|
||||
All fields are optional, unless otherwise stated.
|
||||
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.
|
||||
|
||||
### Top-Level Fields
|
||||
|
||||
@ -60,7 +59,7 @@ All fields are optional, unless otherwise stated.
|
||||
**`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`** | `string` | _Optional_ | Which service to use to resolve favicons. Set to `local` to do this locally, without using an API. Available options are: `local`, `faviconkit`, `google`, `clearbit`, `webmasterapi` and `allesedv`. Defaults to `faviconkit`. See [Icons](/docs/icons.md#favicons) for more info
|
||||
**`faviconApi`** | `string` | _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](/docs/icons.md#favicons) for more info
|
||||
**`auth`** | `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. Note authentication is done on the client side, and so if your instance of Dashy is exposed to the internet, it is recommend to configure your web server to handle this. See [`auth`](#appconfigauth-optional)
|
||||
**`layout`** | `string` | _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`** | `string` | _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.
|
||||
@ -183,5 +182,9 @@ sections: # An array of sections
|
||||
|
||||
For more example config files, see: [this gist](https://gist.github.com/Lissy93/000f712a5ce98f212817d20bc16bab10)
|
||||
|
||||
If you need any help, feel free to [Raise an Issue](https://github.com/Lissy93/dashy/issues/new?assignees=Lissy93&labels=%F0%9F%A4%B7%E2%80%8D%E2%99%82%EF%B8%8F+Question&template=question.md&title=%5BQUESTION%5D) or [Start a Discussion](https://github.com/Lissy93/dashy/discussions)
|
||||
|
||||
Happy Configuring 🤓🔧
|
||||
|
||||
**[⬆️ Back to Top](#configuring)**
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user