diff --git a/docs/assets/CONTRIBUTORS.svg b/docs/assets/CONTRIBUTORS.svg index a3c5791c..1a583d00 100644 --- a/docs/assets/CONTRIBUTORS.svg +++ b/docs/assets/CONTRIBUTORS.svg @@ -1,4 +1,4 @@ - + @@ -12,85 +12,109 @@ + + + - - - - - - - - - - + - + + + + + + + + + + + + + - + - + - - - - - - - - - - - - - + - + + + + + + + + + + + + + - + - + + + + - + - + - + + + + - + + + + + + + + + + - + - + - + - + - + + + + - + - + - + \ No newline at end of file diff --git a/docs/assets/repo-visualization.svg b/docs/assets/repo-visualization.svg index 0e36fbe2..a8610168 100644 --- a/docs/assets/repo-visualization.svg +++ b/docs/assets/repo-visualization.svg @@ -1 +1 @@ -viewsviewsutilsutilsstylesstylesmixinsmixinsdirectivesdirectivescomponentscomponentsassetsassetsWorkspaceWorkspaceWidgetsWidgetsSettingsSettingsPageStrcturePageStrctureMinimalViewMinimalViewLinkItemsLinkItemsInteractiveEditorInteractiveEditorFormElementsFormElementsConfigurationConfigurationChartsChartslocaleslocalesinterface-iconsinterface-iconsLogin.vueLogin.vueLogin.vueHome.vueHome.vueHome.vueemojis.jsonemojis.jsonemojis.jsonConfigSch...ConfigSch...ConfigSch...defaults.jsdefaults.jsdefaults.jscolor-the...color-the...color-the...store.jsstore.jsstore.jsWidgetBas...WidgetBas...WidgetBas...AnonAddy.vueAnonAddy.vueAnonAddy.vueSportsSc...SportsSc...SportsSc...CustomThe...CustomThe...CustomThe...Section.vueSection.vueSection.vueItem.vueItem.vueItem.vueItemIcon.vueItemIcon.vueItemIcon.vueEditItem.vueEditItem.vueEditItem.vueEditMode...EditMode...EditMode...JsonEdito...JsonEdito...JsonEdito...ConfigCon...ConfigCon...ConfigCon...CloudBac...CloudBac...CloudBac...Gauge.vueGauge.vueGauge.vuehi.jsonhi.jsonhi.jsonit.jsonit.jsonit.jsonfr.jsonfr.jsonfr.jsonsv.jsonsv.jsonsv.jsonen.jsonen.jsonen.jsonru.jsonru.jsonru.jsonsl.jsonsl.jsonsl.jsonar.jsonar.jsonar.jsonja.jsonja.jsonja.json.js.json.scss.svg.vueeach dot sized by file size \ No newline at end of file +viewsviewsutilsutilsstylesstylesmixinsmixinsdirectivesdirectivescomponentscomponentsassetsassetsWorkspaceWorkspaceWidgetsWidgetsSettingsSettingsPageStrcturePageStrctureMinimalViewMinimalViewLinkItemsLinkItemsInteractiveEditorInteractiveEditorFormElementsFormElementsConfigurationConfigurationChartsChartslocaleslocalesinterface-iconsinterface-iconsLogin.vueLogin.vueLogin.vueemojis.jsonemojis.jsonemojis.jsonConfigSch...ConfigSch...ConfigSch...defaults.jsdefaults.jsdefaults.jscolor-the...color-the...color-the...store.jsstore.jsstore.jsWidgetBas...WidgetBas...WidgetBas...AnonAddy.vueAnonAddy.vueAnonAddy.vueCustomTh...CustomTh...CustomTh...Section.vueSection.vueSection.vueItemIcon...ItemIcon...ItemIcon...Item.vueItem.vueItem.vueEditItem...EditItem...EditItem...ConfigCon...ConfigCon...ConfigCon...Gauge.vueGauge.vueGauge.vuebg.jsonbg.jsonbg.jsonhi.jsonhi.jsonhi.jsonpt.jsonpt.jsonpt.jsonit.jsonit.jsonit.jsonfr.jsonfr.jsonfr.jsonen.jsonen.jsonen.jsonsv.jsonsv.jsonsv.jsonru.jsonru.jsonru.jsonsl.jsonsl.jsonsl.json.js.json.scss.svg.vueeach dot sized by file size \ No newline at end of file diff --git a/docs/authentication.md b/docs/authentication.md index cc693086..09904fa8 100644 --- a/docs/authentication.md +++ b/docs/authentication.md @@ -45,13 +45,13 @@ A hash is a one-way cryptographic function, meaning that it is easy to generate Once authentication is enabled, so long as there is no valid token in cookie storage, the application will redirect the user to the login page. When the user enters credentials in the login page, they will be checked, and if valid, then a token will be generated, and they can be redirected to the home page. If credentials are invalid, then an error message will be shown, and they will remain on the login page. Once in the application, to log out the user can click the logout button (in the top-right), which will clear cookie storage, causing them to be redirected back to the login page. ### Enabling Guest Access -With authentication setup, by default no access is allowed to your dashboard without first logging in with valid credentials. Guest mode can be enabled to allow for read-only access to a secured dashboard by any user, without the need to log in. A guest user cannot write any changes to the config file, but can apply modifications locally (stored in their browser). You can enable guest access, by setting `appConfig.enableGuestAccess: true`. +With authentication setup, by default no access is allowed to your dashboard without first logging in with valid credentials. Guest mode can be enabled to allow for read-only access to a secured dashboard by any user, without the need to log in. A guest user cannot write any changes to the config file, but can apply modifications locally (stored in their browser). You can enable guest access, by setting `appConfig.auth.enableGuestAccess: true`. ### Granular Access -You can use the following properties to make certain sections only visible to some users, or hide sections from guests. -- `hideForUsers` - Section will be visible to all users, except for those specified in this list -- `showForUsers` - Section will be hidden from all users, except for those specified in this list -- `hideForGuests` - Section will be visible for logged in users, but not for guests +You can use the following properties to make certain sections or items only visible to some users, or hide sections and items from guests. +- `hideForUsers` - Section or Item will be visible to all users, except for those specified in this list +- `showForUsers` - Section or Item will be hidden from all users, except for those specified in this list +- `hideForGuests` - Section or Item will be visible for logged in users, but not for guests For Example: @@ -71,7 +71,9 @@ For Example: displayData: hideForGuests: true items: - ... + - title: Hide Me + displayData: + hideForUsers: [alicia, bob] ``` ### Permissions @@ -146,10 +148,12 @@ appConfig: clientId: 'dashy' ``` +Note that if you are using Keycloak V 17 or older, you will also need to set `legacySupport: true` (also under `appConfig.auth.keycloak`). This is because the API endpoint was updated in later versions. + ### 4. Add groups and roles (Optional) -Keycloak allows you to assign users roles and groups. You can use these values to configure who can access various sections in Dashy. +Keycloak allows you to assign users roles and groups. You can use these values to configure who can access various sections or items in Dashy. Keycloak server administration and configuration is a deep topic; please refer to the [server admin guide](https://www.keycloak.org/docs/latest/server_admin/index.html#assigning-permissions-and-access-using-roles-and-groups) to see details about creating and assigning roles and groups. -Once you have groups or roles assigned to users you can configure access under each sections `displayData.showForKeycloakUser` and `displayData.hideForKeycloakUser`. +Once you have groups or roles assigned to users you can configure access under each section or item `displayData.showForKeycloakUser` and `displayData.hideForKeycloakUser`. Both show and hide configurations accept a list of `groups` and `roles` that limit access. If a users data matches one or more items in these lists they will be allowed or excluded as defined. ```yaml sections: @@ -159,6 +163,11 @@ sections: roles: ['canViewDevResources'] hideForKeycloakUsers: groups: ['ProductTeam'] + items: + - title: Not Visible for developers + displayData: + hideForKeycloakUsers: + groups: ['DevelopmentTeam'] ``` Depending on how you're hosting Dashy and Keycloak, you may also need to set some HTTP headers, to prevent a CORS error. This would typically be the `Access-Control-Allow-Origin [URL-of Dashy]` on your Keycloak instance. See the [Setting Headers](https://github.com/Lissy93/dashy/blob/master/docs/management.md#setting-headers) guide in the management docs for more info. diff --git a/docs/backup-restore.md b/docs/backup-restore.md index c130b241..2c6b2158 100644 --- a/docs/backup-restore.md +++ b/docs/backup-restore.md @@ -1,5 +1,3 @@ -# Backup and Restore - ### Cloud Backup and Restore Dashy has a built-in feature for securely backing up your config to a hosted cloud service, and then restoring it on another instance. This feature is totally optional, and if you do not enable it, then Dashy will not make any external network requests. diff --git a/docs/configuring.md b/docs/configuring.md index e1fb6f31..bd4b914c 100644 --- a/docs/configuring.md +++ b/docs/configuring.md @@ -36,10 +36,12 @@ The following file provides a reference of all supported configuration options. - [`keycloak`](#appconfigauthkeycloak-optional) - Auth config for Keycloak - [**`sections`**](#section) - List of sections - [`displayData`](#sectiondisplaydata-optional) - Section display settings - - [`show/hideForKeycloakUsers`](#sectiondisplaydatahideforkeycloakusers-and-sectiondisplaydatashowforkeycloakusers) - Set user controls + - [`show/hideForKeycloakUsers`](#sectiondisplaydatahideforkeycloakusers-sectiondisplaydatashowforkeycloakusers-itemdisplaydatahideforkeycloakusers-and-itemdisplaydatashowforkeycloakusers) - Set user controls - [`icon`](#sectionicon-and-sectionitemicon) - Icon for a section - [`items`](#sectionitem) - List of items - [`icon`](#sectionicon-and-sectionitemicon) - Icon for an item + - [`displayData`](#itemdisplaydata-optional) - Item display settings + - [`show/hideForKeycloakUsers`](#sectiondisplaydatahideforkeycloakusers-sectiondisplaydatashowforkeycloakusers-itemdisplaydatahideforkeycloakusers-and-itemdisplaydatashowforkeycloakusers) - Set user controls - [`widgets`](#sectionwidget-optional) - List of widgets - [**Notes**](#notes) - [Editing Config through the UI](#editing-config-through-the-ui) @@ -163,6 +165,7 @@ For more info, see the **[Authentication Docs](/docs/authentication)** **`serverUrl`** | `string` | Required | The URL (or URL/ IP + Port) where your keycloak server is running **`realm`** | `string` | Required | The name of the realm (must already be created) that you want to use **`clientId`** | `string` | Required | The Client ID of the client you created for use with Dashy +**`legacySupport`** | `boolean` | _Optional_ | If using Keycloak 17 or older, then set this to `true` **[⬆️ Back to Top](#)** @@ -223,9 +226,24 @@ For more info, see the **[Authentication Docs](/docs/authentication)** **`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 +**`displayData`** | `object` | _Optional_ | Meta-data to optionally overide display settings for a given item. See [`displayData`](#itemdisplaydata-optional) **[⬆️ Back to Top](#)** + +### `item.displayData` _(optional)_ + +**Field** | **Type** | **Required**| **Description** +--- | --- | --- | --- +**`hideForUsers`** | `string[]` | _Optional_ | Current item will be visible to all users, except for those specified in this list +**`showForUsers`** | `string[]` | _Optional_ | Current item will be hidden from all users, except for those specified in this list +**`hideForGuests`** | `boolean` | _Optional_ | Current item will be visible for logged in users, but not for guests (see `appConfig.enableGuestAccess`). Defaults to `false` +**`hideForKeycloakUsers`** | `object` | _Optional_ | Current item will be visible to all keycloak users, except for those configured via these groups and roles. See `hideForKeycloakUsers` +**`showForKeycloakUsers`** | `object` | _Optional_ | Current item will be hidden from all keycloak users, except for those configured via these groups and roles. See `showForKeycloakUsers` + +**[⬆️ Back to Top](#)** + + ### `section.widget` _(optional)_ **Field** | **Type** | **Required**| **Description** @@ -258,7 +276,7 @@ For more info, see the **[Authentication Docs](/docs/authentication)** **`showForUsers`** | `string[]` | _Optional_ | Current section will be hidden from all users, except for those specified in this list **`hideForGuests`** | `boolean` | _Optional_ | Current section will be visible for logged in users, but not for guests (see `appConfig.enableGuestAccess`). Defaults to `false` **`hideForKeycloakUsers`** | `object` | _Optional_ | Current section will be visible to all keycloak users, except for those configured via these groups and roles. See `hideForKeycloakUsers` -**`showForKeycloakUsers`** | `object` | _Optional_ | Current section will be hidden from all keyclaok users, except for those configured via these groups and roles. See `showForKeycloakUsers` +**`showForKeycloakUsers`** | `object` | _Optional_ | Current section will be hidden from all keycloak users, except for those configured via these groups and roles. See `showForKeycloakUsers` **[⬆️ Back to Top](#)** @@ -270,12 +288,12 @@ For more info, see the **[Authentication Docs](/docs/authentication)** **[⬆️ Back to Top](#)** -### `section.displayData.hideForKeycloakUsers` and `section.displayData.showForKeycloakUsers` +### `section.displayData.hideForKeycloakUsers`, `section.displayData.showForKeycloakUsers`, `item.displayData.hideForKeycloakUsers` and `item.displayData.showForKeycloakUsers` **Field** | **Type** | **Required**| **Description** --- |------------| --- | --- -**`groups`** | `string[]` | _Optional_ | Current Section will be hidden or shown based on the user having any of the groups in this list -**`roles`** | `string[]` | _Optional_ | Current Section will be hidden or shown based on the user having any of the roles in this list +**`groups`** | `string[]` | _Optional_ | Current Section or Item will be hidden or shown based on the user having any of the groups in this list +**`roles`** | `string[]` | _Optional_ | Current Section or Item will be hidden or shown based on the user having any of the roles in this list **[⬆️ Back to Top](#)** @@ -311,7 +329,7 @@ When updating the config through the JSON editor in the UI, you have two save op If you have authentication set up, then any user who is not an admin (with `type: admin`) will not be able to write changes to disk. -You can also prevent changes fro any user being written to disk, using `preventWriteToDisk`. Or prevent any changes from being saved locally in browser storage, using `preventLocalSave`. +You can also prevent changes from any user being written to disk, using `preventWriteToDisk`. Or prevent any changes from being saved locally in browser storage, using `preventLocalSave`. To disable all UI config features, set `disableConfiguration`. diff --git a/docs/contributing.md b/docs/contributing.md index 696c80e5..0df7d46f 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -1,110 +1,111 @@ -# Contributing - -First off, thank you for considering contributing towards Dashy! πŸ™Œ -There are several ways that you can help out, and any contributions, however small will always be very much appreciated. -You will be appropriately credited in the readme - huge thank you to [everyone who has helped](/docs/credits) so far πŸ’ž - -## Take a 2-minute survey -Help improve Dashy by taking a very short, 6-question survey. This will give me a better understanding of what is important to you, so that I can make Dashy better in the future :) - -[![Take the Survey](https://img.shields.io/badge/Take_the-Survey-%231a86fd?style=for-the-badge&logo=buddy)](https://survey.typeform.com/to/gl0L68ou) - -## Share your dashboard -Dashy now has a [Showcase](https://github.com/Lissy93/dashy/blob/master/docs/showcase.md#dashy-showcase-) where you can show off a screenshot of your dashboard, and get inspiration from other users (and I really love seeing how people are using Dashy). To [submit your dashboard](https://github.com/Lissy93/dashy/blob/master/docs/showcase.md#submitting-your-dashboard), either open a PR or raise an issue. - -[![Add your Dashboard to the Showcase](https://img.shields.io/badge/Add_your_Dashboard-Showcase-%238616ee?style=for-the-badge&logo=feathub&logoColor=8616ee)](https://github.com/Lissy93/dashy/issues/new?assignees=&labels=%F0%9F%92%AF+Showcase&template=showcase-addition.yml&title=%5BSHOWCASE%5D+%3Ctitle%3E) - -## Make a small donation - -Donations help to cover server costs, development time and caffeine ;) -Don't feel any pressure to donate anything, as Dashy and my other projects will always be 100% free, for everyone, for ever. - -[![Sponsor Lissy93 on GitHub](https://img.shields.io/badge/Sponsor_on_GitHub-Lissy93-%23ff4dda?style=for-the-badge&logo=githubsponsors&logoColor=ff4dda)](https://github.com/sponsors/Lissy93) - -Sponsoring will give you several perks - for $1 / Β£0.75 per month, you'll get a sponsor badge on your profile, be credited on the Dashy's readme, with a link to your website/ profile/ socials, get priority support, have your feature ideas implemented, plus lots more. For more info, see [@Lissy93's Sponsor Page](https://github.com/sponsors/Lissy93). - -## Enable Anonymous Bug Reports - -Bug reports helps me to discover bugs I was unaware of, and then fix them, in order to make Dashy more reliable long term. This is a simple, yet really helpful step you can take to help improve Dashy. [Sentry](https://github.com/getsentry/sentry) is an open source error tracking and performance monitoring tool, which enables the identification any errors which occur in the production app (only if you enable it). - -To enable error reporting: -```yaml -appConfig: - enableErrorReporting: true -``` - -All reporting is **disabled** by default, and no data will ever be sent to any external endpoint without your explicit consent. All statistics are anonomized and stored securely. For more about privacy and security, see the [Sentry Security Docs](https://sentry.io/security/). - -## Add Translations -If you speak another language, then adding translations will help make Dashy available to non-native English speakers. This is a very quick and easy task, as all application text is located in [`locales/en.json`](https://github.com/Lissy93/dashy/blob/master/src/assets/locales/en.json), so adding a new language is as simple as copying this file and translating the values. You don't have to translate it all, as any missing attributes will just fallback to English. For a full tutorial, see the [Multi-Language Support Docs](https://github.com/Lissy93/dashy/blob/master/docs/multi-language-support.md). - -## Submit a PR -Contributing to the code or docs is super helpful. You can fix a bug, add a new feature or improve an existing one. If you've built your own custom widget, theme or view, consider sharing it in a PR. I've written [several guides](/docs/development-guides) to help you get started, and the steps for setting up the development environment are outlined in the [Development Docs](/docs/development). Feel free to ask if you have any questions. - -## 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`](/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. - -[![Raise a Bug](https://img.shields.io/badge/Raise_a-Bug-%23dc2d76?style=for-the-badge&logo=dependabot)](https://github.com/Lissy93/dashy/issues/new?assignees=lissy93&labels=%F0%9F%90%9B+Bug&template=bug.yml&title=%5BBUG%5D+%3Ctitle%3E) - -## Join the discussion -I've enabled the discussion feature on GitHub, here you can share tips and tricks, useful information, or your dashboard. You can also ask questions, and offer basic support to other users. - -[![Join the Discussion on GitHub](https://img.shields.io/badge/Join_the-Discussion-%23ffd000?style=for-the-badge&logo=livechat)](https://github.com/Lissy93/dashy/discussions) - -## Request a feature via BountySource -BountySource is a platform for sponsoring the development of certain features on open source projects. If there is a feature you'd like implemented into Dashy, but either isn't high enough priority or is deemed to be more work than it's worth, then you can instead contribute a bounty towards it's development. You won't pay a penny until your proposal is fully built, and you are satisfied with the result. This helps support the developers, and makes Dashy better for everyone. - -[![Request a Feature on BountySource](https://img.shields.io/badge/BountySource-Dashy-%23F67909?style=for-the-badge&logo=openbugbounty)](https://www.bountysource.com/teams/dashy) - -## Spread the word -Dashy is still a relatively young project, and as such not many people know of it. It would be great to see more users, and so it would be awesome if you could consider sharing with your friends or on social platforms. - -[![Share Dashy on Mastodon](https://img.shields.io/badge/Share-Mastodon-%232b90d9?style=flat-square&logo=mastodon)](https://mastodon.social/?text=Check%20out%20Dashy%2C%20the%20privacy-friendly%2C%20self-hosted%20startpage%20for%20organizing%20your%20life%3A%20https%3A%2F%2Fgithub.com%2FLissy93%2Fdashy%20-%20By%20%40lissy93%40mastodon.social) -[![Share Dashy on Reddit](https://img.shields.io/badge/Share-Reddit-%23FF5700?style=flat-square&logo=reddit)](http://www.reddit.com/submit?url=https://github.com/Lissy93/dashy&title=Dashy%20-%20The%20self-hosted%20dashboard%20for%20your%20homelab%20%F0%9F%9A%80) -[![Share Dashy on Twitter](https://img.shields.io/badge/Share-Twitter-%231DA1F2?style=flat-square&logo=twitter)](https://twitter.com/intent/tweet?url=https://github.com/lissy93/dashy&text=Check%20out%20Dashy%20by%20@Lissy_Sykes,%20the%20self-hosted%20dashboard%20for%20your%20homelab%20%F0%9F%9A%80) -[![Share Dashy on Facebook](https://img.shields.io/badge/Share-Facebook-%234267B2?style=flat-square&logo=facebook)](https://www.facebook.com/sharer/sharer.php?u=https://github.com/lissy93/dashy) -[![Share Dashy on LinkedIn](https://img.shields.io/badge/Share-LinkedIn-%230077b5?style=flat-square&logo=linkedin)](https://www.linkedin.com/shareArticle?mini=true&url=https://github.com/lissy93/dashy) -[![Share Dashy on Pinterest](https://img.shields.io/badge/Share-Pinterest-%23E60023?style=flat-square&logo=pinterest)](https://pinterest.com/pin/create/button/?url=https://github.com/lissy93/dashy&media=https://raw.githubusercontent.com/Lissy93/dashy/master/docs/showcase/1-home-lab-material.png&description=Check%20out%20Dashy,%20the%20self-hosted%20dashboard%20for%20your%20homelab%20%F0%9F%9A%80) -[![Share Dashy on VK](https://img.shields.io/badge/Share-VK-%234C75A3?style=flat-square&logo=vk)](https://vk.com/share.php?url=https%3A%2F%2Fgithub.com%2Flissy93%2Fdashy%2F&title=Check%20out%20Dashy%20-%20The%20Self-Hosted%20Dashboard%20for%20your%20Homelab%20%F0%9F%9A%80) -[![Share Dashy via Viber](https://img.shields.io/badge/Share-Viber-%238176d6?style=flat-square&logo=viber)](viber://forward?text=https%3A%2F%2Fgithub.com%2Flissy93%2Fdashy%0ACheck%20out%20Dashy%2C%20the%20self-hosted%20dashboard%20for%20your%20homelab%20%F0%9F%9A%80) -[![Share Dashy via Telegram](https://img.shields.io/badge/Share-Telegram-%230088cc?style=flat-square&logo=telegram)](https://t.me/share/url?url=https%3A%2F%2Fgithub.com%2Flissy93%2Fdashy&text=Check%20out%20Dashy%2C%20the%20self-hosted%20dashboard%20for%20your%20homelab%20%F0%9F%9A%80) -[![Share Dashy via Email](https://img.shields.io/badge/Share-Email-%238A90C7?style=flat-square&logo=protonmail)](mailto:info@example.com?&subject=Check%20out%20Dashy%20-%20The%20self-hosted%20dashboard%20for%20your%20homelab%20%F0%9F%9A%80&cc=&bcc=&body=https://github.com/lissy93/dashy) - -## Star, Upvote or Leave a Review -Dashy is on the following platforms, and if you could spare a few seconds to give it an upvote or review, this will also help new users discover Dashy - -[![ProductHunt](https://img.shields.io/badge/Review-ProductHunt-%23b74424?style=flat-square&logo=producthunt)](https://www.producthunt.com/posts/dashy) -[![AlternativeTo](https://img.shields.io/badge/Review-AlternativeTo-%235581a6?style=flat-square&logo=abletonlive)](https://alternativeto.net/software/dashy/about/) -[![Slant](https://img.shields.io/badge/Review-Slant-%2346a1df?style=flat-square&logo=capacitor)](https://www.slant.co/improve/topics/27783/viewpoints/1/~self-hosted-homelab-startpage~dashy) -[![Star on GitHub](https://img.shields.io/github/stars/Lissy93/Dashy?color=ba96d6&label=Star%20-%20GitHub&logo=github&style=flat-square)](https://github.com/Lissy93/dashy/stargazers) -[![Star on DockerHub](https://img.shields.io/docker/stars/lissy93/dashy?color=4cb6e0&label=Star%20-%20Docker&logo=docker&style=flat-square)](https://hub.docker.com/r/lissy93/dashy) - -## Follow for More -If you've enjoyed Dashy, you can follow the me to get updates about other projects that I am working on. - -[![Alicia Sykes on Twitter](https://img.shields.io/twitter/follow/Lissy_Sykes?style=social&logo=twitter)](https://twitter.com/Lissy_Sykes) -[![Alicia Sykes on GitHub](https://img.shields.io/github/followers/lissy93?label=Lissy93&style=social)](https://github.com/Lissy93) -[![Alicia Sykes on Mastodon](https://img.shields.io/mastodon/follow/1032965?domain=https%3A%2F%2Fmastodon.social)](https://mastodon.social/web/accounts/1032965) -[![Alicia Sykes on Keybase](https://img.shields.io/badge/aliciasykes--lightgrey?style=social&logo=Keybase)](https://keybase.io/aliciasykes) -[![Alicia Sykes's Website](https://img.shields.io/badge/aliciasykes.com--lightgrey?style=social&logo=Tencent%20QQ)](https://aliciasykes.com) -[![Alicia Sykes's Blog](https://img.shields.io/badge/Blog--lightgrey?style=social&logo=micro.blog)](https://notes.aliciasykes.com/) -[![Alicia Sykes's PGP](https://img.shields.io/badge/PGP--lightgrey?style=social&logo=Let%E2%80%99s%20Encrypt)](https://keybase.io/aliciasykes/pgp_keys.asc) - -If you like, you could also consider [subscribing to my mailing list](https://notes.aliciasykes.com/subscribe) for occasional blog post updates. - ---- - -### Contributors - -For a full list of Dashy's contributors, see the [Credits Page](/docs/credits) - -[![Auto-generated contributors](https://raw.githubusercontent.com/Lissy93/dashy/master/docs/assets/CONTRIBUTORS.svg)](/docs/credits) - -### Star-Gazers Over Time - -[![Stargazers](https://starchart.cc/Lissy93/dashy.svg)](https://seladb.github.io/StarTrack-js/#/preload?r=Lissy93,dashy) - +# Contributing + +First off, thank you for considering contributing towards Dashy! πŸ™Œ +There are several ways that you can help out, and any contributions, however small will always be very much appreciated. +You will be appropriately credited in the readme - huge thank you to [everyone who has helped](/docs/credits) so far πŸ’ž + +## Take a 2-minute survey +Help improve Dashy by taking a very short, 6-question survey. This will give me a better understanding of what is important to you, so that I can make Dashy better in the future :) + +[![Take the Survey](https://img.shields.io/badge/Take_the-Survey-%231a86fd?style=for-the-badge&logo=buddy)](https://survey.typeform.com/to/gl0L68ou) + +## Share your dashboard +Dashy now has a [Showcase](https://github.com/Lissy93/dashy/blob/master/docs/showcase.md#dashy-showcase-) where you can show off a screenshot of your dashboard, and get inspiration from other users (and I really love seeing how people are using Dashy). To [submit your dashboard](https://github.com/Lissy93/dashy/blob/master/docs/showcase.md#submitting-your-dashboard), either open a PR or raise an issue. + +[![Add your Dashboard to the Showcase](https://img.shields.io/badge/Add_your_Dashboard-Showcase-%238616ee?style=for-the-badge&logo=feathub&logoColor=8616ee)](https://github.com/Lissy93/dashy/issues/new?assignees=&labels=%F0%9F%92%AF+Showcase&template=showcase-addition.yml&title=%5BSHOWCASE%5D+%3Ctitle%3E) + +## Make a small donation + +Donations help to cover server costs, development time and caffeine ;) +Don't feel any pressure to donate anything, as Dashy and my other projects will always be 100% free, for everyone, for ever. + +[![Sponsor Lissy93 on GitHub](https://img.shields.io/badge/Sponsor_on_GitHub-Lissy93-%23ff4dda?style=for-the-badge&logo=githubsponsors&logoColor=ff4dda)](https://github.com/sponsors/Lissy93) + +Sponsoring will give you several perks - for $1 / Β£0.75 per month, you'll get a sponsor badge on your profile, be credited on the Dashy's readme, with a link to your website/ profile/ socials, get priority support, have your feature ideas implemented, plus lots more. For more info, see [@Lissy93's Sponsor Page](https://github.com/sponsors/Lissy93). + + +## Enable Anonymous Bug Reports + +Bug reports helps me to discover bugs I was unaware of, and then fix them, in order to make Dashy more reliable long term. This is a simple, yet really helpful step you can take to help improve Dashy. [Sentry](https://github.com/getsentry/sentry) is an open source error tracking and performance monitoring tool, which enables the identification any errors which occur in the production app (only if you enable it). + +To enable error reporting: +```yaml +appConfig: + enableErrorReporting: true +``` + +All reporting is **disabled** by default, and no data will ever be sent to any external endpoint without your explicit consent. All statistics are anonomized and stored securely. For more about privacy and security, see the [Sentry Security Docs](https://sentry.io/security/). + +## Add Translations +If you speak another language, then adding translations will help make Dashy available to non-native English speakers. This is a very quick and easy task, as all application text is located in [`locales/en.json`](https://github.com/Lissy93/dashy/blob/master/src/assets/locales/en.json), so adding a new language is as simple as copying this file and translating the values. You don't have to translate it all, as any missing attributes will just fallback to English. For a full tutorial, see the [Multi-Language Support Docs](https://github.com/Lissy93/dashy/blob/master/docs/multi-language-support.md). + +## Submit a PR +Contributing to the code or docs is super helpful. You can fix a bug, add a new feature or improve an existing one. If you've built your own custom widget, theme or view, consider sharing it in a PR. I've written [several guides](/docs/development-guides) to help you get started, and the steps for setting up the development environment are outlined in the [Development Docs](/docs/developing). Feel free to ask if you have any questions. + +## 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`](/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. + +[![Raise a Bug](https://img.shields.io/badge/Raise_a-Bug-%23dc2d76?style=for-the-badge&logo=dependabot)](https://github.com/Lissy93/dashy/issues/new?assignees=lissy93&labels=%F0%9F%90%9B+Bug&template=bug.yml&title=%5BBUG%5D+%3Ctitle%3E) + +## Join the discussion +I've enabled the discussion feature on GitHub, here you can share tips and tricks, useful information, or your dashboard. You can also ask questions, and offer basic support to other users. + +[![Join the Discussion on GitHub](https://img.shields.io/badge/Join_the-Discussion-%23ffd000?style=for-the-badge&logo=livechat)](https://github.com/Lissy93/dashy/discussions) + +## Request a feature via BountySource +BountySource is a platform for sponsoring the development of certain features on open source projects. If there is a feature you'd like implemented into Dashy, but either isn't high enough priority or is deemed to be more work than it's worth, then you can instead contribute a bounty towards it's development. You won't pay a penny until your proposal is fully built, and you are satisfied with the result. This helps support the developers, and makes Dashy better for everyone. + +[![Request a Feature on BountySource](https://img.shields.io/badge/BountySource-Dashy-%23F67909?style=for-the-badge&logo=openbugbounty)](https://www.bountysource.com/teams/dashy) + +## Spread the word +Dashy is still a relatively young project, and as such not many people know of it. It would be great to see more users, and so it would be awesome if you could consider sharing with your friends or on social platforms. + +[![Share Dashy on Mastodon](https://img.shields.io/badge/Share-Mastodon-%232b90d9?style=flat-square&logo=mastodon)](https://mastodon.social/?text=Check%20out%20Dashy%2C%20the%20privacy-friendly%2C%20self-hosted%20startpage%20for%20organizing%20your%20life%3A%20https%3A%2F%2Fgithub.com%2FLissy93%2Fdashy%20-%20By%20%40lissy93%40mastodon.social) +[![Share Dashy on Reddit](https://img.shields.io/badge/Share-Reddit-%23FF5700?style=flat-square&logo=reddit)](http://www.reddit.com/submit?url=https://github.com/Lissy93/dashy&title=Dashy%20-%20The%20self-hosted%20dashboard%20for%20your%20homelab%20%F0%9F%9A%80) +[![Share Dashy on Twitter](https://img.shields.io/badge/Share-Twitter-%231DA1F2?style=flat-square&logo=twitter)](https://twitter.com/intent/tweet?url=https://github.com/lissy93/dashy&text=Check%20out%20Dashy%20by%20@Lissy_Sykes,%20the%20self-hosted%20dashboard%20for%20your%20homelab%20%F0%9F%9A%80) +[![Share Dashy on Facebook](https://img.shields.io/badge/Share-Facebook-%234267B2?style=flat-square&logo=facebook)](https://www.facebook.com/sharer/sharer.php?u=https://github.com/lissy93/dashy) +[![Share Dashy on LinkedIn](https://img.shields.io/badge/Share-LinkedIn-%230077b5?style=flat-square&logo=linkedin)](https://www.linkedin.com/shareArticle?mini=true&url=https://github.com/lissy93/dashy) +[![Share Dashy on Pinterest](https://img.shields.io/badge/Share-Pinterest-%23E60023?style=flat-square&logo=pinterest)](https://pinterest.com/pin/create/button/?url=https://github.com/lissy93/dashy&media=https://raw.githubusercontent.com/Lissy93/dashy/master/docs/showcase/1-home-lab-material.png&description=Check%20out%20Dashy,%20the%20self-hosted%20dashboard%20for%20your%20homelab%20%F0%9F%9A%80) +[![Share Dashy on VK](https://img.shields.io/badge/Share-VK-%234C75A3?style=flat-square&logo=vk)](https://vk.com/share.php?url=https%3A%2F%2Fgithub.com%2Flissy93%2Fdashy%2F&title=Check%20out%20Dashy%20-%20The%20Self-Hosted%20Dashboard%20for%20your%20Homelab%20%F0%9F%9A%80) +[![Share Dashy via Viber](https://img.shields.io/badge/Share-Viber-%238176d6?style=flat-square&logo=viber)](viber://forward?text=https%3A%2F%2Fgithub.com%2Flissy93%2Fdashy%0ACheck%20out%20Dashy%2C%20the%20self-hosted%20dashboard%20for%20your%20homelab%20%F0%9F%9A%80) +[![Share Dashy via Telegram](https://img.shields.io/badge/Share-Telegram-%230088cc?style=flat-square&logo=telegram)](https://t.me/share/url?url=https%3A%2F%2Fgithub.com%2Flissy93%2Fdashy&text=Check%20out%20Dashy%2C%20the%20self-hosted%20dashboard%20for%20your%20homelab%20%F0%9F%9A%80) +[![Share Dashy via Email](https://img.shields.io/badge/Share-Email-%238A90C7?style=flat-square&logo=protonmail)](mailto:info@example.com?&subject=Check%20out%20Dashy%20-%20The%20self-hosted%20dashboard%20for%20your%20homelab%20%F0%9F%9A%80&cc=&bcc=&body=https://github.com/lissy93/dashy) + +## Star, Upvote or Leave a Review +Dashy is on the following platforms, and if you could spare a few seconds to give it an upvote or review, this will also help new users discover Dashy + +[![ProductHunt](https://img.shields.io/badge/Review-ProductHunt-%23b74424?style=flat-square&logo=producthunt)](https://www.producthunt.com/posts/dashy) +[![AlternativeTo](https://img.shields.io/badge/Review-AlternativeTo-%235581a6?style=flat-square&logo=abletonlive)](https://alternativeto.net/software/dashy/about/) +[![Slant](https://img.shields.io/badge/Review-Slant-%2346a1df?style=flat-square&logo=capacitor)](https://www.slant.co/improve/topics/27783/viewpoints/1/~self-hosted-homelab-startpage~dashy) +[![Star on GitHub](https://img.shields.io/github/stars/Lissy93/Dashy?color=ba96d6&label=Star%20-%20GitHub&logo=github&style=flat-square)](https://github.com/Lissy93/dashy/stargazers) +[![Star on DockerHub](https://img.shields.io/docker/stars/lissy93/dashy?color=4cb6e0&label=Star%20-%20Docker&logo=docker&style=flat-square)](https://hub.docker.com/r/lissy93/dashy) + +## Follow for More +If you've enjoyed Dashy, you can follow the me to get updates about other projects that I am working on. + +[![Alicia Sykes on Twitter](https://img.shields.io/twitter/follow/Lissy_Sykes?style=social&logo=twitter)](https://twitter.com/Lissy_Sykes) +[![Alicia Sykes on GitHub](https://img.shields.io/github/followers/lissy93?label=Lissy93&style=social)](https://github.com/Lissy93) +[![Alicia Sykes on Mastodon](https://img.shields.io/mastodon/follow/1032965?domain=https%3A%2F%2Fmastodon.social)](https://mastodon.social/web/accounts/1032965) +[![Alicia Sykes on Keybase](https://img.shields.io/badge/aliciasykes--lightgrey?style=social&logo=Keybase)](https://keybase.io/aliciasykes) +[![Alicia Sykes's Website](https://img.shields.io/badge/aliciasykes.com--lightgrey?style=social&logo=Tencent%20QQ)](https://aliciasykes.com) +[![Alicia Sykes's Blog](https://img.shields.io/badge/Blog--lightgrey?style=social&logo=micro.blog)](https://notes.aliciasykes.com/) +[![Alicia Sykes's PGP](https://img.shields.io/badge/PGP--lightgrey?style=social&logo=Let%E2%80%99s%20Encrypt)](https://keybase.io/aliciasykes/pgp_keys.asc) + +If you like, you could also consider [subscribing to my mailing list](https://notes.aliciasykes.com/subscribe) for occasional blog post updates. + +--- + +### Contributors + +For a full list of Dashy's contributors, see the [Credits Page](/docs/credits) + +[![Auto-generated contributors](https://raw.githubusercontent.com/Lissy93/dashy/master/docs/assets/CONTRIBUTORS.svg)](/docs/credits) + +### Star-Gazers Over Time + +[![Stargazers](https://starchart.cc/Lissy93/dashy.svg)](https://seladb.github.io/StarTrack-js/#/preload?r=Lissy93,dashy) + diff --git a/docs/credits.md b/docs/credits.md index 286a3baa..1cad8e17 100644 --- a/docs/credits.md +++ b/docs/credits.md @@ -1,7 +1,6 @@ # Credits ### Sponsors - + + + + - + + + + + + - + + + + - + + + + - - + + - + + - - - -
@@ -11,6 +10,13 @@ Peng1can + + emlazzarin +
+ Eddy Lazzarin + + 		BOZG @@ -32,6 +38,14 @@ Vlad Timofeev + + kitl000 +
+ Kit L. + +
Byolock @@ -39,14 +53,27 @@ Byolock + + PAPAMICA +
+ Mickael Asseline + + 		hugalafutro
Hugalafutro -
+ + shadowking001 +
+ LawrenceP. + + 		KierenConnell @@ -55,10 +82,18 @@ - - gdepountis + + Antiz96
- Gdepountis + Robin Candau + +
+ + ced4568 +
+ Kyforker148 		@@ -122,14 +157,28 @@ Snyk Bot + + pinarruiz +
+ Alejandro Pinar Ruiz + +
kashif-se
Kashif Sohail -
+ + walkxcode +
+ Walkx + + 		evroon @@ -148,16 +197,17 @@ remygrandin
- remygrandin + Remygrandin 		- - walkxcode + + stanly0726
- Walkx + Stanly0726 -
onedr0p @@ -171,8 +221,7 @@
Alessandro Del Prete -
BOZG @@ -180,6 +229,13 @@ Stephen Rigney + + moemoeq +
+ CHAIYEON CHO + + 		daentech @@ -193,7 +249,8 @@
RΓΊben Silva -
Singebob @@ -214,14 +271,6 @@
Begin -
- - moemoeq -
- CHAIYEON CHO - 		@@ -237,6 +286,14 @@ DeepSource Bot + + emiran-orange +
+ Emiran-orange + +
FormatToday @@ -257,42 +314,20 @@
Ishan Jain -
+ + Hellhium +
+ Jemy SCHNEPP + + 		KierenConnell
Kieren Connell - 		- - rubjo -
- Rubjo - - 		- - turnrye -
- Ryan Turner - - 		- - royshreyaaa -
- Shreya Roy - - 		- - StevKast -
- Steven Kast -
diff --git a/docs/developing.md b/docs/developing.md index 056614aa..886d3c83 100644 --- a/docs/developing.md +++ b/docs/developing.md @@ -2,7 +2,7 @@ # 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.md) 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) diff --git a/docs/development-guides.md b/docs/development-guides.md index 268ddc73..40ab54ff 100644 --- a/docs/development-guides.md +++ b/docs/development-guides.md @@ -35,7 +35,7 @@ Then you can go ahead and write you're own custom CSS. Although all CSS is suppo For a full guide on styling, see [Theming Docs](./theming). -Note that if you're theme is just for yourself, and you're not submitting a PR, then you can instead just pass it under `appConfig.cssThemes` inside your config file. And then put your theme in your own stylesheet, and pass it into the Docker container - [see how](https://github.com/Lissy93/dashy/blob/master/docs/theming.md#adding-your-own-theme). +Note that if you're theme is just for yourself, and you're not submitting a PR, then you can instead just pass it under `appConfig.cssThemes` inside your config file. And then put your theme in your own stylesheet, and pass it into the Docker container - [see how](https://github.com/Lissy93/dashy/blob/master/docs/theming#adding-your-own-theme). ## Writing Translations @@ -97,7 +97,7 @@ If you are not comfortable with making pull requests, or do not want to modify t This section is for, adding a new setting to the config file. -All of the users config is specified in `./public/conf.yml` - see [Configuring Docs](./configuring.md) for info. +All of the users config is specified in `./public/conf.yml` - see [Configuring Docs](./configuring) for info. It's important to first ensure that there isn't a similar option already available, the new option is definitely necessary, and most importantly that it is fully backwards compatible. Next choose the appropriate section to place it under diff --git a/docs/icons.md b/docs/icons.md index ff98f799..1a620a51 100644 --- a/docs/icons.md +++ b/docs/icons.md @@ -103,7 +103,7 @@ For example, these will all render the same rocket (πŸš€) emoji: `icon: ':rocket ## Home-Lab Icons -The [dashboard-icons](https://github.com/WalkxCode/dashboard-icons) repo by [@WalkxCode](https://github.com/WalkxCode) provides a comprehensive collection of 360+ high-quality PNG icons for commonly self-hosted services. Dashy natively supports these icons, and you can use them just by specifying the icon name (without extension) preceded by `hl-`. See [here](https://github.com/WalkxCode/dashboard-icons/tree/master/png) for a full list of all available icons. Note that these are fetched and cached strait from GitHub, so if you require offline access, the [Local Icons](#local-icons) method may be a better option for you. +The [dashboard-icons](https://github.com/WalkxHub/dashboard-icons) repo by [@WalkxCode](https://github.com/WalkxCode) provides a comprehensive collection of 360+ high-quality PNG icons for commonly self-hosted services. Dashy natively supports these icons, and you can use them just by specifying the icon name (without extension) preceded by `hl-`. See [here](https://github.com/WalkxCode/dashboard-icons/tree/master/png) for a full list of all available icons. Note that these are fetched and cached strait from GitHub, so if you require offline access, the [Local Icons](#local-icons) method may be a better option for you. For example: ```yaml diff --git a/docs/management.md b/docs/management.md index 0d5f1365..f3b4b40b 100644 --- a/docs/management.md +++ b/docs/management.md @@ -196,7 +196,7 @@ I recommend combining this with [healthchecks](https://github.com/healthchecks/h ## SSL Certificates -Enabling HTTPS with an SSL certificate is recommended, especially if you hare hosting Dashy anywhere other than your home. This will ensure that all traffic is encrypted in transit. +Enabling HTTPS with an SSL certificate is recommended, especially if you are hosting Dashy anywhere other than your home. This will ensure that all traffic is encrypted in transit. ### Auto-SSL If you are using [NGINX Proxy Manager](https://nginxproxymanager.com/), then SSL is supported out of the box. Once you've added your proxy host and web address, then set the scheme to HTTPS, then under the SSL Tab select "Request a new SSL certificate" and follow the on-screen instructions. diff --git a/docs/pages-and-sections.md b/docs/pages-and-sections.md index f5faa746..f55c62f6 100644 --- a/docs/pages-and-sections.md +++ b/docs/pages-and-sections.md @@ -1,11 +1,10 @@ # Pages and Sections - ## Multi-Page Support You can have additional pages within your dashboard, with each having it's own config file. The config files for sub-pages can either be stored locally, or hosted separately. A link to each additional page will be displayed in the navigation bar. -Note that the only top-level fields supported by sub-pages are `pageInfo` and `sections`. The `appConfig` and `pages` will always be inherited from your main `conf.yml` file. Other than that, sub-pages behave exactly the same as your default view, and can contain sections, items, widgets and page info like nav links, title and logo. +You can edit additional pages using the interactive editor, exactly the same was as your primary page (so long as it's local). But please save changes to one page, before you start editing the next. ### Using Local Sub-Pages @@ -21,6 +20,8 @@ pages: path: 'work.yml' ``` +If you're sub-page is located within `/app/public`, then you only need to specify the filename, but if it's anywhere else, then the full path is required. + ### Using Remote Sub-Pages Config files don't need to be local, you can store them anywhere, and data will be imported as sub-pages on page load. @@ -39,7 +40,7 @@ pages: There are many options of how this can be used. You could store your config within a Git repository, in order to easily track and rollback changes. Or host your config on your NAS, to have it backed up with the rest of your files. Or use a hosted paste service, for example [snippet.host](https://snippet.host/), which supports never-expiring CORS-enabled pastes, which can also be edited later. -You will obviously not be able to write updates to remote configs through the UI editor, but you can still make and preview changes, then use the export menu to get a copy of the new config, and modify the original source manually. +You will obviously not be able to write updates to remote configs directly through the UI editor, but you can still make and preview changes, then use the export menu to get a copy of the new config, which can then be pasted to the remote source manually. The config file must, of course be accessible from within Dashy. If your config contains sensitive info (like API keys, credentials, secret URLs, etc), take care not to expose it to the internet. The following example shows creating a config, publishing it as a [Gist](https://gist.github.com/), copying the URL to the raw file, and using it within your dashboard. @@ -49,3 +50,49 @@ The following example shows creating a config, publishing it as a [Gist](https:/ src="https://i.ibb.co/55jm3LG/how-to-use-remote-config-sub-page.gif" />

+ +### Restrictions + +Only top-level fields supported by sub-pages are `pageInfo` and `sections`. The `appConfig` and `pages` will always be inherited from your main `conf.yml` file. Other than that, sub-pages behave exactly the same as your default view, and can contain sections, items, widgets and page info like nav links, title and logo. + +Note that since page paths are required by the router, they are set at build-time, not run-time, and so a rebuild (happens automatically) is required for changes to page paths to take effect (this only applies to changes to the `pages` array, rebuild isn't required for editing page content). + + +## Sub-Items + +A normal section will contain zero or more items, for example: + +```yaml +- name: Coding + icon: far fa-code + items: + - title: GitHub + url: https://github.com/ + - title: StackOverflow + url: http://stackoverflow.com/ +``` + +But items can also be grouped together, referred to as sub-items. This is useful for a group of less frequently used items, which you don't want to take up too much space, or for action buttons (_coming soon_). + +Item groups may also have an optional title. + +```yaml +- name: Coding + icon: far fa-code + items: + - title: Normal Item 1 + - title: Normal Item 2 + - subItems: + - title: JavaScript + url: https://developer.mozilla.org + icon: si-javascript + - title: TypeScript + url: https://www.typescriptlang.org/docs + icon: si-typescript + - title: Svelt + url: https://svelte.dev/docs + icon: si-svelte + - title: Go + url: https://go.dev/doc + icon: si-go +``` diff --git a/docs/privacy.md b/docs/privacy.md index db91d8cc..26390acb 100644 --- a/docs/privacy.md +++ b/docs/privacy.md @@ -111,6 +111,8 @@ Dashy supports [Widgets](/docs/widgets) for displaying dynamic content. Below is - [IP-API Privacy Policy](https://ip-api.com/docs/legal) - **[IP Blacklist](/docs/widgets#ip-blacklist)**: `https://api.blacklistchecker.com` - [Blacklist Checker Privacy Policy](https://blacklistchecker.com/privacy) +- **[Domain Monitor](/docs/widgets#domain-monitor)**: `http://api.whoapi.com` + - [WhoAPI Privacy Policy](https://whoapi.com/privacy-policy/) - **[Crypto Watch List](/docs/widgets#crypto-watch-list)** and **[Token Price History](/docs/widgets#crypto-token-price-history)**: `https://api.coingecko.com` - [CoinGecko Privacy Policy](https://www.coingecko.com/en/privacy) - **[Wallet Balance](/docs/widgets#wallet-balance)**: `https://api.blockcypher.com/` @@ -207,7 +209,7 @@ Note that packages listed under `devDependencies` section are only used for buil ## Securing your Environment Running your self-hosted applications in individual, containerized environments (such as containers or VMs) helps keep them isolated, and prevent an exploit in one service effecting another. -If you're running Dashy in a container, see [Management Docs --> Container Security](https://github.com/Lissy93/dashy/blob/master/docs/management#container-security) for step-by-step security guide. +If you're running Dashy in a container, see [Management Docs --> Container Security](https://github.com/Lissy93/dashy/blob/master/docs/management.md#container-security) for step-by-step security guide. There is very little complexity involved with Dashy, and therefore the attack surface is reasonably small, but it is still important to follow best practices and employ monitoring for all your self-hosted apps. A couple of things that you should look at include: - Use SSL for securing traffic in transit diff --git a/docs/release-workflow.md b/docs/release-workflow.md index 7e87792f..99401c5e 100644 --- a/docs/release-workflow.md +++ b/docs/release-workflow.md @@ -12,7 +12,7 @@ We're using [Semantic Versioning](https://semver.org/), to indicate major, minor 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. +For a full breakdown of each change, you can view the [Changelog](https://github.com/Lissy93/dashy/blob/master/.github/CHANGELOG.md). 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. --- @@ -155,4 +155,4 @@ Action | Description **Generate Credits**
[![generate-credits.yml](https://github.com/Lissy93/dashy/actions/workflows/generate-credits.yml/badge.svg)](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**
[![wiki-sync.yml](https://github.com/Lissy93/dashy/actions/workflows/wiki-sync.yml/badge.svg)](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 ---- +--- \ No newline at end of file diff --git a/docs/showcase.md b/docs/showcase.md index 4021f768..a902a28c 100644 --- a/docs/showcase.md +++ b/docs/showcase.md @@ -1,4 +1,4 @@ -# Showcase 🌟 +# *Dashy Showcase* 🌟 | πŸ’— Got a sweet dashboard? Submit it to the showcase! πŸ‘‰ [See How](#submitting-your-dashboard) | |-| @@ -10,19 +10,74 @@ --- ### Ratty222 -> By [@ratty222](https://github.com/ratty222) [#384](https://github.com/Lissy93/dashy/discussions/384) +> By [@ratty222](https://github.com/ratty222) Re: [#384](https://github.com/Lissy93/dashy/discussions/384) ![screenshot-ratty222-dashy](https://user-images.githubusercontent.com/1862727/147582551-4c655d37-8bcc-4f95-ab41-164a9d0d6a07.png) --- ### Hugalafutro Dashy -> By [@hugalafutro](https://github.com/hugalafutro) [#505](https://github.com/Lissy93/dashy/discussions/505) +> By [@hugalafutro](https://github.com/hugalafutro) Re: [#505](https://github.com/Lissy93/dashy/discussions/505) [![hugalafutro-dashy-screenshot](https://i.ibb.co/PDpLDKS/hugalafutro-dashy.gif)](https://i.ibb.co/PDpLDKS/hugalafutro-dashy.gif) --- +### NAS Home Dashboard +> By [@cerealconyogurt](https://github.com/cerealconyogurt) Re: [#74](https://github.com/Lissy93/dashy/issues/74) + +![screenshot-networking-services](https://raw.githubusercontent.com/Lissy93/dashy/master/docs/showcase/6-nas-home-dashboard.png) + +--- + +### Brewhack + +> By [@brpeterso](https://github.com/brpeterso) Re: [#680](https://github.com/Lissy93/dashy/issues/680) + +![screenshot-brewhack-dashboard](https://i.ibb.co/cNjzPT4/brewhack.png) + +--- + +### The Private Dashboard + +> By [@DylanBeMe](https://github.com/DylanBeMe) Re: [#419](https://github.com/Lissy93/dashy/issues/419) + +![screenshot-private-dashboard](https://i.ibb.co/hKS483T/private-dashboard-Dylan-Be-Me.png) + +--- + +### Homelab & VPS dashboard +> By [@shadowking001](https://github.com/shadowking001) Re: [#86](https://github.com/Lissy93/dashy/issues/86) + +![screenshot-shadowking001-dashy](https://raw.githubusercontent.com/Lissy93/dashy/master/docs/showcase/8-shadowking001s-dashy.png) + +--- + +### Raspberry PI Docker Dashboard + +> By [@henkiewie](https://github.com/henkiewie) Re: [#622](https://github.com/Lissy93/dashy/issues/622) + +> I use this dashboard every day. It now even includes a player for a radio stream which I configured with Logitech media server and icecast. I made an smaller version of the grafana dashboard to fit an iframe in kiosk mode, so it monitors the most important values of my RPI. The PI is in Argon m2 case and used as a NAS. The dashboard is a copy of the adventure theme with some changes saved in `/app/src/styles/user-defined-themes.scss` + +![screenshot-henkiewie-dashy](https://i.ibb.co/jGzPm6b/henkiewie-dashy-showcase.png) + +--- + +### First Week of Self-Hosting +> By [u//RickyCZ](https://www.reddit.com/user/RickyCZ) via [Reddit](https://www.reddit.com/r/selfhosted/comments/pose15/just_got_started_a_week_ago_selfhosting_is_very/) + +![screenshot-week-of-self-hosting](https://raw.githubusercontent.com/Lissy93/dashy/master/docs/showcase/11-ricky-cz.png) + +--- + +### EVO Dashboard + +> By [@EVOTk](https://github.com/EVOTk) Re: [#316](https://github.com/Lissy93/dashy/pull/316) + +![screenshot-evo-dashboard](https://raw.githubusercontent.com/Lissy93/dashy/master/docs/showcase/12-evo-dashboard.png) + +--- + ### Networking Services > By [@Lissy93](https://github.com/lissy93) @@ -30,36 +85,6 @@ --- -### Homelab & VPS dashboard -> By [@shadowking001](https://github.com/shadowking001) - -![screenshot-shadowking001-dashy](https://raw.githubusercontent.com/Lissy93/dashy/master/docs/showcase/8-shadowking001s-dashy.png) - ---- - -### EVO Dashboard - -> By [@EVOTk](https://github.com/EVOTk) - -![screenshot-evo-dashboard](https://raw.githubusercontent.com/Lissy93/dashy/master/docs/showcase/12-evo-dashboard.png) - ---- - -### The Private Dashboard - -> By [@DylanBeMe](https://github.com/DylanBeMe) [#419](https://github.com/Lissy93/dashy/issues/419) - -![screenshot-evo-dashboard](https://i.ibb.co/hKS483T/private-dashboard-Dylan-Be-Me.png) - ---- - -### NAS Home Dashboard -> By [@cerealconyogurt](https://github.com/cerealconyogurt) - -![screenshot-networking-services](https://raw.githubusercontent.com/Lissy93/dashy/master/docs/showcase/6-nas-home-dashboard.png) - ---- - ### Dashy Live > By [@Lissy93](https://github.com/lissy93) @@ -108,16 +133,9 @@ --- -### First Week of Self-Hosting -> By [u//RickyCZ](https://www.reddit.com/user/RickyCZ) - -![screenshot-week-of-self-hosting](https://raw.githubusercontent.com/Lissy93/dashy/master/docs/showcase/11-ricky-cz.png) - ---- - ### HomeLAb 3.0 -> By [@skoogee](https://github.com/skoogee) (http://zhrn.cc) +> By [@skoogee](https://github.com/skoogee) (http://zhrn.cc) [#279](https://github.com/Lissy93/dashy/issues/279) > Dashy, is the most complete dashboard I ever tried, has all the features, and it sets itself apart from the rest. It is my default homepage now. I am thankful to the developer @Lissy93 for sharing such a wonderful creation. @@ -126,19 +144,12 @@ --- ### Ground Control -> By [@dtctek](https://github.com/dtctek) +> By [@dtctek](https://github.com/dtctek) Re: [#83](https://github.com/Lissy93/dashy/issues/83) ![screenshot-ground-control](https://user-images.githubusercontent.com/1862727/149821995-e9b41dab-186c-42e6-b5b3-e233259b241d.png) --- -### Morning Dashboard -> Displayed on my smart screen between 05:00 - 08:00, and includes all the info that I usually check before leaving for work - -![screenshot-morning-dash](https://i.ibb.co/4Wx8zb7/morning-dashboard.png) - ---- - ### Croco_Grievous > By [u/Croco_Grievous](https://www.reddit.com/user/Croco_Grievous/) via [reddit](https://www.reddit.com/r/selfhosted/comments/t4xk3z/everything_started_with_pihole_on_a_raspberry_pi/) @@ -161,12 +172,28 @@ --- +### Morning Dashboard +> Displayed on my smart screen between 05:00 - 08:00, and includes all the info that I usually check before leaving for work + +![screenshot-morning-dash](https://i.ibb.co/4Wx8zb7/morning-dashboard.png) + +--- + ### Yet Another Homelab ![screenshot-yet-another-homelab](https://raw.githubusercontent.com/Lissy93/dashy/master/docs/showcase/9-home-lab-oblivion.png) --- +### The Dragons Lair +> By [dr460nf1r3](https://github.com/dr460nf1r3) via [#684](https://github.com/Lissy93/dashy/issues/684) + +> My new startpage featuring the stuff I use most. And of course dragons! + +![screenshot-dragons-lair](https://raw.githubusercontent.com/Lissy93/dashy/master/docs/showcase/13-dragons-lair.png) + +--- + ## Submitting your Dashboard #### How to Submit diff --git a/docs/showcase/13-dragons-lair.png b/docs/showcase/13-dragons-lair.png new file mode 100644 index 00000000..1c0867f7 Binary files /dev/null and b/docs/showcase/13-dragons-lair.png differ diff --git a/docs/theming.md b/docs/theming.md index 84dde582..e6bbae60 100644 --- a/docs/theming.md +++ b/docs/theming.md @@ -69,6 +69,16 @@ Custom CSS can be developed, tested and applied directly through the UI. Althoug This can be done from the Config menu (spanner icon in the top-right), under the Custom Styles tab. This is then associated with `appConfig.customCss` in local storage. Styles can also be directly applied to this attribute in the config file, but this may get messy very quickly if you have a lot of CSS. +### Page-Specific Styles + +If you've got multiple pages within your dashboard, you can choose to target certain styles to specific pages. The top-most element within `` will have a class name specific to the current sub-page. This is usually the page's name, all lowercase, with dashes instead of spaces, but you can easily check this yourself within the dev tools. + +For example, if the pages name was "CFT Toolbox", and you wanted to target `.item`s, you would do: + +```css +.cft-toolbox .item { border: 4px solid yellow; } +``` + ### Loading External Stylesheets The URI of a stylesheet, either local or hosted on a remote CDN can be passed into the config file. The attribute `appConfig.externalStyleSheet` accepts either a string, or an array of strings. You can also pass custom font stylesheets here, they must be in a CSS format (for example, `https://fonts.googleapis.com/css2?family=Cutive+Mono`). diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index ad98f01c..4b5c2a69 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -7,8 +7,11 @@ ### Contents - [Refused to Connect in Web Content View](#refused-to-connect-in-modal-or-workspace-view) - [404 On Static Hosting](#404-on-static-hosting) +- [404 from Mobile Home Screen](#404-after-launch-from-mobile-home-screen) - [Yarn Build or Run Error](#yarn-error) - [Remote Config Not Loading](#remote-config-not-loading) +- [Heap limit Allocation failed](ineffective-mark-compacts-near-heap-limit-allocation-failed) +- [Command failed with signal "SIGKILL"](#command-failed-with-signal-sigkill) - [Auth Validation Error: "should be object"](#auth-validation-error-should-be-object) - [App Not Starting After Update to 2.0.4](#app-not-starting-after-update-to-204) - [Keycloak Redirect Error](#keycloak-redirect-error) @@ -26,11 +29,15 @@ - [Status Checks Failing](#status-checks-failing) - [Diagnosing Widget Errors](#widget-errors) - [Fixing Widget CORS Errors](#widget-cors-errors) -- [Keycloak Redirect Error](#keycloak-redirect-error) +- [Weather Forecast Widget 401](#weather-forecast-widget-401) +- [Font Awesome Icons not Displaying](#font-awesome-icons-not-displaying) +- [Copy to Clipboard not Working](#copy-to-clipboard-not-working) - [How-To Open Browser Console](#how-to-open-browser-console) - [Git Contributions not Displaying](#git-contributions-not-displaying) + --- + ## `Refused to Connect` in Modal or Workspace View This is not an issue with Dashy, but instead caused by the target app preventing direct access through embedded elements. @@ -85,6 +92,15 @@ If this works, but you wish to continue using HTML5 history mode, then a bit of --- +## 404 after Launch from Mobile Home Screen + +Similar to the above issue, if you get a 404 after using iOS's β€œadd to Home Screen” feature, then this is caused by Vue router. +It can be fixed by setting `appConfig.routingMode` to `hash` + +See also: [#628](https://github.com/Lissy93/dashy/issues/628) + +--- + ## Yarn Error For more info, see [Issue #1](https://github.com/Lissy93/dashy/issues/1) @@ -118,6 +134,35 @@ If it is a remote service, that you do not have admin access to, then another op --- +## Ineffective mark-compacts near heap limit Allocation failed + +If you see an error message, similar to: + +``` +<--- Last few GCs ---> + +[61:0x74533040] 229060 ms: Mark-sweep (reduce) 127.1 (236.9) -> 127.1 (137.4) MB, 5560.7 / 0.3 ms (average mu = 0.286, current mu = 0.011) allocation failure scavenge might not succeed + +<--- JS stacktrace ---> + +FATAL ERROR: Reached heap limit Allocation failed - JavaScript heap out of memory +``` + + +This is likely caused by insufficient memory allocation to the container. When the container first starts up, or has to rebuild, the memory usage spikes, and if there isn't enough memory, it may terminate. This can be specified with, for example: `--memory=1024m`. For more info, see [Docker: Runtime options with Memory, CPUs, and GPUs](https://docs.docker.com/config/containers/resource_constraints/). + +See also: [#380](https://github.com/Lissy93/dashy/issues/380), [#350](https://github.com/Lissy93/dashy/issues/350), [#297](https://github.com/Lissy93/dashy/issues/297), [#349](https://github.com/Lissy93/dashy/issues/349), [#510](https://github.com/Lissy93/dashy/issues/510) and [#511](https://github.com/Lissy93/dashy/issues/511) + +--- + +## Command failed with signal "SIGKILL" + +In Docker, this can be caused by not enough memory. When the container first starts up, or has to rebuild, the memory usage spikes, and so a larger allocation may be required. This can be specified with, for example: `--memory=1024m`. For more info, see [Docker: Runtime options with Memory, CPUs, and GPUs](https://docs.docker.com/config/containers/resource_constraints/) + +See also [#624](https://github.com/Lissy93/dashy/issues/624) + +--- + ## Auth Validation Error: "should be object" In V 1.6.5 an update was made that in the future will become a breaking change. You will need to update you config to reflect this before V 2.0.0 is released. In the meantime, your previous config will continue to function normally, but you will see a validation warning. The change means that the structure of the `appConfig.auth` object is now an object, which has a `users` property. @@ -171,6 +216,13 @@ You should also ensure that Keycloak is correctly configured, with a user, realm For more details on how to set headers, see the [Example Headers](/docs/management#setting-headers) in the management docs, or reference the documentation for your proxy. +If you're running in Kubernetes, you will need to enable CORS ingress rules, see [docs](https://kubernetes.github.io/ingress-nginx/user-guide/nginx-configuration/annotations/#enable-cors), e.g: + +``` +nginx.ingress.kubernetes.io/cors-allow-origin: "https://dashy.example.com" +nginx.ingress.kubernetes.io/enable-cors: "true" +``` + See also: #479, #409, #507, #491, #341, #520 --- @@ -349,7 +401,7 @@ For more info on how to set headers, see: [Setting Headers](/docs/management#set #### Option 3 - Proxying Request -You can route requests through Dashy's built-in CORS proxy. Instructions and more details can be found [here](/docs/widgets.md#proxying-requests). If you don't have control over the target origin, and you are running Dashy either through Docker, with the Node server or on Netlify, then this solution will work for you. +You can route requests through Dashy's built-in CORS proxy. Instructions and more details can be found [here](/docs/widgets#proxying-requests). If you don't have control over the target origin, and you are running Dashy either through Docker, with the Node server or on Netlify, then this solution will work for you. Just add the `useProxy: true` option to the failing widget. @@ -359,22 +411,40 @@ For testing purposes, you can use an addon, which will disable the CORS checks. --- -## Keycloak Redirect Error +## Weather Forecast Widget 401 -Firstly, ensure that in your Keycloak instance you have populated the Valid Redirect URIs field ([screenshot](https://user-images.githubusercontent.com/1862727/148599768-db4ee4f8-72c5-402d-8f00-051d999e6267.png)) with the URL to your Dashy instance. +[Weather widget](/docs/widgets#weather-forecast) is working fine, but you are getting a `401` for the [Weather Forecast widget](/docs/widgets#weather-forecast), then this is most likely an OWM API key issue. -You may need to specify CORS headers on your Keycloak instance, to allow requests coming from Dashy, e.g: +The forecasting API requires an upgraded plan. ULPT: You can get a free, premium API key by filling in [this form](https://home.openweathermap.org/students). It's a student plan, but there's no verification to check that you are still a student. -``` -Access-Control-Allow-Origin: https://dashy.example.com -``` +A future update will be pushed out, to use a free weather forecasting API. -If you're running in Kubernetes, you will need to enable CORS ingress rules, see [docs](https://kubernetes.github.io/ingress-nginx/user-guide/nginx-configuration/annotations/#enable-cors), e.g: +--- -``` -nginx.ingress.kubernetes.io/cors-allow-origin: "https://dashy.example.com" -nginx.ingress.kubernetes.io/enable-cors: "true" -``` +## Font Awesome Icons not Displaying + +Usually, Font Awesome will be automatically enabled if one or more of your icons are using Font-Awesome. If this is not happening, then you can always manually enable (or disable) Font Awesome by setting: [`appConfig`](/docs/configuring#appconfig-optional).`enableFontAwesome` to `true`. + +If you are trying to use a premium icon, then you must have a [Pro License](https://fontawesome.com/plans). You'll then need to specify your Pro plan API key under `appConfig.fontAwesomeKey`. You can find this key, by logging into your FA account, navigate to Account β†’ [Kits](https://fontawesome.com/kits) β†’ New Kit β†’ Copy Kit Code. The code is a 10-digit alpha-numeric code, and is also visible within the new kit's URL, for example: `81e48ce079`. + +Be sure that you're specifying the icon category and name correctly. You're icon should look be `[category] fa-[icon-name]`. The following categories are supported: `far` _(regular)_, `fas` _(solid)_, `fal`_(light)_, `fad` _(duo-tone)_ and `fab`_(brands)_. With the exception of brands, you'll usually want all your icons to be in from same category, so they look uniform. + +Ensure the icon you are trying to use, is available within [FontAwesome Version 5](https://fontawesome.com/v5/search). + +Examples: `fab fa-raspberry-pi`, `fas fa-database`, `fas fa-server`, `fas fa-ethernet` + +Finally, check the [browser console](#how-to-open-browser-console) for any error messages, and raise a ticket if the issue persists. + +--- + +## Copy to Clipboard not Working + +If the copy to clipboard feature (either under Config --> Export, or Item --> Copy URL) isn't functioning as expected, first check the browser console. If you see `TypeError: Cannot read properties of undefined (reading 'writeText')` then this feature is not supported by your browser. +The most common reason for this, is if you not running the app over HTTPS. Copying to the clipboard requires the app to be running in a secure origin / aka have valid HTTPS cert. You can read more about this [here](https://stackoverflow.com/a/71876238/979052). + +As a workaround, you could either: +- Highlight the text and copy / Ctrl + C +- Or setup SSL - [here's a guide](https://github.com/Lissy93/dashy/blob/master/docs/management.md#ssl-certificates) on doing so --- diff --git a/docs/widgets.md b/docs/widgets.md index efc2f99e..0c7860f4 100644 --- a/docs/widgets.md +++ b/docs/widgets.md @@ -2,10 +2,6 @@ Dashy has support for displaying dynamic content in the form of widgets. There are several built-in widgets available out-of-the-box as well as support for custom widgets to display stats from almost any service with an API. -> ℹ️ **Note**: Widgets are still in the Alpha-phase of development. -> If you find a bug, please raise it.
-> Adding / editing widgets through the UI isn't yet supported, you will need to do this in the YAML config file. - ##### Contents - **[General Widgets](#general-widgets)** - [Clock](#clock) @@ -15,6 +11,7 @@ Dashy has support for displaying dynamic content in the form of widgets. There a - [Image](#image) - [Public IP Address](#public-ip) - [IP Blacklist Checker](#ip-blacklist) + - [Domain Monitor](#domain-monitor) - [Crypto Watch List](#crypto-watch-list) - [Crypto Price History](#crypto-token-price-history) - [Crypto Wallet Balance](#wallet-balance) @@ -47,6 +44,10 @@ Dashy has support for displaying dynamic content in the form of widgets. There a - [Recent Traffic](#recent-traffic) - [Stat Ping Statuses](#stat-ping-statuses) - [Synology Download Station](#synology-download-station) + - [AdGuard Home Block Stats](#adguard-home-block-stats) + - [AdGuard Home Filters](#adguard-home-filters) + - [AdGuard Home DNS Info](#adguard-home-dns-info) + - [AdGuard Home Top Domains](#adguard-home-top-domains) - **[System Resource Monitoring](#system-resource-monitoring)** - [CPU Usage Current](#current-cpu-usage) - [CPU Usage Per Core](#cpu-usage-per-core) @@ -97,6 +98,7 @@ A simple, live-updating time and date widget with time-zone support. All fields **`format`** | `string` | _Optional_ | A country code for displaying the date and time in local format.
Specified as `[ISO-3166]-[ISO-639]`, for example: `en-AU`. See [here](https://www.fincher.org/Utilities/CountryLanguageList.shtml) for a full list of locales. Defaults to the browser / device's region **`customCityName`** | `string` | _Optional_ | By default the city from the time-zone is shown, but setting this value will override that text **`hideDate`** | `boolean` | _Optional_ | If set to `true`, the date and city will not be shown. Defaults to `false` +**`hideSeconds`** | `boolean` | _Optional_ | If set to `true`, seconds will not be shown. Defaults to `false` ##### Example @@ -319,6 +321,43 @@ Notice certain web pages aren't loading? This widget quickly shows which blackli --- +### Domain Monitor + +Keep an eye on the expiry dates of your domain names, using public whois records fetched from [whoapi.com](https://whoapi.com/). Click the domain name to view additional info, like registrar, name servers and date last updated. + +

+ +##### Options + +**Field** | **Type** | **Required** | **Description** +--- | --- | --- | --- +**`domain`** | `string` | Required | The domain to check +**`apiKey`** | `string` | Required | You can get your free API key from [my.whoapi.com](https://my.whoapi.com/user/signup) +**`showFullInfo`** | `boolean` | _Optional_ | If set to true, the toggle-full-info panel will be open by default + +##### Example + +```yaml + - type: domain-monitor + options: + domain: example.com + apiKey: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx + + - type: domain-monitor + options: + domain: example2.com + apiKey: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx +``` + +##### Info +- **CORS**: 🟒 Enabled +- **Auth**: πŸ”΄ Required +- **Price**: 🟠 Free Plan (10,000 requests) +- **Host**: Managed Instance Only +- **Privacy**: _See [WhoAPI Privacy Policy](https://whoapi.com/privacy-policy/)_ + +--- + ### Crypto Watch List Keep track of price changes of your favorite crypto assets. Data is fetched from [CoinGecko](https://www.coingecko.com/). All fields are optional. @@ -713,6 +752,7 @@ Show recent scores and upcoming matches from your favourite sports team. Data is **`pastOrFuture`** | `string` | __Optional__ | Set to `past` to show scores for recent games, or `future` to show upcoming games. Defaults to `past`. You can change this within the UI **`apiKey`** | `string` | __Optional__ | Optionally specify your API key, which you can sign up for at [TheSportsDB.com](https://www.thesportsdb.com/) **`limit`** | `number` | __Optional__ | To limit output to a certain number of matches, defaults to `15` +**`hideImage`** | `boolean` | __Optional__ | Set to `true` to not render the team / match banner image, defaults to `false` ##### Example @@ -1080,6 +1120,8 @@ _No config options._ ##### Info No external data requests made +Note that this widget is not available if you are running Dashy in a container or VM. Instead you can use the [System Monitoring](#system-resource-monitoring) widgets to display stats from the host system instead. + --- ### Cron Monitoring (Health Checks) @@ -1308,6 +1350,9 @@ Displays the current and recent uptime of your running services, via a self-host **Field** | **Type** | **Required** | **Description** --- | --- | --- | --- **`hostname`** | `string` | Required | The URL to your StatPing instance, without a trailing slash +**`groupId`** | `number` | Optional | If provided, only Services in the given group are displayed. Defaults to `0` in which case all services are displayed. +**`showChart`** | `boolean`| Optional | If provided and `false` then charts are not displayed. Defaults to `true`. +**`showInfo`** | `boolean`| Optional | If provided and `false` then information summaries are not displayed. Defaults to `true`. ##### Example @@ -1316,6 +1361,18 @@ Displays the current and recent uptime of your running services, via a self-host options: hostname: http://192.168.130.1:8080 ``` +or +```yaml +- type: stat-ping + options: + hostname: http://192.168.130.1:8080 + groupId: 3 + showChart: false + showInfo: false +``` +You can use multiple StatPing widgets with different `groupId`s. + +Note, the Group Id is not directly visible in SttatPing UI, you can inspect the group select HTML element or the API response to find out. ##### Info - **CORS**: 🟠 Proxied @@ -1330,7 +1387,7 @@ Displays the current and recent uptime of your running services, via a self-host Displays the current downloads/torrents tasks of your Synology NAS -

+

##### Options @@ -1361,6 +1418,152 @@ Displays the current downloads/torrents tasks of your Synology NAS --- +### AdGuard Home Block Stats + +Fetches data from your [AdGuard Home](https://adguard.com/en/adguard-home/overview.html) instance, and +displays total number of allowed and blocked queries, plus a pie chart showing breakdown by block type. + +

+ +##### Options + +**Field** | **Type** | **Required** | **Description** +--- | --- | --- | --- +**`hostname`** | `string` | Required | The URL to your AdGuard Home instance +**`username`** | `string` | _Optional_ | If you've got auth enabled on AdGuard, provide your username here +**`password`** | `string` | _Optional_ | If you've got auth enabled on AdGuard, provide your password here + +##### Example + +```yaml +- type: adguard-stats + useProxy: true + options: + hostname: http://127.0.0.1 + username: admin + password: test +``` + +##### Info +- **CORS**: 🟠 Proxied +- **Auth**: 🟠 Optional +- **Price**: 🟒 Free +- **Host**: Self-Hosted (see [AdGuard Home](https://adguard.com/en/adguard-home/overview.html)) +- **Privacy**: _See [AdGuard Privacy Policy](https://adguard.com/en/privacy.html)_ + + +--- + +### AdGuard Home Filters + +Fetches data from your [AdGuard Home](https://adguard.com/en/adguard-home/overview.html) instance, to display the current status of each of your filter lists. Includes filter name, last updated, number of items, and a link to the list. + +

+ +##### Options + +**Field** | **Type** | **Required** | **Description** +--- | --- | --- | --- +**`hostname`** | `string` | Required | The URL to your AdGuard Home instance +**`username`** | `string` | _Optional_ | If you've got auth enabled on AdGuard, provide your username here +**`password`** | `string` | _Optional_ | If you've got auth enabled on AdGuard, provide your password here +**`showOnOffStatusOnly`** | `boolean` | _Optional_ | If set to `true`, will only show aggregated AdGuard filter status (on/off), instead of a list of filters + +##### Example + +```yaml +- type: adguard-filter-status + useProxy: true + options: + hostname: http://127.0.0.1 + username: admin + password: test + showOnOffStatusOnly: false +``` + +##### Info +- **CORS**: 🟠 Proxied +- **Auth**: 🟠 Optional +- **Price**: 🟒 Free +- **Host**: Self-Hosted (see [AdGuard Home](https://adguard.com/en/adguard-home/overview.html)) +- **Privacy**: _See [AdGuard Privacy Policy](https://adguard.com/en/privacy.html)_ + +--- + +### AdGuard Home DNS Info + +Fetches data from your [AdGuard Home](https://adguard.com/en/adguard-home/overview.html) instance, and displays the current status (Enabled / Disabled) of AdGuard DNS. Click show more to view detailed info, including upstream DNS provider, active ports, and the status of DNSSEC, EDNS CS, PTR and IPv6. + +

+ +##### Options + +**Field** | **Type** | **Required** | **Description** +--- | --- | --- | --- +**`hostname`** | `string` | Required | The URL to your AdGuard Home instance +**`username`** | `string` | _Optional_ | If you've got auth enabled on AdGuard, provide your username here +**`password`** | `string` | _Optional_ | If you've got auth enabled on AdGuard, provide your password here +**`showFullInfo`** | `boolean` | _Optional_ | If set to `true`, the full DNS info will be shown by default, without having to click "Show Info" + +##### Example + +```yaml +- type: adguard-dns-info + useProxy: true + options: + hostname: http://127.0.0.1 + username: admin + password: test + showFullInfo: false +``` + +##### Info +- **CORS**: 🟠 Proxied +- **Auth**: 🟠 Optional +- **Price**: 🟒 Free +- **Host**: Self-Hosted (see [AdGuard Home](https://adguard.com/en/adguard-home/overview.html)) +- **Privacy**: _See [AdGuard Privacy Policy](https://adguard.com/en/privacy.html)_ + +--- + +### AdGuard Home Top Domains + +Fetches data from your [AdGuard Home](https://adguard.com/en/adguard-home/overview.html) instance, and displays a list of the most queried, and most blocked domains. + +

+ +##### Options + +**Field** | **Type** | **Required** | **Description** +--- | --- | --- | --- +**`hostname`** | `string` | Required | The URL to your AdGuard Home instance +**`username`** | `string` | _Optional_ | If you've got auth enabled on AdGuard, provide your username here +**`password`** | `string` | _Optional_ | If you've got auth enabled on AdGuard, provide your password here +**`limit`** | `number` | _Optional_ | Specify the number of results to show, between `1` and `100`, defaults to `10` +**`hideBlockedDomains`** | `boolean` | _Optional_ | Don't show the blocked domains list (queried domains only) +**`hideQueriedDomains`** | `boolean` | _Optional_ | Don't show the queried domains list (blocked domains only) + +##### Example + +```yaml +- type: adguard-top-domains + useProxy: true + options: + hostname: http://127.0.0.1 + username: admin + password: test + limit: 10 +``` + +##### Info +- **CORS**: 🟠 Proxied +- **Auth**: 🟠 Optional +- **Price**: 🟒 Free +- **Host**: Self-Hosted (see [AdGuard Home](https://adguard.com/en/adguard-home/overview.html)) +- **Privacy**: _See [AdGuard Privacy Policy](https://adguard.com/en/privacy.html)_ + +--- + ## System Resource Monitoring The easiest method for displaying system info and resource usage in Dashy is with [Glances](https://nicolargo.github.io/glances/).