mirror of
https://github.com/Lissy93/dashy.git
synced 2025-07-27 15:44:27 +02:00
🔄 Sync docs from master
This commit is contained in:
Alicia Sykes
parent
c25e346b35
commit
2416b53c45
File diff suppressed because one or more lines are too long
|
Before Width: | Height: | Size: 1.0 MiB After Width: | Height: | Size: 1.7 MiB |
1
docs/assets/repo-visualization.svg
Normal file
1
docs/assets/repo-visualization.svg
Normal file
File diff suppressed because one or more lines are too long
|
After Width: | Height: | Size: 70 KiB |
@ -2,24 +2,40 @@
|
||||
|
||||
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.
|
||||
|
||||
---
|
||||
|
||||
#### Contents
|
||||
|
||||
- [**`pageInfo`**](#pageinfo) - Header text, footer, title, navigation, etc
|
||||
- [`navLinks`](#pageinfonavlinks-optional) - Navigation bar items and links
|
||||
- [**`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
|
||||
- [**`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
|
||||
- [**Notes**](#notes)
|
||||
- [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) feature.
|
||||
- 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) 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.
|
||||
|
||||
### 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).
|
||||
|
||||
### 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.
|
||||
---
|
||||
|
||||
### Top-Level Fields
|
||||
|
||||
@ -60,6 +76,7 @@ To disallow any changes from being written to disk via the UI config editor, set
|
||||
**`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`](#appconfigwebsearch-optional)
|
||||
**`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`)
|
||||
@ -77,8 +94,9 @@ To disallow any changes from being written to disk via the UI config editor, set
|
||||
**`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](https://github.com/getsentry/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](https://docs.sentry.io/product/sentry-basics/dsn-explainer/). 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.
|
||||
**`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 `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](#)**
|
||||
@ -86,7 +104,7 @@ To disallow any changes from being written to disk via the UI config editor, set
|
||||
### `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`](#appconfigauthusers-optional). <br />**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](/docs/authentication#alternative-authentication-methods).
|
||||
**`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`](#appconfigauthusers-optional). <br/>**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](/docs/authentication#alternative-authentication-methods).
|
||||
**`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`](#appconfigauthkeycloak-optional) 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`.
|
||||
@ -115,6 +133,16 @@ For more info, see the **[Authentication Docs](/docs/authentication)**
|
||||
|
||||
**[⬆️ Back to Top](#)**
|
||||
|
||||
**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=`)
|
||||
|
||||
|
||||
**[⬆️ Back to Top](#)**
|
||||
|
||||
### `appConfig.hideComponents` _(optional)_
|
||||
|
||||
@ -154,6 +182,7 @@ For more info, see the **[Authentication Docs](/docs/authentication)**
|
||||
**`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
|
||||
@ -164,12 +193,13 @@ For more info, see the **[Authentication Docs](/docs/authentication)**
|
||||
|
||||
**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`
|
||||
**`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;`
|
||||
**`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
|
||||
**`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`
|
||||
@ -183,10 +213,25 @@ For more info, see the **[Authentication Docs](/docs/authentication)**
|
||||
|
||||
**Field** | **Type** | **Required**| **Description**
|
||||
--- | --- | --- | ---
|
||||
**`icon`** | `string` | _Optional_ | The icon for a given item or section. Can be a font-awesome icon, favicon, remote URL or local URL. If set to `favicon`, the icon will be automatically fetched from the items website URL. To use font-awesome, specify the category, followed by the icon name, e.g. `fas fa-rocket`, `fab fa-monero` or `fal fa-duck` - note that to use pro icons, you mut specify `appConfig.fontAwesomeKey`. Similarly, you can also use [simple-icons](https://simpleicons.org/) by setting icon to `si-[icon-name]` or [material-design-icons](https://dev.materialdesignicons.com/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.
|
||||
**`icon`** | `string` | _Optional_ | The icon for a given item or section. See [Icon Docs](/docs/icons) 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](https://simpleicons.org/) by setting icon to `si-[icon-name]` or [material-design-icons](https://dev.materialdesignicons.com/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](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).
|
||||
|
||||
### 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
|
||||
|
||||
```yaml
|
||||
|
||||
@ -20,7 +20,7 @@ Dashy now has a [Showcase](https://github.com/Lissy93/dashy/blob/master/docs/sho
|
||||
|
||||
## Improve the Docs
|
||||
Found a typo, or something that isn't as clear as it could be? Maybe I've missed something off altogether, or you hit a roadblock that took you a while to figure out. Submitting a pull request to add to or improve the documentation will help future users get Dashy up and running more easily.
|
||||
All content is located either in the README or [`/docs/`](/docs) directory, and synced to the Wiki and website using a GH action (workflows/wiki-sync.yml).
|
||||
All content is located either in the [`./README.md`](/README) or [`/docs/`](/docs) directory, and synced to the Wiki and website using a GH [action](/actions/workflows/wiki-sync.yml).
|
||||
|
||||
## Raise a bug
|
||||
If you've found a bug, then please do raise it as an issue. This will help me know if there's something that needs fixing. Try and include as much detail as possible, such as your environment, steps to reproduce, any console output and maybe an example screenshot or recording if necessary.
|
||||
@ -89,7 +89,7 @@ If you've enjoyed Dashy, you can follow the me to get updates about other projec
|
||||
[](https://aliciasykes.com)
|
||||
[](https://notes.aliciasykes.com/)
|
||||
|
||||
If you like, you could also consider [subscribing to my mailing list](https://notes.aliciasykes.com/subscribe) for very occasional blog post updates, or even [nominating me (`@lissy93`)](https://stars.github.com/nominate/) on the GitHub Star Programme.
|
||||
If you like, you could also consider [subscribing to my mailing list](https://notes.aliciasykes.com/subscribe) for very occasional blog post updates.
|
||||
|
||||
---
|
||||
|
||||
@ -97,7 +97,7 @@ If you like, you could also consider [subscribing to my mailing list](https://no
|
||||
|
||||
For a full list of Dashy's contributors, see the [Credits Page](/docs/credits)
|
||||
|
||||
|
||||
[](/docs/credits)
|
||||
|
||||
### Star-Gazers Over Time
|
||||
|
||||
|
||||
@ -50,21 +50,28 @@
|
||||
<sub><b>Snyk Bot</b></sub>
|
||||
</a>
|
||||
</td>
|
||||
<td align="center">
|
||||
<a href="https://github.com/onedr0p">
|
||||
<img src="https://avatars.githubusercontent.com/u/213795?v=4" width="80;" alt="onedr0p"/>
|
||||
<br />
|
||||
<sub><b>ᗪєνιη ᗷυнʟ</b></sub>
|
||||
</a>
|
||||
</td>
|
||||
<td align="center">
|
||||
<a href="https://github.com/UrekD">
|
||||
<img src="https://avatars.githubusercontent.com/u/38784343?v=4" width="80;" alt="UrekD"/>
|
||||
<br />
|
||||
<sub><b>UrekD</b></sub>
|
||||
</a>
|
||||
</td>
|
||||
<td align="center">
|
||||
<a href="https://github.com/onedr0p">
|
||||
<img src="https://avatars.githubusercontent.com/u/213795?v=4" width="80;" alt="onedr0p"/>
|
||||
<br />
|
||||
<sub><b>ᗪєνιη ᗷυнʟ</b></sub>
|
||||
</a>
|
||||
</td></tr>
|
||||
<tr>
|
||||
<td align="center">
|
||||
<a href="https://github.com/daentech">
|
||||
<img src="https://avatars.githubusercontent.com/u/358678?v=4" width="80;" alt="daentech"/>
|
||||
<br />
|
||||
<sub><b>Dan Gilbert</b></sub>
|
||||
</a>
|
||||
</td>
|
||||
<td align="center">
|
||||
<a href="https://github.com/BeginCI">
|
||||
<img src="https://avatars.githubusercontent.com/u/57495754?v=4" width="80;" alt="BeginCI"/>
|
||||
@ -79,6 +86,13 @@
|
||||
<sub><b>DeepSource Bot</b></sub>
|
||||
</a>
|
||||
</td>
|
||||
<td align="center">
|
||||
<a href="https://github.com/FormatToday">
|
||||
<img src="https://avatars.githubusercontent.com/u/20515769?v=4" width="80;" alt="FormatToday"/>
|
||||
<br />
|
||||
<sub><b>FormatToday</b></sub>
|
||||
</a>
|
||||
</td>
|
||||
<td align="center">
|
||||
<a href="https://github.com/turnrye">
|
||||
<img src="https://avatars.githubusercontent.com/u/701035?v=4" width="80;" alt="turnrye"/>
|
||||
@ -153,6 +167,27 @@
|
||||
<sub><b>Snyk Bot</b></sub>
|
||||
</a>
|
||||
</td>
|
||||
<td align="center">
|
||||
<a href="https://github.com/netlify">
|
||||
<img src="https://avatars.githubusercontent.com/u/7892489?v=4" width="80;" alt="netlify"/>
|
||||
<br />
|
||||
<sub><b>Netlify</b></sub>
|
||||
</a>
|
||||
</td>
|
||||
<td align="center">
|
||||
<a href="https://github.com/viezly">
|
||||
<img src="https://avatars.githubusercontent.com/u/78649443?v=4" width="80;" alt="viezly"/>
|
||||
<br />
|
||||
<sub><b>Viezly</b></sub>
|
||||
</a>
|
||||
</td>
|
||||
<td align="center">
|
||||
<a href="https://github.com/muse-dev">
|
||||
<img src="https://avatars.githubusercontent.com/u/42072939?v=4" width="80;" alt="muse-dev"/>
|
||||
<br />
|
||||
<sub><b>MuseDev</b></sub>
|
||||
</a>
|
||||
</td>
|
||||
<td align="center">
|
||||
<a href="https://github.com/github-actions[bot]">
|
||||
<img src="https://avatars.githubusercontent.com/in/15368?v=4" width="80;" alt="github-actions[bot]"/>
|
||||
@ -162,20 +197,24 @@
|
||||
</td></tr>
|
||||
</table>
|
||||
|
||||
## Dependencies 🔗
|
||||
> The above section is auto-generated, using [contribute-list](https://github.com/marketplace/actions/contribute-list) by @akhilmhdh.
|
||||
|
||||
---
|
||||
|
||||
## Dependencies
|
||||
|
||||
This app definitely wouldn't have been quite so possible without the making use of the following package and components. Full credit and big kudos to their respective authors, who've done an amazing job in building and maintaining them. For a full breakdown of dependency licenses, please see [Legal](https://github.com/Lissy93/dashy/blob/master/.github/LEGAL)
|
||||
|
||||
##### Core
|
||||
At it's core, the application uses [Vue.js](https://github.com/vuejs/vue), as well as it's services. Styling is done with [SCSS](https://github.com/sass/sass), JavaScript is currently [Babel](https://github.com/babel/babel), (but I am in the process of converting to [TypeScript](https://github.com/Microsoft/TypeScript)). Linting is done with [ESLint](https://github.com/eslint/eslint) and [Prettier](https://prettier.io/), both following the [AirBnB Styleguide](https://github.com/airbnb/javascript). The config is defined in [YAML](https://github.com/yaml/yaml), and there is a simple [Node.js](https://github.com/nodejs/node) server to serve up the static app and the optional API endpoints.
|
||||
#### Core
|
||||
At it's core, the application uses [**Vue.js**](https://github.com/vuejs/vue), as well as it's services with [**VueX**](https://vuex.vuejs.org/) for state management. Styling is done with [**SCSS**](https://github.com/sass/sass), JavaScript is currently [**Babel**](https://github.com/babel/babel), (but I am in the process of converting to [**TypeScript**](https://github.com/Microsoft/TypeScript)). Linting is done with [**ESLint**](https://github.com/eslint/eslint) and [**Prettier**](https://prettier.io/), both following the [**AirBnB Styleguide**](https://github.com/airbnb/javascript). The config is defined in [**YAML**](https://github.com/yaml/yaml), with a simple [**Node.js**](https://github.com/nodejs/node) server to serve up the static app and the optional API endpoints, and container deployment is done with [**Docker**](https://www.docker.com/).
|
||||
|
||||
##### Utilities
|
||||
#### Utilities
|
||||
- [`crypto-js`](https://github.com/brix/crypto-js) - Encryption implementations by @evanvosberg and community `MIT`
|
||||
- [`axios`](https://github.com/axios/axios) - Promise based HTTP client by @mzabriskie and community `MIT`
|
||||
- [`ajv`](https://github.com/ajv-validator/ajv) - JSON schema Validator by @epoberezkin and community `MIT`
|
||||
- [`vue-i18n`](https://github.com/kazupon/vue-i18n) - Internationalization plugin by @kazupon and community `MIT`
|
||||
- [`i18n`](https://github.com/kazupon/vue-i18n) - Internationalization plugin by @kazupon and community `MIT`
|
||||
|
||||
##### Frontend Components
|
||||
#### Frontend Components
|
||||
- [`vue-select`](https://github.com/sagalbot/vue-select) - Dropdown component by @sagalbot `MIT`
|
||||
- [`vue-js-modal`](https://github.com/euvl/vue-js-modal) - Modal component by @euvl `MIT`
|
||||
- [`v-tooltip`](https://github.com/Akryum/v-tooltip) - Tooltip component by @Akryum `MIT`
|
||||
@ -185,12 +224,33 @@ At it's core, the application uses [Vue.js](https://github.com/vuejs/vue), as we
|
||||
- [`vue-toasted`](https://github.com/shakee93/vue-toasted) - Toast notification component by @shakee93 `MIT`
|
||||
- [`vue-swatches`](https://github.com/saintplay/vue-swatches) - Color palete picker by @saintplay `MIT`
|
||||
|
||||
##### Backup & Sync Server
|
||||
Although the app is purely frontend, there is an optional cloud backup and restore feature. This is built as a serverless function on [Cloudflare workers](https://workers.cloudflare.com/) using [KV](https://developers.cloudflare.com/workers/runtime-apis/kv) and [web crypto](https://developers.cloudflare.com/workers/runtime-apis/web-crypto)
|
||||
#### Backup & Sync Server
|
||||
Although the app is purely frontend, there is an optional cloud sync feature, for off-site backup and restore. This is built as a serverless function on [Cloudflare workers](https://workers.cloudflare.com/) using [KV](https://developers.cloudflare.com/workers/runtime-apis/kv) and [web crypto](https://developers.cloudflare.com/workers/runtime-apis/web-crypto)
|
||||
|
||||
##### External Services
|
||||
#### External Services
|
||||
The 1-Click deploy demo uses [Play-with-Docker Labs](https://play-with-docker.com/). Code is hosted on [GitHub](https://github.com), Docker images are hosted on [DockerHub](https://hub.docker.com/), and the demos are hosted on [Netlify](https://www.netlify.com/).
|
||||
|
||||
#### Actions
|
||||
This repo makes heavy use of [GitHub actions](https://github.com/features/actions) to run automated workflows. The following base actions are totally awesome, and have been extremely useful. Full credit to their respective authors
|
||||
|
||||
- [`action-autotag`](https://github.com/butlerlogic/action-autotag) by @butlerlogic - Tags new versions when app version changes
|
||||
- [`action-wiki-sync`](https://github.com/joeizzard/action-wiki-sync) by @joeizzard - Copies the markdown docs to the GH wiki
|
||||
- [`contributors-list`](https://github.com/bubkoo/contributors-list) by @bubkoo - Generates contributors SVG
|
||||
- [`contributors-readme-action`](https://github.com/akhilmhdh/contributors-readme-action) by @akhilmhdh - Inserts contributors into credits
|
||||
- [`create-pull-request`](https://github.com/eter-evans/create-pull-request) by @eter-evans - Creates pull request
|
||||
- [`github-pages-deploy-action`](https://github.com/JamesIves/github-pages-deploy-action) by @JamesIves - Deploy app to GH pages
|
||||
- [`github-release-commenter`](https://github.com/apexskier/github-release-commenter) by @apexskier - Updates issues when fix is released
|
||||
- [`github-sponsors-readme-action`](https://github.com/JamesIves/github-sponsors-readme-action) by @JamesIves - Inserts sponsors into credits
|
||||
- [`is-sponsor-label-action`](https://github.com/JasonEtco/is-sponsor-label-action) by @JasonEtco - Label sponsors, for priority support
|
||||
- [`issues-translate-action`](https://github.com/tomsun28/issues-translate-action) by @tomsun28 - Translates non-English issues and comments
|
||||
- [`misspell-fixer-action`](https://github.com/sobolevn/misspell-fixer-action) by @sobolevn - Finds and fixes typos
|
||||
- [`please-star-first`](https://github.com/uhyo/please-star-first) by @uhyo - Closes certain issues by non-stargazers
|
||||
- [`pr-commenter-action`](https://github.com/exercism/pr-commenter-action) by @exercism - Adds info comments to PR based on the files changed
|
||||
- [`snyk note`](https://github.com/snyk/actions/node) by @snyk - Reports vulnerabilities in the code or dependencies
|
||||
- [`todo-to-issue-action`](https://github.com/alstr/todo-to-issue-action) by @alstr - Opens issues from todos in the code
|
||||
- [`yarn-lock-changes`](https://github.com/Simek/yarn-lock-changes) by @Simek - Outputs dependency changes in PR
|
||||
|
||||
---
|
||||
|
||||
> This page is auto-generated, using [contribute-list](https://github.com/marketplace/actions/contribute-list) by @akhilmhdh.
|
||||
## You!
|
||||
Would you like to be listed here? Whatever your skill set, Dashy needs people like you to help support future development. Check out the [Contributing Page](/docs/contributing) for ways that you can get involved. Huge thank you to everyone who has already contributed! 💖
|
||||
|
||||
@ -29,8 +29,7 @@ Once you've got Dashy up and running, you'll want to configure it with your own
|
||||
|
||||
|
||||
|
||||
](https://hub.docker.com/r/lissy93/dashy)
|
||||
|
||||
](https://hub.docker.com/r/lissy93/dashy)<br/>
|
||||
**Status**: [
|
||||
|
||||
|
||||
|
||||
@ -2,14 +2,24 @@
|
||||
# Developing
|
||||
|
||||
This article outlines how to get Dashy running in a development environment, and outlines the basics of the architecture.
|
||||
If you're adding new features, you may want to check out the [Development Guides](/docs/development-guides) docs, for tutorials covering basic tasks.
|
||||
If you're adding new features, you may want to check out the [Development Guides](./docs/development-guides) docs, for tutorials covering basic tasks.
|
||||
|
||||
- [Setting up the Development Environment](#setting-up-the-dev-environment)
|
||||
- [Prerequisites](#prerequisites)
|
||||
- [Running the App](#running-the-project)
|
||||
- [Project Commands](#project-commands)
|
||||
- [Environmental Variables](#environmental-variables)
|
||||
- [Git Strategy](#git-strategy)
|
||||
- [Flow](#git-flow)
|
||||
- [Branches](#git-branch-naming)
|
||||
- [Commit emojis](#commit-emojis)
|
||||
- [PR Guidelines](#pr-guidelines)
|
||||
- [Resources for Beginners](#resources-for-beginners)
|
||||
- [Style Guide](#style-guide)
|
||||
- [Frontend Components](#frontend-components)
|
||||
- [Project Structure](#directory-structure)
|
||||
- [Dependencies and Packages](#dependencies-and-packages)
|
||||
- [App Info](#app-info)
|
||||
- [Code Style Guide](#style-guide)
|
||||
- [Application Structure](#application-structure)
|
||||
- [Development Tools](#development-tools)
|
||||
- [Misc / Notes](#notes)
|
||||
|
||||
## Setting up the Dev Environment
|
||||
|
||||
@ -27,50 +37,45 @@ Dashy should now be being served on http://localhost:8080/. Hot reload is enable
|
||||
|
||||
### Project Commands
|
||||
|
||||
- `yarn dev` - Starts the development server with hot reloading
|
||||
- `yarn build` - Builds the project for production, and outputs it into `./dist`
|
||||
- `yarn start` - Starts a web server, and serves up the production site from `./dist`
|
||||
- `yarn validate-config` - Parses and validates your `conf.yml` against Dashy's schema
|
||||
- `yarn lint` - Lints code to ensure it follows a consistent, neat style
|
||||
- `yarn test` - Runs tests, and outputs results
|
||||
#### Basics
|
||||
- **`yarn build`** - In the interest of speed, the application is pre-compiled, this means that the config file is read during build-time, and therefore the app needs to rebuilt for any new changes to take effect. Luckily this is very straight forward. Just run `yarn build` or `docker exec -it [container-id] yarn build`
|
||||
- **`yarn start`** - Starts a web server, and serves up the production site from `./dist` (must run build command first)
|
||||
|
||||
There is also:
|
||||
- `yarn build-and-start` will run `yarn build` and `yarn start`
|
||||
- `yarn build-watch` will output contents to `./dist` and recompile when anything in `./src` is modified, you can then use either `yarn start` or your own server, to have a production environment that watches for changes.
|
||||
#### Development
|
||||
- **`yarn dev`** - Starts the development server with hot reloading
|
||||
- **`yarn lint`** - Lints code to ensure it follows a consistent, neat style
|
||||
- **`yarn test`** - Runs tests, and outputs results
|
||||
|
||||
Using the Vue CLI:
|
||||
- The app is build with Vue, and uses the [Vue-CLI Service](https://cli.vuejs.org/guide/cli-service.html) for basic commands.
|
||||
- If you have [NPX](https://github.com/npm/npx) installed, then you can invoke the Vue CLI binary using `npx vue-cli-service [command]`
|
||||
- Vue also has a GUI environment that can be used for basic project management, and may be useful for beginners, this can be started by running `vue ui`, and opening up `http://localhost:8000`
|
||||
#### Utils and Checks
|
||||
- **`yarn validate-config`** - If you have quite a long configuration file, you may wish to check that it's all good to go, before deploying the app. This can be done with `yarn validate-config` or `docker exec -it [container-id] yarn validate-config`. Your config file needs to be in `/public/conf.yml` (or within your Docker container at `/app/public/conf.yml`). This will first check that your YAML is valid, and then validates it against Dashy's [schema](https://github.com/Lissy93/dashy/blob/master/src/utils/ConfigSchema.js).
|
||||
- **`yarn health-check`** - Checks that the application is up and running on it's specified port, and outputs current status and response times. Useful for integrating into your monitoring service, if you need to maintain high system availability
|
||||
|
||||
Note:
|
||||
#### Alternate Start Commands
|
||||
- **`yarn build-and-start`** - Builds the app, runs checks and starts the production server. Commands are run in parallel, and so is faster than running them in independently. Uses the `yarn build` and `yarn start` commands
|
||||
- **`yarn build-watch`** - If you find yourself making frequent changes to your configuration, and do not want to have to keep manually rebuilding, then this option is for you. It will watch for changes to any files within the projects root, and then trigger a rebuild. Note that if you are developing new features, then `yarn dev` would be more appropriate, as it's significantly faster at recompiling (under 1 second), and has hot reloading, linting and testing integrated
|
||||
- **`yarn pm2-start`** - Starts the Node server using [PM2](https://pm2.keymetrics.io/), a process manager for Node.js applications, that helps them stay alive. PM2 has some built-in basic monitoring features, and an optional [management solution](https://pm2.io/). If you are running the app on bare metal, it is recommended to use this start command
|
||||
|
||||
#### Notes
|
||||
- If you are using NPM, replace `yarn` with `npm run`
|
||||
- If you are using Docker, precede each command with `docker exec -it [container-id]`. Container ID can be found by running `docker ps`
|
||||
- You can manage the app using the [Vue-CLI Service](https://cli.vuejs.org/guide/cli-service.html), with `npx vue-cli-service [command]`. Or to start the Vue Management UI, run `npx vue ui`, and open `http://localhost:8000`
|
||||
|
||||
### Environmental Variables
|
||||
All environmental variables are optional. Currently there are not many environmental variables used, as most of the user preferences are stored under `appConfig` in the `conf.yml` file.
|
||||
|
||||
You can set variables within your local development environment using a `.env` file.
|
||||
|
||||
Any environmental variables used by the frontend are preceded with `VUE_APP_`. Vue will merge the contents of your `.env` file into the app in a similar way to the ['dotenv'](https://github.com/motdotla/dotenv) package, where any variables that you set on your system will always take preference over the contents of any `.env` file.
|
||||
|
||||
- `PORT` - The port in which the application will run (defaults to `4000` for the Node.js server, and `80` within the Docker container)
|
||||
- `NODE_ENV` - Which environment to use, either `production`, `development` or `test`
|
||||
- `VUE_APP_DOMAIN` - The URL where Dashy is going to be accessible from. This should include the protocol, hostname and (if not 80 or 443), then the port too, e.g. `https://localhost:3000`, `http://192.168.1.2:4002` or `https://dashy.mydomain.com`
|
||||
|
||||
|
||||
If you do add new variables, ensure that there is always a fallback (define it in [`defaults.js`](https://github.com/Lissy93/dashy/blob/master/src/utils/defaults.js)), so as to not cause breaking changes. Don't commit your `.env` file to git, but instead take a few moments to document what you've added under the appropriate section. Try and follow the concepts outlined in the [12 factor app](https://12factor.net/config).
|
||||
You can set variables either in your environment, or using the [`.env`](https://github.com/Lissy93/dashy/blob/master/.env) file.
|
||||
|
||||
- `NODE_ENV` - Current environment, can be either development, production or test
|
||||
- `PORT` - The port to expose the running application on
|
||||
- `HOST` - The host that Dashy is running on, domain or IP
|
||||
- `BASE_URL` - The default base path for serving up static assets
|
||||
- `VUE_APP_DOMAIN` - Usually the same as BASE_URL, but accessible in frontend
|
||||
- `INTEGRITY` - Should enable SRI for build script and link resources
|
||||
- `IS_DOCKER` - Computed automatically on build. Indicates if running in container
|
||||
- `VUE_APP_VERSION` - Again, set automatically using package.json during build time
|
||||
|
||||
### Environment Modes
|
||||
You can set the environment using the `NODE_ENV` variable.
|
||||
The correct environment will be selected based on the script you run by default
|
||||
The following environments are supported.
|
||||
- `production`
|
||||
- `development`
|
||||
- `test`
|
||||
|
||||
For more info, see [Vue CLI Environment Modes](https://cli.vuejs.org/guide/mode-and-env.html#modes).
|
||||
You can set the environment using the `NODE_ENV` variable. By default, the correct environment should be selected based on the script you run to start the app. The following environments are supported: `production`, `development` and `test`. For more info, see [Vue CLI Environment Modes](https://cli.vuejs.org/guide/mode-and-env.html#modes).
|
||||
|
||||
---
|
||||
|
||||
@ -135,6 +140,7 @@ When you submit your PR, include the required info, by filling out the PR templa
|
||||
- Finally, check the checkboxes, to confirm that the standards are met, and hit submit!
|
||||
|
||||
---
|
||||
|
||||
## Resources for Beginners
|
||||
New to Web Development? Glad you're here! Dashy is a pretty simple app, so it should make a good candidate for your first PR. Presuming that you already have a basic knowledge of JavaScript, the following articles should point you in the right direction for getting up to speed with the technologies used in this project:
|
||||
- [Introduction to Vue.js](https://v3.vuejs.org/guide/introduction.html)
|
||||
@ -152,6 +158,8 @@ As well as Node, Git and Docker- you'll also need an IDE (e.g. [VS Code](https:/
|
||||
|
||||
---
|
||||
|
||||
## App Info
|
||||
|
||||
## Style Guide
|
||||
|
||||
Linting is done using [ESLint](https://eslint.org/), and using the [Vue.js Styleguide](https://github.com/vuejs/eslint-config-standard), which is very similar to the [AirBnB Stylguide](https://github.com/airbnb/javascript). You can run `yarn lint` to report and fix issues. While the dev server is running, issues will be reported to the console automatically, and any lint errors will trigger the build to fail. Note that all lint checks must pass before any PR can be merged. Linting is also run as a git pre-commit hook
|
||||
@ -175,8 +183,6 @@ Styleguides:
|
||||
|
||||
## Application Structure
|
||||
|
||||
### Directory Structure
|
||||
|
||||
#### Files in the Root: `./`
|
||||
```
|
||||
╮
|
||||
@ -206,6 +212,7 @@ Styleguides:
|
||||
├── components # All front-end Vue web components
|
||||
│ ├── Configuration # Components relating to the user config pop-up
|
||||
│ │ ├── AppInfoModal.vue # A modal showing core app info, like version, language, etc
|
||||
│ │ ├── AppVersion.vue # Shows current version from package.json, compares with GitHub
|
||||
│ │ ├── CloudBackupRestore.vue # Form where the user manages cloud sync options
|
||||
│ │ ├── ConfigContainer.vue # Main container, wrapping all other config components
|
||||
│ │ ├── CustomCss.vue # Form where the user can input custom CSS
|
||||
@ -224,14 +231,24 @@ Styleguides:
|
||||
│ │ ├── ItemIcon.vue # The icon used by both items and sections
|
||||
│ │ ├── ItemOpenMethodIcon.vue # A small icon, visible on hover, indicating opening method
|
||||
│ │ ╰── StatusIndicator.vue # Traffic light dot, showing if app is online or down
|
||||
│ ├── Minimal View # Components used for the startpage / minimal alternative view
|
||||
│ │ ├── MinimalHeading.vue # Title part of minimal view
|
||||
│ │ ├── MinimalSearch.vue # Search bar for minimal view
|
||||
│ │ ╰── MinimalSection.vue # Tabbed-Item section for minimal view
|
||||
│ ├── PageStrcture # Components relating the main structure of the page
|
||||
│ │ ├── Footer.vue # Footer, visible at the bottom of all pages
|
||||
│ │ ├── Header.vue # Header, visible at the top of pages, and includes title and nav
|
||||
│ │ ├── LoadingScreen.vue # Splash screen shown on first load
|
||||
│ │ ├── Nav.vue # Navigation bar, includes a list of links
|
||||
│ │ ╰── PageTitle.vue # Page title and sub-title, visible within the Header
|
||||
│ ├── Workspace # Components used for the multi-tasking/ Workspace view
|
||||
│ │ ├── MultiTaskingWeb.vue # When multi-tasking enabled, generates new iframe
|
||||
│ │ ├── SideBar.vue # The left sidebar for the workspace view
|
||||
│ │ ├── SideBarItem.vue # App item for the sidebar view
|
||||
│ │ ├── SideBarSection.vue # Collapsible collection of items within workspace sidebar
|
||||
│ │ ╰── WebContent.vue # Workspace iframe view, displays content of current app
|
||||
│ ╰── Settings # Components relating to the quick-settings, in the top-right
|
||||
│ ├── AuthButtons.vue # Logout button and other app info
|
||||
│ ├── AuthButtons.vue # Logout button and other app info
|
||||
│ ├── ConfigLauncher.vue # Icon that when clicked will launch the Configuration component
|
||||
│ ├── CustomThemeMaker.vue # Color pickers for letting user build their own theme
|
||||
│ ├── ItemSizeSelector.vue # Set of buttons used to set and save item size
|
||||
@ -248,14 +265,21 @@ Styleguides:
|
||||
├── utils # Directory of re-used helper functions
|
||||
│ ├── ArrowKeyNavigation.js # Functionality for arrow-key navigation
|
||||
│ ├── Auth.js # Handles all authentication related actions
|
||||
│ ├── CheckSectionVisibility.js # Checks which parts of the page should be visible/ hidden based on config
|
||||
│ ├── ClickOutside.js # A directive for detecting click, used to hide dropdown, modal or context menu
|
||||
│ ├── ConfigAccumulator.js # Central place for managing and combining config
|
||||
│ ├── ConfigHelpers.js # Helper functions for managing configuration
|
||||
│ ├── CloudBackup.js # Functionality for encrypting, processing and network calls
|
||||
│ ├── ConfigSchema.json # The schema, used to validate the users conf.yml file
|
||||
│ ├── ConfigAccumulator.js # Central place for managing and combining config
|
||||
│ ├── ConfigHelpers.json # Collection of helper functions to process config using accumulator
|
||||
│ ├── ConfigValidator.js # A helper script that validates the config file against schema
|
||||
│ ├── CoolConsole.js # Prints info, warning and error messages to browser console, with a cool style
|
||||
│ ├── defaults.js # Global constants and their default values
|
||||
│ ├── emojis.json # List of emojis with unicode and shortcode, used for emoji icon feature
|
||||
│ ├── EmojiUnicodeRegex.js # Regular expression to validate emoji unicode format, for emoji icons
|
||||
│ ├── ErrorHandler.js # Helper function called when an error is returned
|
||||
│ ├── InitServiceWorker.js # Initializes and manages service worker, if enabled
|
||||
│ ├── Search.js # Helper functions for searching/ filtering items in all views
|
||||
│ ├── JsonToYaml.js # Function that parses and converts raw JSON into valid YAML
|
||||
│ ├── languages.js # Handles fetching, switching and validating languages
|
||||
│ ╰── ThemeHelper.js # Function that handles the fetching and setting of user themes
|
||||
@ -267,23 +291,9 @@ Styleguides:
|
||||
╰── Workspace.vue # The workspace view with apps in sidebar
|
||||
```
|
||||
|
||||
### Frontend Components
|
||||
|
||||
All frontend code is located in the `./src` directory, which is split into 5 sub-folders:
|
||||
- **Components** - All frontend web components are located here. Each component should have a distinct, well defined and simple task, and ideally should not be too long. The components directory is organised into a series of sub-directories, representing a specific area of the application
|
||||
- **PageStrcture** - Components relating to overall page structure (nav, footer, etc)
|
||||
- FormElements - Reusable form elements (button, input field, etc)
|
||||
- LinkItems - Components relating to Dashy's sections and items (item group, item, item icon, etc)
|
||||
- Configuration - Components relating to Dashy's configuration forms (cloud backup, JSON editor, etc)
|
||||
- **Views** - Each view directly corresponds to a route (defined in the router), and in effectively a page. They should have minimal logic, and just contain a few components
|
||||
- **Utils** - These are helper functions, or logic that is used within the app does not include an UI elements
|
||||
- **Styles** - Any SCSS that is used globally throughout that app, and is not specific to a single component goes here. This includes variables, color themes, typography settings, CSS reset and media queries
|
||||
- **Assets** - Static assets that need to be bundled into the application, but do not require any manipulation go here. This includes interface icons and fonts
|
||||
|
||||
The structure of the components directory is similar to that of the frontend application layout
|
||||
|
||||
<p align="center"><img src="https://i.ibb.co/wJCt0Lq/dashy-page-structure.png" width="600"/></p>
|
||||
#### Visualisation of Source Directory
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
@ -296,6 +306,7 @@ The easiest method of checking performance is to use Chromium's build in auditin
|
||||
[BundlePhobia](https://bundlephobia.com/) is a really useful app that lets you analyze the cost of adding any particular dependency to an application
|
||||
|
||||
---
|
||||
|
||||
## Notes
|
||||
|
||||
### Known Warnings
|
||||
@ -306,4 +317,3 @@ When running the build command, several warnings appear. These are not errors, a
|
||||
|
||||
`WARN asset size limit: The following asset(s) exceed the recommended size limit (244 KiB).` - For the PWA to support Windows 10, a splash screen asset is required, and is quite large. This throws a warning, however PWA assets are not loaded until needed, so shouldn't have any impact on application performance. A similar warning is thrown for the Raleway font, and that is looking to be addressed.
|
||||
|
||||
`glob-parent Security Alert` - This will be fixed soon. The version of glob-parent that is used by the latest version of Vue-CLI has a security issue associated with it. I am waiting on Vue to update their dependencies.
|
||||
|
||||
@ -141,6 +141,40 @@ Running `yarn upgrade` will updated all dependencies based on the ranges specifi
|
||||
|
||||
---
|
||||
|
||||
## Developing Netlify Cloud Functions
|
||||
|
||||
When Dashy is deployed to Netlify, it is effectively running as a static app, and therefore the server-side code for the Node.js endpoints is not available. However Netlify now supports serverless cloud lambda functions, which can be used to replace most functionality.
|
||||
|
||||
#### 1. Run Netlify Dev Server
|
||||
|
||||
First off, install the Netlify CLI: `npm install netlify-cli -g`
|
||||
Then, from within the root of Dashy's directory, start the server, by running: `netlify dev`
|
||||
|
||||
#### 2. Create a lambda function
|
||||
|
||||
This should be saved it in the [`./services/serverless-functions`](https://github.com/Lissy93/dashy/tree/master/services/serverless-functions) directory
|
||||
|
||||
```javascript
|
||||
exports.handler = async () => ({
|
||||
statusCode: 200,
|
||||
body: 'Return some data here...',
|
||||
});
|
||||
```
|
||||
|
||||
#### 3. Redirect the Node endpoint to the function
|
||||
|
||||
In the [`netlify.toml`](https://github.com/Lissy93/dashy/blob/FEATURE/serverless-functions/netlify.toml) file, add a 301 redirect, with the path to the original Node.js endpoint, and the name of your cloud function
|
||||
|
||||
```toml
|
||||
[[redirects]]
|
||||
from = "/status-check"
|
||||
to = "/.netlify/functions/cloud-status-check"
|
||||
status = 301
|
||||
force = true
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Hiding Page Furniture on Certain Routes
|
||||
For some pages (such as the login page, the minimal start page, etc) the basic page furniture, (like header, footer, nav, etc) is not needed. This section explains how you can hide furniture on a new view (step 1), or add a component that should be hidden on certain views (step 2).
|
||||
|
||||
@ -175,4 +209,13 @@ Finally, in the markup of your component, just add a `v-if` statement, referenci
|
||||
</header>
|
||||
```
|
||||
|
||||
---
|
||||
---
|
||||
|
||||
## Adding / Using Environmental Variables
|
||||
All environmental variables are optional. Currently there are not many environmental variables used, as most of the user preferences are stored under `appConfig` in the `conf.yml` file.
|
||||
|
||||
You can set variables either in your environment, or using the [`.env`](https://github.com/Lissy93/dashy/blob/master/.env) file.
|
||||
|
||||
Any environmental variables used by the frontend are preceded with `VUE_APP_`. Vue will merge the contents of your `.env` file into the app in a similar way to the ['dotenv'](https://github.com/motdotla/dotenv) package, where any variables that you set on your system will always take preference over the contents of any `.env` file.
|
||||
|
||||
If add any new variables, ensure that there is always a fallback (define it in [`defaults.js`](https://github.com/Lissy93/dashy/blob/master/src/utils/defaults.js)), so as to not cause breaking changes. Don't commit the contents of your `.env` file to git, but instead take a few moments to document what you've added under the appropriate section. Try and follow the concepts outlined in the [12 factor app](https://12factor.net/config).
|
||||
|
||||
@ -3,11 +3,13 @@
|
||||
Both sections and items can have an icon, which is specified using the `icon` attribute. Using icons improves the aesthetics of your UI and makes the app more intuitive to use. There are several options when it comes to setting icons, and this article outlines each of them
|
||||
|
||||
- [Font Awesome Icons](#font-awesome)
|
||||
- [Simple Icons](#simple-icons)
|
||||
- [Auto-Fetched Favicons](#favicons)
|
||||
- [Generative Icons](#generative-icons)
|
||||
- [Emoji Icons](#emoji-icons)
|
||||
- [Icons by URL](#icons-by-url)
|
||||
- [Local Icons](#local-icons)
|
||||
- [Material Design Icons](#material-design-icons)
|
||||
- [No Icon](#no-icon)
|
||||
|
||||
<p align="center">
|
||||
@ -16,7 +18,9 @@ Both sections and items can have an icon, which is specified using the `icon` at
|
||||
|
||||
Note that, if you are using icons from an external source (like font-awesome or material-design-icons), then the relevant font file will be loaded in automatically if and when needed, but combining icons from multiple services may have a negative impact on performance.
|
||||
|
||||
### Font Awesome
|
||||
---
|
||||
|
||||
## Font Awesome
|
||||
You can use any [Font Awesome Icon](https://fontawesome.com/icons) simply by specifying it's identifier. This is in the format of `[category] [name]` and can be found on the page for any given icon on the Font Awesome site. For example: `fas fa-rocket`, `fab fa-monero` or `fas fa-unicorn`.
|
||||
|
||||
Font-Awesome has a wide variety of free icons, but you can also use their pro icons if you have a membership. To do so, you need to specify your license key under: `appConfig.fontAwesomeKey`. This is usually a 10-digit string, for example `13014ae648`.
|
||||
@ -25,7 +29,29 @@ Font-Awesome has a wide variety of free icons, but you can also use their pro ic
|
||||
<img width="580" src="https://i.ibb.co/pdrw8J4/fontawesome-icons2.png" />
|
||||
</p>
|
||||
|
||||
### Favicons
|
||||
---
|
||||
|
||||
## Simple Icons
|
||||
[SimpleIcons.org](https://simpleicons.org/) is a collection of 2000+ high quality, free and open source brand and logo SVG icons. Usage of which is very similar to font-awesome icons. First find the glyph you want to use on the [website](https://simpleicons.org/), then just set your icon the the simple icon slug, prefixed with `si-`.
|
||||
|
||||
For example:
|
||||
```yaml
|
||||
sections:
|
||||
- name: Simple Icons Example
|
||||
items:
|
||||
- title: Portainer
|
||||
icon: si-portainer
|
||||
- title: FreeNAS
|
||||
icon: si-freenas
|
||||
- title: NextCloud
|
||||
icon: si-nextcloud
|
||||
- title: Home Assistant
|
||||
icon: si-homeassistant
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Favicons
|
||||
Dashy can auto-fetch the favicon for a given service using it's URL. Just set `icon: favicon` to use this feature. If the services URL is a local IP, then Dashy will attempt to find the favicon from `http://[ip]/favicon.ico`. This has two issues, favicons are not always hosted at the same location for every service, and often the default favicon is a low resolution. Therefore to fix this, for remote services an API is used to return a high-quality icon for any online service.
|
||||
|
||||
<p align="center">
|
||||
@ -42,41 +68,45 @@ The default favicon API is [Favicon Kit](https://faviconkit.com/), a free and re
|
||||
|
||||
You can also force Dashy to always get favicons from the root of the domain, and not use an external service, by setting `appConfig.faviconApi` to `local`.
|
||||
|
||||
### Generative Icons
|
||||
To use a different favicon API for certain items, then set `icon: favicon-[api]`, e.g. `favicon-clearbit`
|
||||
|
||||
If for a given service none of the APIs work in your situation, and nor does local, then the best option is to find the path of the services logo or favicon, and set the icon to the URL of the raw image.
|
||||
|
||||
---
|
||||
|
||||
## Generative Icons
|
||||
Uses a unique and programmatically generated icon for a given service. This is particularly useful when you have a lot of similar services with a different IP or port, and no specific icon. These icons are generated with [ipsicon.io](https://ipsicon.io/). To use this option, just set an item's to: `icon: generative`.
|
||||
|
||||
<p align="center">
|
||||
<img width="400" src="https://i.ibb.co/qrNNNcm/generative-icons.png" />
|
||||
</p>
|
||||
|
||||
### Emoji Icons
|
||||
---
|
||||
|
||||
## Emoji Icons
|
||||
You can use almost any emoji as an icon for items or sections. You can specify the emoji either by pasting it directly, using it's unicode ( e.g. `'U+1F680'`) or shortcode (e.g. `':rocket:'`). You can find these codes for any emoji using [Emojipedia](https://emojipedia.org/) (near the bottom of emoji each page), or for a quick reference to emoji shortcodes, check out [emojis.ninja](https://emojis.ninja/) by @nomanoff.
|
||||
|
||||
<p align="center">
|
||||
<img width="580" src="https://i.ibb.co/YLwgTf9/emoji-icons-1.png" />
|
||||
</p>
|
||||
|
||||
The following examples will all render the same rocket (🚀) emoji:
|
||||
For example, these will all render the same rocket (🚀) emoji: `icon: ':rocket:'` or `icon: 'U+1F680'` or `icon: 🚀`
|
||||
|
||||
```yaml
|
||||
items:
|
||||
- title: Shortcode
|
||||
icon: ':rocket:'
|
||||
- title: Unicode
|
||||
icon: 'U+1F680'
|
||||
- title: Emoji
|
||||
icon: 🚀
|
||||
```
|
||||
---
|
||||
|
||||
### Icons by URL
|
||||
## Icons by URL
|
||||
You can also set an icon by passing in a valid URL pointing to the icons location. For example `icon: https://i.ibb.co/710B3Yc/space-invader-x256.png`, this can be in .png, .jpg or .svg format, and hosted anywhere- so long as it's accessible from where you are hosting Dashy. The icon will be automatically scaled to fit, however loading in a lot of large icons may have a negative impact on performance, especially if you visit Dashy from new devices often.
|
||||
|
||||
### Local Icons
|
||||
---
|
||||
|
||||
## Local Icons
|
||||
You may also want to store your icons locally, bundled within Dashy so that there is no reliance on outside services. This can be done by putting the icons within Dashy's `./public/item-icons/` directory. If you are using Docker, then the easiest option is to map a volume from your host system, for example: `-v /local/image/directory:/app/public/item-icons/`. To reference an icon stored locally, just specify it's name and extension. For example, if my icon was stored in `/app/public/item-icons/maltrail.png`, then I would just set `icon: maltrail.png`.
|
||||
|
||||
You can also use sub-folders within the `item-icons` directory to keep things organised. You would then specify an icon with it's folder name slash image name. For example: `networking/monit.png`
|
||||
|
||||
### Material Design Icons
|
||||
---
|
||||
|
||||
## Material Design Icons
|
||||
Dashy also supports 5000+ [material-design-icons](https://github.com/Templarian/MaterialDesign). To use these, first find the name/ slug for your icon [here](https://dev.materialdesignicons.com/icons), and then prefix is with `mdi-`.
|
||||
|
||||
For example:
|
||||
@ -93,8 +123,7 @@ sections:
|
||||
|
||||
```
|
||||
|
||||
### Simple Icons
|
||||
To use glyphs from [SimpleIcons.org](https://simpleicons.org/), first find the icon slug, and then prefix it with `si-`. The image will be loaded directly from the Simple Icons
|
||||
---
|
||||
|
||||
### No Icon
|
||||
## No Icon
|
||||
If you don't wish for a given item or section to have an icon, just leave out the `icon` attribute.
|
||||
|
||||
@ -3,22 +3,18 @@
|
||||
## Providing Assets
|
||||
Although not essential, you will most likely want to provide several assets to Dashy. All web assets can be found in the `/public` directory.
|
||||
|
||||
For example:
|
||||
- `./public/conf.yml` - As mentioned, this is your main application config file
|
||||
- `./public/item-icons` - If you're using your own icons, you can choose to store them locally for better load time, and this is the directory to put them in. You can also use sub-folders here to keep things organized. You then reference these assets relative this the direcroties path, for example: to use `./public/item-icons/networking/netdata.png` as an icon for one of your links, you would set `icon: networking/netdata.png`
|
||||
- Also within `./public` you'll find standard website assets, including `favicon.ico`, `manifest.json`, `robots.txt`, etc. There's no need to modify these, but you can do so if you wish.
|
||||
- `./public/item-icons` - If you're using your own icons, you can choose to store them locally for better load time, and this is the directory to put them in. You can also use sub-folders here to keep things organized
|
||||
- Also within `./public` you'll find standard website assets, including `favicon.ico`, `manifest.json`, `robots.txt`, etc. There's no need to pass these in, but you can do so if you wish
|
||||
|
||||
## Basic Commands
|
||||
This is easy to do using [Docker Volumes](https://docs.docker.com/storage/volumes/), which lets you share a file or directory between your host system, and the container. Volumes are specified in the Docker run command, or Docker compose file, using the `--volume` or `-v` flags. The value of which consists of the path to the file / directory on your host system, followed by the destination path within the container. Fields are separated by a colon (`:`), and must be in the correct order. For example: `-v ~/alicia/my-local-conf.yml:/app/public/conf.yml`
|
||||
|
||||
Now that you've got Dashy running, there are a few commands that you need to know.
|
||||
## Running Commands
|
||||
|
||||
The following commands are defined in the [`package.json`](https://github.com/Lissy93/dashy/blob/master/package.json#L5) file, and are run with `yarn`. If you prefer, you can use NPM, just replace instances of `yarn` with `npm run`. If you are using Docker, then you will need to precede each command with `docker exec -it [container-id]`, where container ID can be found by running `docker ps`. For example `docker exec -it 26c156c467b4 yarn build`.
|
||||
The project has a few commands that can be used for various tasks, you can find a list of these either in the [Developing Docs](/docs/developing#project-commands), or by looking at the [`package.json`](https://github.com/Lissy93/dashy/blob/master/package.json#L5). These can be used by running `yarn [command-name]`.
|
||||
|
||||
- **`yarn build`** - In the interest of speed, the application is pre-compiled, this means that the config file is read during build-time, and therefore the app needs to rebuilt for any new changes to take effect. Luckily this is very straight forward. Just run `yarn build` or `docker exec -it [container-id] yarn build`
|
||||
- **`yarn validate-config`** - If you have quite a long configuration file, you may wish to check that it's all good to go, before deploying the app. This can be done with `yarn validate-config` or `docker exec -it [container-id] yarn validate-config`. Your config file needs to be in `/public/conf.yml` (or within your Docker container at `/app/public/conf.yml`). This will first check that your YAML is valid, and then validates it against Dashy's [schema](https://github.com/Lissy93/dashy/blob/master/src/utils/ConfigSchema.js).
|
||||
- **`yarn health-check`** - Checks that the application is up and running on it's specified port, and outputs current status and response times. Useful for integrating into your monitoring service, if you need to maintain high system availability
|
||||
- **`yarn build-watch`** - If you find yourself making frequent changes to your configuration, and do not want to have to keep manually rebuilding, then this option is for you. It will watch for changes to any files within the projects root, and then trigger a rebuild. Note that if you are developing new features, then `yarn dev` would be more appropriate, as it's significantly faster at recompiling (under 1 second), and has hot reloading, linting and testing integrated
|
||||
- **`yarn build-and-start`** - Builds the app, runs checks and starts the production server. Commands are run in parallel, and so is faster than running them in independently
|
||||
- **`yarn pm2-start`** - Starts the Node server using [PM2](https://pm2.keymetrics.io/), a process manager for Node.js applications, that helps them stay alive. PM2 has some built-in basic monitoring features, and an optional [management solution](https://pm2.io/). If you are running the app on bare metal, it is recommended to use this start command
|
||||
But if you're using Docker, then you'll need to execute them within the container. This can be done by preceding each command with `docker exec -it [container-id]`, where container ID can be found by running `docker ps`. For example `docker exec -it 26c156c467b4 yarn build`. You can also enter the container, with `docker exec -it [container-id] /bin/ash`, and navigate around it with normal Linux commands.
|
||||
|
||||
## Healthchecks
|
||||
|
||||
@ -67,7 +63,7 @@ If you're not so comfortable on the command line, then you can use a tool like [
|
||||
Dashy has [basic authentication](/docs/authentication) built in, however at present this is handled on the front-end, and so where security is critical, it is recommended to use an alternative method. See [here](/docs/authentication#alternative-authentication-methods) for options regarding securing Dashy.
|
||||
|
||||
|
||||
**[⬆️ Back to Top](#)**
|
||||
**[⬆️ Back to Top](#management)**
|
||||
|
||||
---
|
||||
## Updating
|
||||
@ -105,7 +101,7 @@ For more information, see the [Watchtower Docs](https://containrrr.dev/watchtowe
|
||||
4. Re-build: `yarn build`
|
||||
5. Start: `yarn start`
|
||||
|
||||
**[⬆️ Back to Top](#)**
|
||||
**[⬆️ Back to Top](#management)**
|
||||
|
||||
---
|
||||
|
||||
@ -180,7 +176,7 @@ Then restart Apache, with `sudo systemctl restart apache2`
|
||||
8. If you need to change the port, click 'Add environmental variable', give it the name 'PORT', choose a port number and press 'Save'.
|
||||
9. Dashy should now be running at your selected path an on a given port
|
||||
|
||||
**[⬆️ Back to Top](#)**
|
||||
**[⬆️ Back to Top](#management)**
|
||||
|
||||
---
|
||||
|
||||
@ -189,4 +185,4 @@ Then restart Apache, with `sudo systemctl restart apache2`
|
||||
Dashy has built-in authentication and login functionality. However, since this is handled on the client-side, if you are using Dashy 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. For more info, see **[Authentication Docs](/docs/authentication)**.
|
||||
|
||||
|
||||
**[⬆️ Back to Top](#)**
|
||||
**[⬆️ Back to Top](#management)**
|
||||
@ -1,23 +1,32 @@
|
||||
# Internationalization
|
||||
|
||||
Internationalization is the process of making an application available in other languages. This is important, as not everyone is a native English speaker.
|
||||
Internationalization is the process of making an application available in other languages. This is important, as not everyone is a native English speaker. This page explains how you can switch languages, how to add a new language, and how to make text translatable when writing a new component.
|
||||
|
||||
## Available Languages
|
||||
|
||||
An up-to-date list of all currently supported languages can be found in [`./src/utils/languages.js`](https://github.com/Lissy93/dashy/blob/master/src/utils/languages.js). Languages are specified by their 2-digit [ISO-639 code](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) (e.g. `en`, `fr`, `de`, `es`, etc)
|
||||
- [Setting your Language](#setting-language)
|
||||
- [Adding a new Language](#adding-a-new-language)
|
||||
- [Adding New Text to a Component](#adding-new-text-to-a-component)
|
||||
|
||||
---
|
||||
|
||||
## How to change Language
|
||||
## Setting Language
|
||||
|
||||
By default, Dashy will attempt to use the language of your browser or system. If a translation for your language does not yet exist, it will fallback to English.
|
||||
|
||||
You can also manually select your language. This can be done, either through the UI (Config --> Language), or by setting it in your config file:
|
||||
#### In the UI
|
||||
You can manually select your language in the UI. Under the Config Menu, click the Language button, and select your language from the dropdown menu. Your preference will be saved in local storage.
|
||||
|
||||
#### Config File
|
||||
You can also set your language in the config file. Specify the ISO code of one of the supported languages, under `appConfig.lang`. For example:
|
||||
|
||||
```yaml
|
||||
appConfig:
|
||||
lang: de
|
||||
lang: de
|
||||
```
|
||||
|
||||
#### Available Languages
|
||||
|
||||
At the time of writing the following languages are supported: `en`, `zh-CN`, `nl`, `fr`, `de`, `es`, `sl`, `it`, `pt`, `ru`, `ar`, `hi`, `ja`, but an up-to-date list of all implemented translations can be found in [`./src/utils/languages.js`](https://github.com/Lissy93/dashy/blob/master/src/utils/languages.js). Languages are specified by their 2-digit [ISO-639 code](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes), or sometimes a 4-digit code if it's a regional dialect.
|
||||
|
||||
---
|
||||
|
||||
## Adding a new Language
|
||||
@ -27,9 +36,10 @@ Dashy is using [vue-i18n](https://vue-i18n.intlify.dev/guide/) to manage multi-l
|
||||
Adding a new language is pretty straightforward, with just three steps:
|
||||
|
||||
##### 1. Create a new Language File
|
||||
Create a new JSON file in `./src/assets/locales` name is a 2-digit [ISO-639 code](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) for your language, E.g. for German `de.json`, French `fr.json` or Spanish `es.json` - You can find a list of all ISO codes at [iso.org](https://www.iso.org/obp/ui).
|
||||
If your language is a specific dialect or regional language, then use the Posfix [CLDR](http://cldr.unicode.org/) format, where, e.g. `en-GB.json` (British), `es-MX.json` (Spanish, in Mexico) or `zh-CN.json` (Chinese, simplified) - A list of which can be found [here](https://github.com/unicode-org/cldr-json/blob/master/cldr-json/cldr-core/availableLocales.json)
|
||||
Create a new JSON file in `./src/assets/locales` for your language.
|
||||
|
||||
You should name it with the 2-digit [ISO-639 code](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) for your locale (e.g. for German `de.json`, French `fr.json` or Spanish `es.json`) - You can find a list of all ISO codes at [iso.org](https://www.iso.org/obp/ui).
|
||||
If your language is a specific dialect or regional translation, then use the Posfix [CLDR](http://cldr.unicode.org/) format, where, e.g. `en-GB.json` (British English), `es-MX.json` (Spanish, in Mexico) or `zh-CN.json` (Chinese, simplified) - A list of which can be found [here](https://github.com/unicode-org/cldr-json/blob/master/cldr-json/cldr-core/availableLocales.json)
|
||||
|
||||
##### 2. Translate!
|
||||
Using [`en.json`](https://github.com/Lissy93/dashy/tree/master/src/assets/locales/en.json) as an example, translate the JSON values to your language, while leaving the keys as they are. It's fine to leave out certain items, as if they're missing they will fall-back to English. If you see any attribute which include curly braces (`{xxx}`), then leave the inner value of these braces as is, as this is for variables.
|
||||
@ -78,12 +88,9 @@ If you are not comfortable with making pull requests, or do not want to modify t
|
||||
|
||||
---
|
||||
|
||||
## Adding Text
|
||||
|
||||
If you're working on a new component, then any text that is displayed to the user should be extracted out of the component, and stored in the file. This also applies to any existing components, that might have been forgotten to be translated.
|
||||
|
||||
Thankfully, everything is already setup, and so is as easy as adding text to the JSON file, and pasting the key to that text in your component.
|
||||
## Adding New Text to a Component
|
||||
|
||||
If you're working on a new component, then any text that is displayed to the user should be extracted out of the component, and stored in the file. This also applies to any existing components, that might have been forgotten to be translated. Thankfully, everything is already setup, so this is a pretty easy job.
|
||||
|
||||
#### 1. Add Translated Text
|
||||
|
||||
@ -95,8 +102,7 @@ Firstly, go to [`./src/assets/locales/en.json`](https://github.com/Lissy93/dashy
|
||||
}
|
||||
```
|
||||
|
||||
Note that you **must** add English translations for all text. Missing languages are not a problem, as they will always fallback to Enslish, but if the English is missing, then nothing can be displayed.
|
||||
|
||||
Note that you **must** add English translations for all text. Missing languages are not a problem, as they will always fallback to English, but if the English is missing, then nothing can be displayed.
|
||||
|
||||
#### 2. Use Text within Component
|
||||
|
||||
@ -143,10 +149,9 @@ In [`./src/components/Settings/SearchBar.vue`](https://github.com/Lissy93/dashy/
|
||||
<form>
|
||||
<label for="search-input">{{ $t('search.search-label') }}</label>
|
||||
<input
|
||||
id="search-input"
|
||||
v-model="searchValue"
|
||||
:placeholder="$t('search.search-placeholder')"
|
||||
/>
|
||||
/>
|
||||
</form>
|
||||
</template>
|
||||
```
|
||||
@ -159,6 +164,6 @@ Then in [`./src/assets/locales/en.json`](https://github.com/Lissy93/dashy/blob/m
|
||||
"search-label": "Search",
|
||||
"search-placeholder": "Start typing to filter",
|
||||
},
|
||||
...
|
||||
...
|
||||
}
|
||||
```
|
||||
|
||||
@ -56,15 +56,17 @@ The following section outlines all data that is stored in the browsers, as cooki
|
||||
- `LAYOUT_ORIENTATION` - Preferred section layout, either horizontal, vertical or auto
|
||||
- `COLLAPSE_STATE` - Remembers which sections are collapsed
|
||||
- `ICON_SIZE` - Size of items, either small, medium or large
|
||||
- `THEME: 'theme` - Users applied theme
|
||||
- `THEME` - Users applied theme
|
||||
- `CUSTOM_COLORS` - Any color modifications made to a given theme
|
||||
- `BACKUP_ID` - If a backup has been made, the ID is stored here
|
||||
- `BACKUP_HASH` - A unique hash of the previous backups meta data
|
||||
- `HIDE_SETTINGS` - Lets user hide or show the settings menu
|
||||
- `USERNAME` - If user logged in, store username in order to welcome them
|
||||
- `USERNAME` - If user logged in, store username. Only used to show welcome message, not used for auth
|
||||
- `CONF_SECTIONS` - Array of sections, only used when user applies changes locally
|
||||
- `PAGE_INFO` - Config page info, only used when user applies changes locally
|
||||
- `APP_CONFIG` - App config, only used when user applies changes locally
|
||||
- `MOST_USED` - If smart sort is used to order items by most used, store open count
|
||||
- `LAST_USED` - If smart sort is used to order items by last used, store timestamps
|
||||
|
||||
---
|
||||
|
||||
@ -95,6 +97,30 @@ This is covered in more detail in [App Management](/docs/management).
|
||||
|
||||
---
|
||||
|
||||
## Security Features
|
||||
|
||||
#### Subresource Integrity
|
||||
[Subresource Integrity](https://developer.mozilla.org/en-US/docs/Web/Security/Subresource_Integrity) or SRI is a security feature that enables browsers to verify that resources they fetch are delivered without unexpected manipulation. It works by allowing you to provide a cryptographic hash that a fetched resource must match. This prevents the app from loading any resources that have been manipulated, by verifying the files hashes. It safeguards against the risk of an attacker injecting arbitrary malicious content into any files served up via a CDN.
|
||||
|
||||
Dashy supports SRI, and it is recommended to enable this if you are hosting your dashboard via a public CDN. To enable SRI, set the `INTEGRITY` environmental variable to `true`.
|
||||
|
||||
#### Authentication
|
||||
Dashy supports both basic auth, as well as server-based SSO using Keycloak. Full details of which, along with alternate authentication methods can be found in the [Authentication Docs](/docs/authentication). If your dashboard is exposed to the internet and/ or contains any sensitive info it is strongly recommended to configure access control with Keycloak or another server-side method.
|
||||
|
||||
---
|
||||
|
||||
## Disabling Features
|
||||
You may wish to disable features that you don't want to use, if they involve storing data in the browser or making network requests.
|
||||
- To disable smart-sort (uses local storage), set `appConfig.disableSmartSort: true`
|
||||
- To disable update checks (makes external request to GH), set `appConfig.disableUpdateChecks: true`
|
||||
- To disable web search (redirect to external / internal content), set `appConfig.disableWebSearch: true`
|
||||
- To keep status checks disabled (external/ internal requests), set `appConfig.statusCheck: false`
|
||||
- To keep font-awesome icons disabled (external requests), set `appConfig.enableFontAwesome: false`
|
||||
- To keep error reporting disabled (external requests and data collection), set `appConfig.enableErrorReporting: false`
|
||||
- To keep the service worker disabled (stores cache of app in browser data), set `appConfig.enableServiceWorker: false`
|
||||
|
||||
---
|
||||
|
||||
## Reporting a Security Issue
|
||||
If you think you've found a critical issue with Dashy, please send an email to `security@mail.alicia.omg.lol`. You can encrypt it, using [`0688 F8D3 4587 D954 E9E5 1FB8 FEDB 68F5 5C02 83A7`](https://keybase.io/aliciasykes/pgp_keys.asc?fingerprint=0688f8d34587d954e9e51fb8fedb68f55c0283a7). You should receive a response within 48 hours.
|
||||
|
||||
|
||||
@ -121,8 +121,8 @@ Then edit `./public/conf.yml` and rebuild the app with `yarn build`
|
||||
|
||||
## Alternative Deployment Method 2 - Netlify
|
||||
|
||||
Don't have a server? No problem! You can run Dashy for free on Netlify (as well as many [other cloud providers](/docs/deployment#deploy-to-cloud-service)). All you need it a GitHub account.
|
||||
Don't have a server? No problem! You can run Dashy for free on Netlify (as well as many [other cloud providers](./docs/deployment#deploy-to-cloud-service)). All you need it a GitHub account.
|
||||
1. Fork Dashy's repository on GitHub
|
||||
2. [Log in](https://app.netlify.com/login/) to Netlify with GitHub
|
||||
2. [Log in](app.netlify.com/login/) to Netlify with GitHub
|
||||
3. Click "New site from Git" and select your forked repo, then click **Deploy**!
|
||||
4. You can then edit the config in `./public/conf.yml` in your repo, and Netlify will rebuild the app
|
||||
|
||||
@ -27,6 +27,6 @@
|
||||
### Misc
|
||||
- [Privacy & Security](/docs/privacy) - List of requests, potential issues, and security resources
|
||||
- [License](/docs/license) - Copy of the MIT License
|
||||
- [Legal](https://github.com/Lissy93/dashy/blob/master/.github/LEGAL.md) - Licenses of direct dependencies
|
||||
- [Legal](https://github.com/Lissy93/dashy/blob/master/.github/LEGAL) - Licenses of direct dependencies
|
||||
- [Code of Conduct](/docs/code-of-conduct) - Contributor Covenant Code of Conduct
|
||||
- [Changelog](/docs/changelog) - Details of recent changes, and historical versions
|
||||
|
||||
158
docs/release-workflow.md
Normal file
158
docs/release-workflow.md
Normal file
@ -0,0 +1,158 @@
|
||||
|
||||
# Releases and Workflows
|
||||
|
||||
- [Release Schedule](#release-schedule)
|
||||
- [Deployment Process](#deployment-process)
|
||||
- [Git Strategy](#git-strategy)
|
||||
- [Automated Workflows](#automated-workflows)
|
||||
|
||||
## Release Schedule
|
||||
|
||||
We're using [Semantic Versioning](https://semver.org/), to indicate major, minor and patch versions. You can find the current version number in the readme, and check your apps version under the config menu. The version number is pulled from the [package.json](https://github.com/Lissy93/dashy/blob/master/package.json#L3) file.
|
||||
|
||||
Typically there is a new major release every 2 weeks, usually on Sunday, and you can view these under the [Releases Page](https://github.com/Lissy93/dashy/releases). Each new version will also have a corresponding [tag on GitHub](https://github.com/Lissy93/dashy/tags), and each major release will also result in the creation of a new [tag on DockerHub](https://hub.docker.com/r/lissy93/dashy/tags), so that you can fix your container to a certain version.
|
||||
|
||||
For a full breakdown of each change, you can view the [Changelog](https://github.com/Lissy93/dashy/blob/master/.github/CHANGELOG). Each new feature or significant change needs to be submitted through a pull request, which makes it easy to review and track these changes, and roll back if needed.
|
||||
|
||||
---
|
||||
|
||||
## Deployment Process
|
||||
|
||||
All changes and new features are submitted as pull requests, which can then be tested, reviewed and (hopefully) merged into the master branch. Every time there is a change in the major version number, a new release is published. This usually happens every 2 weeks, on a Sunday.
|
||||
|
||||
When a PR is opened:
|
||||
- The feature branch is built, and deployed as a Netlify instance. This can be accessed at: `https://deploy-preview-[pr-number]--dashy-dev.netlify.app`, and this URL as well as a link to the build logs are added as a comment on the PR by Netlify bot
|
||||
- Depending on what files were modified, the bot may also add a comment to remind the author of useful info
|
||||
- A series of checks will run on the new code, using GH Actions, and prevent merging if they fail. This includes: linting, testing, code quality and complexity checking, security scanning and a spell check
|
||||
- If a new dependency was added, liss-bot will comment with a summary of those changes, as well as the cost of the module, version, and any security concerns. If the bundle size has increased, this will also be added as a comment
|
||||
|
||||
After the PR is merged:
|
||||
- The app is build, and deployed to: https://dev.dashy.to
|
||||
- A new tag in GitHub is created, using the apps version number (from the package.json)
|
||||
- The Docker container is built, and published under the `:latest` tag on DockerHub and GHCR
|
||||
|
||||
When a new major version is released:
|
||||
- A new GitHub release is created and published, under new versions tag, with info from the changelog
|
||||
- The container is built and published under a new tag will be created on DockerHub, called `:release-[version]`
|
||||
- An announcement is opened in GitHub discussions, outlining the main changes, where users can comment and ask questions
|
||||
|
||||
[](https://app.netlify.com/sites/dashy-dev/deploys)
|
||||
|
||||
---
|
||||
|
||||
## Git Strategy
|
||||
|
||||
### Git Flow
|
||||
Like most Git repos, we are following the [Github Flow](https://guides.github.com/introduction/flow) standard.
|
||||
|
||||
1. Create a branch (or fork if you don'd have write acces)
|
||||
2. Code some awesome stuff, then add and commit your changes
|
||||
3. Create a Pull Request, complete the checklist and ensure the build succeeds
|
||||
4. Follow up with any reviews on your code
|
||||
5. Merge 🎉
|
||||
|
||||
### Git Branch Naming
|
||||
The format of your branch name should be something similar to: `[TYPE]/[TICKET]_[TITLE]`
|
||||
For example, `FEATURE/420_Awesome-feature` or `FIX/690_login-server-error`
|
||||
|
||||
### Commit Emojis
|
||||
Using a single emoji at the start of each commit message, to indicate the type task, makes the commit ledger easier to understand, plus it looks cool.
|
||||
|
||||
- 🎨 `:art:` - Improve structure / format of the code.
|
||||
- ⚡️ `:zap:` - Improve performance.
|
||||
- 🔥 `:fire:` - Remove code or files.
|
||||
- 🐛 `:bug:` - Fix a bug.
|
||||
- 🚑️ `:ambulance:` - Critical hotfix
|
||||
- ✨ `:sparkles:` - Introduce new features.
|
||||
- 📝 `:memo:` - Add or update documentation.
|
||||
- 🚀 `:rocket:` - Deploy stuff.
|
||||
- 💄 `:lipstick:` - Add or update the UI and style files.
|
||||
- 🎉 `:tada:` - Begin a project.
|
||||
- ✅ `:white_check_mark:` - Add, update, or pass tests.
|
||||
- 🔒️ `:lock:` - Fix security issues.
|
||||
- 🔖 `:bookmark:` - Make a Release or Version tag.
|
||||
- 🚨 `:rotating_light:` - Fix compiler / linter warnings.
|
||||
- 🚧 `:construction:` - Work in progress.
|
||||
- ⬆️ `:arrow_up:` - Upgrade dependencies.
|
||||
- 👷 `:construction_worker:` - Add or update CI build system.
|
||||
- ♻️ `:recycle:` - Refactor code.
|
||||
- 🩹 `:adhesive_bandage:` - Simple fix for a non-critical issue.
|
||||
- 🔧 `:wrench:` - Add or update configuration files.
|
||||
- 🍱 `:bento:` - Add or update assets.
|
||||
- 🗃️ `:card_file_box:` - Perform database schema related changes.
|
||||
- ✏️ `:pencil2:` - Fix typos.
|
||||
- 🌐 `:globe_with_meridians:` - Internationalization and translations.
|
||||
|
||||
For a full list of options, see [gitmoji.dev](https://gitmoji.dev/)
|
||||
|
||||
### PR Guidelines
|
||||
Once you've made your changes, and pushed them to your fork or branch, you're ready to open a pull request!
|
||||
|
||||
For a pull request to be merged, it must:
|
||||
- Must be backwards compatible
|
||||
- The build, lint and tests (run by GH actions) must pass
|
||||
- There must not be any merge conflicts
|
||||
|
||||
When you submit your PR, include the required info, by filling out the PR template. Including:
|
||||
- A brief description of your changes
|
||||
- The issue, ticket or discussion number (if applicable)
|
||||
- For UI relate updates include a screenshot
|
||||
- If any dependencies were added, explain why it was needed, state the cost associated, and confirm it does not introduce any security issues
|
||||
- Finally, check the checkboxes, to confirm that the standards are met, and hit submit!
|
||||
|
||||
---
|
||||
|
||||
## Automated Workflows
|
||||
|
||||
Dashy makes heavy use of [GitHub Actions](https://github.com/features/actions) to fully automate the checking, testing, building, deploying of the project, as well as administration tasks like management of issues, tags, releases and documentation. The following section outlines each workflow, along with a link the the action file, current status and short description. A lot of these automations were made possible using community actions contributed to GH marketplace by some amazing people.
|
||||
|
||||
|
||||
### Code Processing
|
||||
|
||||
Action | Description
|
||||
--- | ---
|
||||
**Code Linter**<br/>[](https://github.com/Lissy93/dashy/actions/workflows/code-linter.yml) | After a pull request is created, all new code changes will be linted, and the CI will fail with a helpful message if the code has any formatting inconsistencies
|
||||
**Code Spell Check**<br/>[](https://github.com/Lissy93/dashy/actions/workflows/code-spell-check.yml) | After a PR submitted, all auto-fixable spelling errors will be detected, then Liss-Bot will create a separate PR to propose the fixes
|
||||
**Dependency Update Summary** <br/>[](https://github.com/Lissy93/dashy/actions/workflows/dependency-updates-summary.yml) | After a PR is submitted, if any of the dependencies are modified, then Liss-Bot will add a comment, explaining which packages have been added, removed, updated or downgraded, as well as other helpful info
|
||||
**Get Size** <br/>[](https://github.com/Lissy93/dashy/actions/workflows/get-size.yml) | Adds comment to PR if the size of the built + bundled application has changed compared to the previous version
|
||||
**Security Scan** <br/>[](https://github.com/Lissy93/dashy/actions/workflows/security-scanning.yml) | Uses Snyk to scan the code and dependencies after a PR. Will add a comment and cause the build to fail if a new vulnerability or potential issue is present
|
||||
|
||||
### Releases
|
||||
|
||||
Action | Description
|
||||
--- | ---
|
||||
**Create Tag** <br/>[](https://github.com/Lissy93/dashy/actions/workflows/auto-tag-pr.yml) | Whenever the version indicated in package.json is updates, a new GitHub tag will be created for that point in time
|
||||
**Build App** <br/>[](https://github.com/Lissy93/dashy/actions/workflows/build-app.yml) | After changes are merged into the master branch, the app will be build, with output pushed to the `dev-demo` branch
|
||||
**Cache Artifacts** <br/>[](https://github.com/Lissy93/dashy/actions/workflows/cache-artifacts.yml) | After build, returned files will be cached for future actions for that commit
|
||||
**Docker Publish** <br/>[](https://github.com/Lissy93/dashy/actions/workflows/docker-publish.yml) | After PR is merged, the multi-architecture Docker container will be built, and then published to GHCR
|
||||
|
||||
### Issue Management
|
||||
|
||||
Action | Description
|
||||
--- | ---
|
||||
**Close Incomplete Issues** <br/>[](https://github.com/Lissy93/dashy/actions/workflows/close-incomplete-issues.yml) | Issues which do not match any of the issue templates will be closed, and a comment posted explaining why
|
||||
**Close Stale Issues** <br/>[](https://github.com/Lissy93/dashy/actions/workflows/close-stale-issues.yml) | Issues which have not been updated for 6 weeks will have a comment posted to them. If the author does not reply within the next week, then the issue will be marked as stale and closed. The original author may still reopen the issue at any time
|
||||
**Close Potential Spam Issues** <br/>[](https://github.com/Lissy93/dashy/actions/workflows/issue-spam-control.yml) | Auto-closes issues, and adds a comment if it was submitted by a user who hasn't yet interacted with the repo, is new to GitHub and has not starred the repository. The comment will advise them to check their issue is complete, and then allow them to reopen it
|
||||
**Issue Translator** <br/>[](https://github.com/Lissy93/dashy/actions/workflows/issue-translator.yml) | Auto-translates any comments and issues that were written in any language other than English, and posts the translation as a comment below
|
||||
**Label Sponsors** <br/>[](https://github.com/Lissy93/dashy/actions/workflows/label-sponsors.yml) | Adds a special label to any issues or pull requests raised by users who are sponsoring the project via GitHub, so that they can get priority support
|
||||
**LGTM Comment**<br/>[](https://github.com/Lissy93/dashy/actions/workflows/lgtm-comment.yml) | When a PR review contains the words LGTM (looks good to me), the Liss-Bot will reply with a random celebratory or thumbs up GIF, just as a bit of fun
|
||||
**Mind your Language** <br/>[](https://github.com/Lissy93/dashy/actions/workflows/mind-your-language.yml) | Replies to any comment (on issue or PR) that contains profanities, offensive or inappropriate language with a polite note reminding the user of the code of conduct
|
||||
**Release Notifier** <br/>[](https://github.com/Lissy93/dashy/actions/workflows/release-commenter.yml) | Once a release has been published which fixes an issue, a comment will be added to the relevant issues informing the user who raised it that it was fixed in the current release
|
||||
**Update Issue after Merge** <br/>[](https://github.com/Lissy93/dashy/actions/workflows/update-issue-after-pr.yml) | After a PR which fixes an issue is merged, Liss-Bot will add a comment to said issue based on the git commit message
|
||||
**Auto Add Comment Based on Tag** <br/>[](https://github.com/Lissy93/dashy/actions/workflows/add-comment-from-tag.yml) | Will add comment with useful info to certain issues, based on the tag applied
|
||||
|
||||
### PR Management
|
||||
|
||||
Action | Description
|
||||
--- | ---
|
||||
**PR Commenter** <br/>[](https://github.com/Lissy93/dashy/actions/workflows/pr-commenter.yml) | Adds comment with helpful info to pull requests, based on which files have been changes
|
||||
**Issue from Todo Code** <br/>[](https://github.com/Lissy93/dashy/actions/workflows/raise-issue-from-todo.yml) | When a `todo` note is found in the code after a PR, then Liss-Bot will automatically raise an issue, so that the todo can be addressed/ implemented. The issue will be closed once the todo has been implemented or removed
|
||||
|
||||
### Documentation & Reports
|
||||
|
||||
Action | Description
|
||||
--- | ---
|
||||
**Generate Credits** <br/>[](https://github.com/Lissy93/dashy/actions/workflows/generate-credits.yml) | Generates a report, including contributors, collaborators, sponsors, bots and helpful users. Will then insert a markdown table with thanks to these GitHub users and links to their profiles into the Credits page, as well as a summary of sponsors and top contributors into the main readme
|
||||
**Wiki Sync** <br/>[](https://github.com/Lissy93/dashy/actions/workflows/wiki-sync.yml) | Generates and publishes the repositories wiki page using the markdown files within the docs directory
|
||||
|
||||
---
|
||||
@ -1,83 +1,107 @@
|
||||
# Keyboard Shortcuts
|
||||
|
||||
## Searching
|
||||
One of the primary purposes of Dashy is to allow you to quickly find and launch a given app. To make this as quick as possible, there is no need to touch the mouse, or press a certain key to begin searching - just start typing. Results will be filtered in real-time. No need to worry about case, special characters or small typos, these are taken care of, and your results should appear.
|
||||
|
||||
## Navigating
|
||||
You can navigate through your items or search results using the keyboard. You can use <kbd>Tab</kbd> to cycle through results, and <kbd>Shift</kbd> + <kbd>Tab</kbd> to go backwards. Or use the arrow keys, <kbd>↑</kbd>, <kbd>→</kbd>, <kbd>↓</kbd> and <kbd>←</kbd>.
|
||||
|
||||
## Launching Apps
|
||||
You can launch a elected app by hitting <kbd>Enter</kbd>. This will open the app using your default opening method, specified in `target` (either `newtab`, `sametab`, `modal` or `workspace`). You can also use <kbd>Alt</kbd> + <kbd>Enter</kbd> to open the app in a pop-up modal, or <kbd>Ctrl</kbd> + <kbd>Enter</kbd> to open it in a new tab. For all available opening methods, just right-click on an item, to bring up the context menu.
|
||||
|
||||
## Tags
|
||||
By default, items are filtered by the `title` attribute, as well as the hostname (extracted from `url`), the `provider` and `description`. If you need to find results based on text which isn't included in these attributes, then you can add `tags` to a given item.
|
||||
|
||||
```yaml
|
||||
items:
|
||||
- title: Plex
|
||||
description: Media library
|
||||
icon: favicon
|
||||
url: https://plex.lab.local
|
||||
tags: [ movies, videos, music ]
|
||||
- title: FreshRSS
|
||||
description: RSS Reader
|
||||
icon: favicon
|
||||
url: https://freshrss.lab.local
|
||||
tags: [ news, updates, blogs ]
|
||||
|
||||
```
|
||||
|
||||
In the above example, Plex will be visible when searching for 'movies', and FreshRSS with 'news'
|
||||
|
||||
|
||||
## Custom Hotkeys
|
||||
For apps that you use regularly, you can set a custom keybinding. Use the `hotkey` parameter on a certain item to specify a numeric key, between `0 - 9`. You can then launch that app, by just pressing that key, which is much quicker than searching for it, if it's an app you use frequently.
|
||||
|
||||
```yaml
|
||||
- title: Bookstack
|
||||
icon: far fa-books
|
||||
url: https://bookstack.lab.local/
|
||||
hotkey: 2
|
||||
- title: Git Tea
|
||||
icon: fab fa-git
|
||||
url: https://git.lab.local/
|
||||
target: workspace
|
||||
hotkey: 3
|
||||
```
|
||||
|
||||
In the above example, pressing <kbd>2</kbd> will launch Bookstack. Or hitting <kbd>3</kbd> will open Git in the workspace view.
|
||||
|
||||
## Web Search
|
||||
It's possible to search the web directly from Dashy, which might be useful if you're using Dashy as your start page. This can be done by typing your query as normal, and then pressing <kbd>⏎</kbd>. Web search options are configured under `appConfig.webSearch`.
|
||||
|
||||
#### Setting Search Engine
|
||||
Set your default search engine using the `webSearch.searchEngine` property. This defaults to DuckDuckGo. Search engine must be referenced by their key, the following providers are supported:
|
||||
- [`duckduckgo`](https://duckduckgo.com), [`google`](https://google.com), [`whoogle`](https://whoogle.sdf.org), [`qwant`](https://www.qwant.com), [`startpage`](https://www.startpage.com), [`searx-bar`](https://searx.bar), [`searx-info`](https://searx.info)
|
||||
- [`searx-tiekoetter`](https://searx.tiekoetter.com), [`searx-bissisoft`](https://searx.bissisoft.com), [`ecosia`](https://www.ecosia.org), [`metager`](https://metager.org/meta), [`swisscows`](https://swisscows.com), [`mojeek`](https://www.mojeek.com)
|
||||
- [`wikipedia`](https://en.wikipedia.org), [`wolframalpha`](https://www.wolframalpha.com), [`stackoverflow`](https://stackoverflow.com), [`github`](https://github.com), [`reddit`](https://www.reddit.com), [`youtube`](https://youtube.com), [`bbc`](https://www.bbc.co.uk)
|
||||
|
||||
#### Using Custom Search Engine
|
||||
You can also use a custom search engine, that isn't included in the above list (like a self-hosted instance of [Whoogle](https://github.com/benbusby/whoogle-search) or [Searx](https://searx.github.io/searx/)). Set `searchEngine: custom`, and then specify the URL (plus query params) to you're search engine under `customSearchEngine`.
|
||||
|
||||
For example:
|
||||
```yaml
|
||||
appConfig:
|
||||
webSearch:
|
||||
searchEngine: custom
|
||||
customSearchEngine: 'https://searx.local/search?q='
|
||||
```
|
||||
|
||||
#### Setting Opening Method
|
||||
In a similar way to opening apps, you can specify where you would like search results to be opened. This is done under the `openingMethod` attribute, and can be set to either `newtab`, `sametab` or `workspace`. By default results are opened in a new tab.
|
||||
|
||||
#### Disabling Web Search
|
||||
Web search can be disabled, by setting `disableWebSearch`, for example:
|
||||
|
||||
```yaml
|
||||
appConfig:
|
||||
webSearch: { disableWebSearch: true }
|
||||
```
|
||||
|
||||
## Clearing Search
|
||||
You can clear your search term at any time, by pressing <kbd>Esc</kbd>.
|
||||
This can also be used to close an open pop-up modal.
|
||||
# Keyboard Shortcuts
|
||||
|
||||
## Searching
|
||||
One of the primary purposes of Dashy is to allow you to quickly find and launch a given app. To make this as quick as possible, there is no need to touch the mouse, or press a certain key to begin searching - just start typing. Results will be filtered in real-time. No need to worry about case, special characters or small typos, these are taken care of, and your results should appear.
|
||||
|
||||
## Navigating
|
||||
You can navigate through your items or search results using the keyboard. You can use <kbd>Tab</kbd> to cycle through results, and <kbd>Shift</kbd> + <kbd>Tab</kbd> to go backwards. Or use the arrow keys, <kbd>↑</kbd>, <kbd>→</kbd>, <kbd>↓</kbd> and <kbd>←</kbd>.
|
||||
|
||||
## Launching Apps
|
||||
You can launch a elected app by hitting <kbd>Enter</kbd>. This will open the app using your default opening method, specified in `target` (either `newtab`, `sametab`, `modal` or `workspace`). You can also use <kbd>Alt</kbd> + <kbd>Enter</kbd> to open the app in a pop-up modal, or <kbd>Ctrl</kbd> + <kbd>Enter</kbd> to open it in a new tab. For all available opening methods, just right-click on an item, to bring up the context menu.
|
||||
|
||||
## Tags
|
||||
By default, items are filtered by the `title` attribute, as well as the hostname (extracted from `url`), the `provider` and `description`. If you need to find results based on text which isn't included in these attributes, then you can add `tags` to a given item.
|
||||
|
||||
```yaml
|
||||
items:
|
||||
- title: Plex
|
||||
description: Media library
|
||||
icon: favicon
|
||||
url: https://plex.lab.local
|
||||
tags: [ movies, videos, music ]
|
||||
- title: FreshRSS
|
||||
description: RSS Reader
|
||||
icon: favicon
|
||||
url: https://freshrss.lab.local
|
||||
tags: [ news, updates, blogs ]
|
||||
|
||||
```
|
||||
|
||||
In the above example, Plex will be visible when searching for 'movies', and FreshRSS with 'news'
|
||||
|
||||
|
||||
## Custom Hotkeys
|
||||
For apps that you use regularly, you can set a custom keybinding. Use the `hotkey` parameter on a certain item to specify a numeric key, between `0 - 9`. You can then launch that app, by just pressing that key, which is much quicker than searching for it, if it's an app you use frequently.
|
||||
|
||||
```yaml
|
||||
- title: Bookstack
|
||||
icon: far fa-books
|
||||
url: https://bookstack.lab.local/
|
||||
hotkey: 2
|
||||
- title: Git Tea
|
||||
icon: fab fa-git
|
||||
url: https://git.lab.local/
|
||||
target: workspace
|
||||
hotkey: 3
|
||||
```
|
||||
|
||||
In the above example, pressing <kbd>2</kbd> will launch Bookstack. Or hitting <kbd>3</kbd> will open Git in the workspace view.
|
||||
|
||||
## Web Search
|
||||
It's possible to search the web directly from Dashy, which might be useful if you're using Dashy as your start page. This can be done by typing your query as normal, and then pressing <kbd>⏎</kbd>. Web search options are configured under `appConfig.webSearch`.
|
||||
|
||||
### Setting Search Engine
|
||||
Set your default search engine using the `webSearch.searchEngine` property. This defaults to DuckDuckGo. Search engine must be referenced by their key, the following providers are supported:
|
||||
- [`duckduckgo`](https://duckduckgo.com), [`google`](https://google.com), [`whoogle`](https://whoogle.sdf.org), [`qwant`](https://www.qwant.com), [`startpage`](https://www.startpage.com), [`searx-bar`](https://searx.bar), [`searx-info`](https://searx.info)
|
||||
- [`searx-tiekoetter`](https://searx.tiekoetter.com), [`searx-bissisoft`](https://searx.bissisoft.com), [`ecosia`](https://www.ecosia.org), [`metager`](https://metager.org/meta), [`swisscows`](https://swisscows.com), [`mojeek`](https://www.mojeek.com)
|
||||
- [`wikipedia`](https://en.wikipedia.org), [`wolframalpha`](https://www.wolframalpha.com), [`stackoverflow`](https://stackoverflow.com), [`github`](https://github.com), [`reddit`](https://www.reddit.com), [`youtube`](https://youtube.com), [`bbc`](https://www.bbc.co.uk)
|
||||
|
||||
### Using Custom Search Engine
|
||||
You can also use a custom search engine, that isn't included in the above list (like a self-hosted instance of [Whoogle](https://github.com/benbusby/whoogle-search) or [Searx](https://searx.github.io/searx/)). Set `searchEngine: custom`, and then specify the URL (plus query params) to you're search engine under `customSearchEngine`.
|
||||
|
||||
For example:
|
||||
```yaml
|
||||
appConfig:
|
||||
webSearch:
|
||||
searchEngine: custom
|
||||
customSearchEngine: 'https://searx.local/search?q='
|
||||
```
|
||||
|
||||
### Setting Opening Method
|
||||
In a similar way to opening apps, you can specify where you would like search results to be opened. This is done under the `openingMethod` attribute, and can be set to either `newtab`, `sametab` or `workspace`. By default results are opened in a new tab.
|
||||
|
||||
### Using Bangs
|
||||
An insanely useful feature of DDG is [Bangs](https://duckduckgo.com/bang), where you type a specific character combination at the start of your search query, and it will be redirected the that website, such as '!w Docker' will display the Docker wikipedia page. Dashy has a similar feature, enabling you to define your own custom bangs to redirect search results to a specific app, website or search engine.
|
||||
|
||||
This is done under the `searchBangs` property, with a list of key value pairs. The key is what you will type, and the value is the destination, either as an identifier or a URL with query parameters.
|
||||
|
||||
For example:
|
||||
|
||||
```yaml
|
||||
appConfig:
|
||||
webSearch:
|
||||
searchEngine: 'duckduckgo'
|
||||
openingMethod: 'newtab'
|
||||
searchBangs:
|
||||
/r: reddit
|
||||
/w: wikipedia
|
||||
/s: https://whoogle.local/search?q=
|
||||
/a: https://www.amazon.co.uk/s?k=
|
||||
':wolf': wolframalpha
|
||||
':so': stackoverflow
|
||||
':git': github
|
||||
```
|
||||
|
||||
Note that bangs begging with `!` or `:` must be surrounded them in quotes
|
||||
|
||||
### Disabling Web Search
|
||||
Web search can be disabled, by setting `disableWebSearch`, for example:
|
||||
|
||||
```yaml
|
||||
appConfig:
|
||||
webSearch: { disableWebSearch: true }
|
||||
```
|
||||
|
||||
## Clearing Search
|
||||
You can clear your search term at any time, resting the UI to it's initial state, by pressing <kbd>Esc</kbd>.
|
||||
This can also be used to close any open pop-up modals.
|
||||
|
||||
@ -54,6 +54,13 @@
|
||||
|
||||
---
|
||||
|
||||
### First Week of Self-Hosting
|
||||
> By [u//RickyCZ](https://www.reddit.com/user/RickyCZ)
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
### Ground Control
|
||||
> By [@dtctek](https://github.com/dtctek)
|
||||
|
||||
|
||||
BIN
docs/showcase/11-ricky-cz.png
Normal file
BIN
docs/showcase/11-ricky-cz.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 176 KiB |
@ -3,7 +3,7 @@
|
||||
Dashy has an optional feature that can display a small icon next to each of your running services, indicating it's current status. This can be useful if you are using Dashy as your homelab's start page, as it gives you an overview of the health of each of your running services. The status feature will show response time, response code, online/ offline check and if applicable, a relevant error message
|
||||
|
||||
<p align="center">
|
||||
<img width="800" src="https://raw.githubusercontent.com/Lissy93/dashy/master/docs/assets/status-check-demo.gif" />
|
||||
<img width="800" src="/docs/assets/status-check-demo.gif" />
|
||||
</p>
|
||||
|
||||
## Enabling Status Indicators
|
||||
@ -42,7 +42,7 @@ By default, with status indicators enabled Dashy will check an applications stat
|
||||
|
||||
The following example, will instruct Dashy to continuously check the status of your services every 20 seconds
|
||||
|
||||
```yaml
|
||||
```
|
||||
appConfig:
|
||||
statusCheck: true
|
||||
statusCheckInterval: 20
|
||||
@ -70,9 +70,13 @@ Vary: Origin
|
||||
```
|
||||
If the URL you are checking is not using HTTPS, then you may need to disable the rejection of insecure requests. This can be done by setting `statusCheckAllowInsecure` to true for a given item.
|
||||
|
||||
If you're serving Dashy though a CDN, instead of using the Node server or Docker image, then the Node endpoint that makes requests will not be available to you, and all requests will fail. A workaround for this may be implemented in the future, but in the meantime, your only option is to use the Docker or Node deployment method.
|
||||
If you get an error, like `Service Unavailable: Server resulted in a fatal error`, even when it's definitely online, this is most likely caused by missing the protocol. Don't forget to include `https://` (or whatever protocol) before the URL, and ensure that if needed, you've specified the port.
|
||||
|
||||
For further troubleshooting, use an application like [Postman](https://postman.com) to diagnose the issue.
|
||||
Currently, the status check needs a page to be rendered, so if this URL in your browser does not return anything, then status checks will not work. This may be modified in the future, but in the meantime, a fix would be to make your own status service, which just checks if your app responds with whatever code you'd like, and then return a 200 plus renders an arbitrary message. Then just point `statusCheckUrl` to your custom page.
|
||||
|
||||
For further troubleshooting, use an application like [Postman](https://postman.com) to diagnose the issue. Set the parameter to `GET`, and then make a call to: `https://[url-of-dashy]/ping/?&url=[service-url]`. Where the service URL must have first been encoded (e.g. with `encodeURIComponent()` or [urlencoder.io](https://www.urlencoder.io/))
|
||||
|
||||
If you're serving Dashy though a CDN, instead of using the Node server or Docker image, then the Node endpoint that makes requests will not be available to you, and all requests will fail. A workaround for this may be implemented in the future, but in the meantime, your only option is to use the Docker or Node deployment method.
|
||||
|
||||
## How it Works
|
||||
|
||||
|
||||
@ -135,3 +135,25 @@ Just add the [-host-header](https://ngrok.com/docs#http-host-header) flag, e.g.
|
||||
|
||||
## Warnings in the Console during deploy
|
||||
Please acknowledge the difference between errors and warnings before raising an issue about messages in the console. It's not unusual to see warnings about a new version of a certain package being available, an asset bundle bing oversized or a service worker not yet having a cache. These shouldn't have any impact on the running application, so please don't raise issues about these unless it directly relates to a bug or issue you're experiencing. Errors on the other hand should not appear in the console, and they are worth looking into further.
|
||||
|
||||
---
|
||||
|
||||
## Status Checks Failing
|
||||
If you're using status checks, and despite a given service being online, the check is displaying an error, there are a couple of things you can look at:
|
||||
|
||||
If your service requires requests to include any authorization in the headers, then use the `statusCheckHeaders` property, as described in the [docs](/docs/status-indicators#setting-custom-headers).
|
||||
|
||||
If you are still having issues, it may be because your target application is blocking requests from Dashy's IP. This is a [CORS error](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS), and can be fixed by setting the headers on your target app, to include:
|
||||
```
|
||||
Access-Control-Allow-Origin: https://location-of-dashy/
|
||||
Vary: Origin
|
||||
```
|
||||
If the URL you are checking has an unsigned certificate, or is not using HTTPS, then you may need to disable the rejection of insecure requests. This can be done by setting `statusCheckAllowInsecure` to true for a given item.
|
||||
|
||||
If you get an error, like `Service Unavailable: Server resulted in a fatal error`, even when it's definitely online, this is most likely caused by missing the protocol. Don't forget to include `https://` (or whatever protocol) before the URL, and ensure that if needed, you've specified the port.
|
||||
|
||||
Currently, the status check needs a page to be rendered, so if this URL in your browser does not return anything, then status checks will not work. This may be modified in the future, but in the meantime, a fix would be to make your own status service, which just checks if your app responds with whatever code you'd like, and then return a 200 plus renders an arbitrary message. Then just point `statusCheckUrl` to your custom page.
|
||||
|
||||
For further troubleshooting, use an application like [Postman](https://postman.com) to diagnose the issue. Set the parameter to `GET`, and then make a call to: `https://[url-of-dashy]/ping/?&url=[service-url]`. Where the service URL must have first been encoded (e.g. with `encodeURIComponent()` or [urlencoder.io](https://www.urlencoder.io/))
|
||||
|
||||
If you're serving Dashy though a CDN, instead of using the Node server or Docker image, then the Node endpoint that makes requests will not be available to you, and all requests will fail. A workaround for this may be implemented in the future, but in the meantime, your only option is to use the Docker or Node deployment method.
|
||||
Loading…
x
Reference in New Issue
Block a user