From b887cb7bfad649935773c101a488ec2b3e4ceb96 Mon Sep 17 00:00:00 2001 From: Lissy93 Date: Sun, 23 Jan 2022 12:20:10 +0000 Subject: [PATCH] Deploy website - based on a4a3c598fe91f027168109cd1854da5907fede89 --- 404.html | 4 ++-- assets/js/9be9f402.1e6e9a05.js | 1 + assets/js/9be9f402.b22b6751.js | 1 - assets/js/9d9f8394.b33b7b16.js | 1 - assets/js/9d9f8394.c03267c6.js | 1 + ...runtime~main.cf68debf.js => runtime~main.d6586337.js} | 2 +- docs/alternate-views/index.html | 4 ++-- docs/authentication/index.html | 4 ++-- docs/backup-restore/index.html | 4 ++-- docs/changelog/index.html | 4 ++-- docs/code-of-conduct/index.html | 4 ++-- docs/configuring/index.html | 4 ++-- docs/contributing/index.html | 4 ++-- docs/credits/index.html | 4 ++-- docs/deployment/index.html | 4 ++-- docs/developing/index.html | 4 ++-- docs/development-guides/index.html | 4 ++-- docs/icons/index.html | 4 ++-- docs/index.html | 4 ++-- docs/license/index.html | 4 ++-- docs/management/index.html | 4 ++-- docs/multi-language-support/index.html | 4 ++-- docs/privacy/index.html | 4 ++-- docs/quick-start/index.html | 4 ++-- docs/readme/index.html | 4 ++-- docs/release-workflow/index.html | 4 ++-- docs/searching/index.html | 4 ++-- docs/showcase/index.html | 4 ++-- docs/showcase/readme/index.html | 4 ++-- docs/status-indicators/index.html | 4 ++-- docs/theming/index.html | 4 ++-- docs/troubleshooting/index.html | 9 +++++---- docs/widgets/index.html | 9 +++++---- index.html | 4 ++-- markdown-page/index.html | 4 ++-- search/index.html | 4 ++-- survey/index.html | 4 ++-- 37 files changed, 73 insertions(+), 71 deletions(-) create mode 100644 assets/js/9be9f402.1e6e9a05.js delete mode 100644 assets/js/9be9f402.b22b6751.js delete mode 100644 assets/js/9d9f8394.b33b7b16.js create mode 100644 assets/js/9d9f8394.c03267c6.js rename assets/js/{runtime~main.cf68debf.js => runtime~main.d6586337.js} (97%) diff --git a/404.html b/404.html index 662f6fe9..e4863b69 100644 --- a/404.html +++ b/404.html @@ -5,13 +5,13 @@ Page Not Found | Dashy - +
Skip to main content

Page Not Found

We could not find what you were looking for.

Please contact the owner of the site that linked you to the original URL and let them know their link is broken.

- + \ No newline at end of file diff --git a/assets/js/9be9f402.1e6e9a05.js b/assets/js/9be9f402.1e6e9a05.js new file mode 100644 index 00000000..47b3448c --- /dev/null +++ b/assets/js/9be9f402.1e6e9a05.js @@ -0,0 +1 @@ +"use strict";(self.webpackChunkdashy=self.webpackChunkdashy||[]).push([[698],{3905:function(t,e,a){a.d(e,{Zo:function(){return d},kt:function(){return u}});var n=a(7294);function r(t,e,a){return e in t?Object.defineProperty(t,e,{value:a,enumerable:!0,configurable:!0,writable:!0}):t[e]=a,t}function l(t,e){var a=Object.keys(t);if(Object.getOwnPropertySymbols){var n=Object.getOwnPropertySymbols(t);e&&(n=n.filter((function(e){return Object.getOwnPropertyDescriptor(t,e).enumerable}))),a.push.apply(a,n)}return a}function i(t){for(var e=1;e=0||(r[a]=t[a]);return r}(t,e);if(Object.getOwnPropertySymbols){var l=Object.getOwnPropertySymbols(t);for(n=0;n=0||Object.prototype.propertyIsEnumerable.call(t,a)&&(r[a]=t[a])}return r}var p=n.createContext({}),s=function(t){var e=n.useContext(p),a=e;return t&&(a="function"==typeof t?t(e):i(i({},e),t)),a},d=function(t){var e=s(t.components);return n.createElement(p.Provider,{value:e},t.children)},m={inlineCode:"code",wrapper:function(t){var e=t.children;return n.createElement(n.Fragment,{},e)}},k=n.forwardRef((function(t,e){var a=t.components,r=t.mdxType,l=t.originalType,p=t.parentName,d=o(t,["components","mdxType","originalType","parentName"]),k=s(a),u=r,N=k["".concat(p,".").concat(u)]||k[u]||m[u]||l;return a?n.createElement(N,i(i({ref:e},d),{},{components:a})):n.createElement(N,i({ref:e},d))}));function u(t,e){var a=arguments,r=e&&e.mdxType;if("string"==typeof t||r){var l=a.length,i=new Array(l);i[0]=k;var o={};for(var p in e)hasOwnProperty.call(e,p)&&(o[p]=e[p]);o.originalType=t,o.mdxType="string"==typeof t?t:r,i[1]=o;for(var s=2;s\n
\n \n Speedcheck\n \n
\n \n')),(0,l.kt)("p",null,"Or"),(0,l.kt)("pre",null,(0,l.kt)("code",{parentName:"pre",className:"language-yaml"},'- type: embed\n options:\n css: \'.coinmarketcap-currency-widget { color: var(--widget-text-color); }\'\n html: \'
\'\n scriptSrc: \'https://files.coinmarketcap.com/static/widget/currency.js\'\n')),(0,l.kt)("hr",null),(0,l.kt)("h3",{id:"api-response"},"API Response"),(0,l.kt)("p",null,"Directly output plain-text response from any API-enabled service."),(0,l.kt)("p",null,"// Coming soon..."),(0,l.kt)("hr",null),(0,l.kt)("h3",{id:"prometheus-data"},"Prometheus Data"),(0,l.kt)("p",null,"Display data from any service with a Prometheus exporter."),(0,l.kt)("p",null,"// Coming soon..."),(0,l.kt)("hr",null),(0,l.kt)("h3",{id:"data-feed"},"Data Feed"),(0,l.kt)("p",null,"Show live data from an RSS-enabled service. The only required parameter is ",(0,l.kt)("inlineCode",{parentName:"p"},"rssUrl"),", which is the URL to the ATOM feed. See ",(0,l.kt)("a",{parentName:"p",href:"#rss-feed"},"RSS Widget")," for full list of available options."),(0,l.kt)("p",{align:"center"},(0,l.kt)("img",{width:"700",src:"https://i.ibb.co/1r88pvL/rss-feed-example-1.png"})),(0,l.kt)("h5",{id:"example-48"},"Example"),(0,l.kt)("pre",null,(0,l.kt)("code",{parentName:"pre",className:"language-yaml"},"- type: rss-feed\n options:\n rssUrl: https://notes.aliciasykes.com/feed\n")),(0,l.kt)("hr",null),(0,l.kt)("h2",{id:"usage--customizations"},"Usage & Customizations"),(0,l.kt)("h3",{id:"widget-usage-guide"},"Widget Usage Guide"),(0,l.kt)("p",null,"Like items, widgets are placed under sections. You may have one or more widgets per section."),(0,l.kt)("p",null,"In your YAML config file, this will look something like:"),(0,l.kt)("pre",null,(0,l.kt)("code",{parentName:"pre",className:"language-yaml"},"sections:\n- name: Today\n icon: far fa-calendar-day\n widgets:\n - type: clock\n options:\n format: en-GB\n - type: weather\n options:\n apiKey: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx\n city: London\n units: metric\n")),(0,l.kt)("blockquote",null,(0,l.kt)("p",{parentName:"blockquote"},'In this example, there is a single section, named "Today", using a Calendar icon from Font-Awesome. It has 2 widgets, a clock and the current weather.')),(0,l.kt)("hr",null),(0,l.kt)("h3",{id:"continuous-updates"},"Continuous Updates"),(0,l.kt)("p",null,"By default, a widget which displays dynamic data from an external source, will only fetch results on page load. If you would like to keep data updated at all times, you can enable ",(0,l.kt)("strong",{parentName:"p"},"Continuous Updates"),". This is done by setting a time value in the ",(0,l.kt)("inlineCode",{parentName:"p"},"updateInterval")," field."),(0,l.kt)("p",null,"The value of ",(0,l.kt)("inlineCode",{parentName:"p"},"updateInterval")," is optional, and is specified and seconds. It must be more than ",(0,l.kt)("inlineCode",{parentName:"p"},"10")," and less than ",(0,l.kt)("inlineCode",{parentName:"p"},"7200"),"."),(0,l.kt)("p",null,"For example, the following widget displaying stats from Pi-Hole will update ever 20 seconds."),(0,l.kt)("pre",null,(0,l.kt)("code",{parentName:"pre",className:"language-yaml"},"widgets:\n- type: pi-hole-stats\n updateInterval: 20\n options:\n hostname: http://192.168.130.2\n")),(0,l.kt)("p",null,"Note that if you have many widgets, and set them to continuously update frequently, you will notice a hit to performance. A widget that relies on data from an external API, will also consume your usage quota faster, if set to keep updating."),(0,l.kt)("hr",null),(0,l.kt)("h3",{id:"proxying-requests"},"Proxying Requests"),(0,l.kt)("p",null,"If a widget fails to make a data request, and the console shows a CORS error, this means the server is blocking client-side requests."),(0,l.kt)("p",null,"Dashy has a built-in CORS proxy (",(0,l.kt)("a",{parentName:"p",href:"https://github.com/Lissy93/dashy/blob/master/services/cors-proxy.js"},(0,l.kt)("inlineCode",{parentName:"a"},"services/cors-proxy.js")),"), which will be used automatically by some widgets, or can be forced to use by other by setting the ",(0,l.kt)("inlineCode",{parentName:"p"},"useProxy")," option."),(0,l.kt)("p",null,"For example:"),(0,l.kt)("pre",null,(0,l.kt)("code",{parentName:"pre",className:"language-yaml"},"widgets:\n- type: pi-hole-stats\n useProxy: true\n options:\n hostname: http://pi-hole.local\n")),(0,l.kt)("p",null,"Alternatively, and more securely, you can set the auth headers on your service to accept requests from Dashy. For example:"),(0,l.kt)("pre",null,(0,l.kt)("code",{parentName:"pre"},"Access-Control-Allow-Origin: https://location-of-dashy/\nVary: Origin\n")),(0,l.kt)("hr",null),(0,l.kt)("h3",{id:"widget-styling"},"Widget Styling"),(0,l.kt)("p",null,"Like elsewhere in Dashy, all colours can be easily modified with CSS variables. "),(0,l.kt)("p",null,"Widgets use the following color variables, which can be overridden if desired:"),(0,l.kt)("ul",null,(0,l.kt)("li",{parentName:"ul"},(0,l.kt)("inlineCode",{parentName:"li"},"--widget-text-color")," - Text color, defaults to ",(0,l.kt)("inlineCode",{parentName:"li"},"--primary")),(0,l.kt)("li",{parentName:"ul"},(0,l.kt)("inlineCode",{parentName:"li"},"--widget-background-color")," - Background color, defaults to ",(0,l.kt)("inlineCode",{parentName:"li"},"--background-darker")),(0,l.kt)("li",{parentName:"ul"},(0,l.kt)("inlineCode",{parentName:"li"},"--widget-accent-color")," - Accent color, defaults to ",(0,l.kt)("inlineCode",{parentName:"li"},"--background"))),(0,l.kt)("p",null,"For more info on how to apply custom variables, see the ",(0,l.kt)("a",{parentName:"p",href:"/docs/theming#setting-custom-css-in-the-ui"},"Theming Docs")),(0,l.kt)("hr",null),(0,l.kt)("h3",{id:"customizing-charts"},"Customizing Charts"),(0,l.kt)("p",null,"For widgets that contain charts, you can set an array of colors under ",(0,l.kt)("inlineCode",{parentName:"p"},"chartColors"),".\nTo specify the chart height, set ",(0,l.kt)("inlineCode",{parentName:"p"},"chartHeight")," to an integer (in ",(0,l.kt)("inlineCode",{parentName:"p"},"px"),"), defaults to ",(0,l.kt)("inlineCode",{parentName:"p"},"300"),".\nFor example:"),(0,l.kt)("pre",null,(0,l.kt)("code",{parentName:"pre",className:"language-yaml"},"- type: gl-load-history\n options:\n hostname: http://192.168.130.2:61208\n chartColors: ['#9b5de5', '#f15bb5', '#00bbf9', '#00f5d4']\n chartHeight: 450\n")),(0,l.kt)("hr",null),(0,l.kt)("h3",{id:"language-translations"},"Language Translations"),(0,l.kt)("p",null,"Since most of the content displayed within widgets is fetched from an external API, unless that API supports multiple languages, translating dynamic content is not possible."),(0,l.kt)("p",null,"However, any hard-coded content is translatable, and all dates and times will display in your local format."),(0,l.kt)("p",null,"For more info about multi-language support, see the ",(0,l.kt)("a",{parentName:"p",href:"/docs/multi-language-support"},"Internationalization Docs"),"."),(0,l.kt)("hr",null),(0,l.kt)("h3",{id:"widget-ui-options"},"Widget UI Options"),(0,l.kt)("p",null,"Widgets can be opened in full-page view, by clicking the Arrow icon (top-right). The URL in your address bar will also update, and visiting that web address directly will take you straight to that widget."),(0,l.kt)("p",null,"You can reload the data of any widget, by clicking the Refresh Data icon (also in top-right). This will only affect the widget where the action was triggered from."),(0,l.kt)("p",null,"All ",(0,l.kt)("a",{parentName:"p",href:"/docs/configuring#section"},"config options")," that can be applied to sections, can also be applied to widget sections. For example, to make a widget section double the width, set ",(0,l.kt)("inlineCode",{parentName:"p"},"displayData.cols: 2")," within the parent section. You can collapse a widget (by clicking the section title), and collapse state will be saved locally."),(0,l.kt)("p",null,"Widgets cannot currently be edited through the UI. This feature is in development, and will be released soon. In the meantime, you can either use the JSON config editor, or use ",(0,l.kt)("a",{parentName:"p",href:"https://github.com/coder/code-server"},"VS Code Server"),", or just SSH into your box and edit the conf.yml file directly."),(0,l.kt)("hr",null),(0,l.kt)("h3",{id:"build-your-own-widget"},"Build your own Widget"),(0,l.kt)("p",null,"Widgets are built in a modular fashion, making it easy for anyone to create their own custom components."),(0,l.kt)("p",null,"For a full tutorial on creating your own widget, you can follow ",(0,l.kt)("a",{parentName:"p",href:"/docs/development-guides#building-a-widget"},"this guide"),", or take a look at ",(0,l.kt)("a",{parentName:"p",href:"https://github.com/Lissy93/dashy/commit/3da76ce2999f57f76a97454c0276301e39957b8e"},"here")," for a code example. "),(0,l.kt)("p",null,"Alternatively, for displaying simple data, you could also just use the either the ",(0,l.kt)("a",{parentName:"p",href:"#iframe-widget"},"iframe"),", ",(0,l.kt)("a",{parentName:"p",href:"#html-embedded-widget"},"embed"),", ",(0,l.kt)("a",{parentName:"p",href:"#data-feed"},"data feed")," or ",(0,l.kt)("a",{parentName:"p",href:"#api-response"},"API response")," widgets."),(0,l.kt)("hr",null),(0,l.kt)("h3",{id:"requesting-a-widget"},"Requesting a Widget"),(0,l.kt)("p",null,"Suggestions for widget ideas are welcome. But there is no guarantee that I will build your widget idea."),(0,l.kt)("p",null,"You can suggest a widget ",(0,l.kt)("a",{parentName:"p",href:"https://git.io/Jygo3"},"here"),", please star the repo before submitting a ticket."),(0,l.kt)("p",null,"Please only request widgets for services that:"),(0,l.kt)("ul",null,(0,l.kt)("li",{parentName:"ul"},"Have a publicly accessible API"),(0,l.kt)("li",{parentName:"ul"},"Are CORS and HTTPS enabled"),(0,l.kt)("li",{parentName:"ul"},"Are free to use, or have a free plan"),(0,l.kt)("li",{parentName:"ul"},"Allow for use in their Terms of Service"),(0,l.kt)("li",{parentName:"ul"},"Would be useful for other users")),(0,l.kt)("p",null,"For services that are not officially supported, it is likely still possible to display data using either the ",(0,l.kt)("a",{parentName:"p",href:"#iframe-widget"},"iframe"),", ",(0,l.kt)("a",{parentName:"p",href:"#html-embedded-widget"},"embed")," or ",(0,l.kt)("a",{parentName:"p",href:"#api-response"},"API response")," widgets. For more advanced features, like charts and action buttons, you could also build your own widget, using ",(0,l.kt)("a",{parentName:"p",href:"/docs/development-guides#building-a-widget"},"this tutorial"),", it's fairly straight forward, and you can use an ",(0,l.kt)("a",{parentName:"p",href:"https://github.com/Lissy93/dashy/tree/master/src/components/Widgets"},"existing widget")," (or ",(0,l.kt)("a",{parentName:"p",href:"https://git.io/JygKI"},"this example"),") as a template."),(0,l.kt)("hr",null),(0,l.kt)("h3",{id:"troubleshooting-widget-errors"},"Troubleshooting Widget Errors"),(0,l.kt)("p",null,"If an error occurs when fetching or rendering results, you will see a short message in the UI. If that message doesn't addequatley explain the problem, then you can ",(0,l.kt)("a",{parentName:"p",href:"/docs/troubleshooting#how-to-open-browser-console"},"open the browser console")," to see more details."),(0,l.kt)("p",null,"Before proceeding, ensure that if the widget requires auth your API is correct, and for custom widgets, double check that the URL and protocol is correct."),(0,l.kt)("p",null,"If you're able to, you can find more information about why the request may be failing in the Dev Tools under the Network tab, and you can ensure your endpoint is correct and working using a tool like Postman."),(0,l.kt)("h4",{id:"cors-errors"},"CORS Errors"),(0,l.kt)("p",null,"The most common issue is a CORS error. This is a browser security mechanism which prevents the client-side app (Dashy) from from accessing resources on a remote origin, without that server's explicit permission (e.g. with headers like Access-Control-Allow-Origin). See the MDN Docs for more info: ",(0,l.kt)("a",{parentName:"p",href:"https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS"},"Cross-Origin Resource Sharing"),"."),(0,l.kt)("p",null,"There are several ways to fix a CORS error:"),(0,l.kt)("h5",{id:"option-1---ensure-correct-protocol"},"Option 1 - Ensure Correct Protocol"),(0,l.kt)("p",null,"You will get a CORS error if you try and access a http service from a https source. So ensure that the URL you are requesting has the right protocol, and is correctly formatted."),(0,l.kt)("h5",{id:"option-2---set-headers"},"Option 2 - Set Headers"),(0,l.kt)("p",null,"If you have control over the destination (e.g. for a self-hosted service), then you can simply apply the correct headers.\nAdd the ",(0,l.kt)("inlineCode",{parentName:"p"},"Access-Control-Allow-Origin")," header, with the value of either ",(0,l.kt)("inlineCode",{parentName:"p"},"*")," to allow requests from anywhere, or more securely, the host of where Dashy is served from. For example:"),(0,l.kt)("pre",null,(0,l.kt)("code",{parentName:"pre"},"Access-Control-Allow-Origin: https://url-of-dashy.local\n")),(0,l.kt)("p",null,"or"),(0,l.kt)("pre",null,(0,l.kt)("code",{parentName:"pre"},"Access-Control-Allow-Origin: *\n")),(0,l.kt)("h5",{id:"option-3---proxying-request"},"Option 3 - Proxying Request"),(0,l.kt)("p",null,"You can route requests through Dashy's built-in CORS proxy. Instructions and more details can be found ",(0,l.kt)("a",{parentName:"p",href:"#proxying-requests"},"here"),". 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."),(0,l.kt)("p",null,"Just add the ",(0,l.kt)("inlineCode",{parentName:"p"},"useProxy: true")," option to the failing widget."),(0,l.kt)("h5",{id:"option-4---use-a-plugin"},"Option 4 - Use a plugin"),(0,l.kt)("p",null,"For testing purposes, you can use an addon, which will disable the CORS checks. You can get the Allow-CORS extension for ",(0,l.kt)("a",{parentName:"p",href:"https://chrome.google.com/webstore/detail/allow-cors-access-control/lhobafahddgcelffkeicbaginigeejlf?hl=en-US"},"Chrome")," or ",(0,l.kt)("a",{parentName:"p",href:"https://addons.mozilla.org/en-US/firefox/addon/access-control-allow-origin/"},"Firefox"),", more details ",(0,l.kt)("a",{parentName:"p",href:"https://mybrowseraddon.com/access-control-allow-origin.html"},"here")),(0,l.kt)("hr",null),(0,l.kt)("h3",{id:"raising-an-issue"},"Raising an Issue"),(0,l.kt)("p",null,"If you need to submit a bug report for a failing widget, then please include the full console output (see ",(0,l.kt)("a",{parentName:"p",href:"/docs/troubleshooting#how-to-open-browser-console"},"how"),") as well as the relevant parts of your config file. Before sending the request, ensure you've read the docs. If you're new to GitHub, an haven't previously contributed to the project, then please fist star the repo to avoid your ticket being closed by the anti-spam bot."))}k.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/9be9f402.b22b6751.js b/assets/js/9be9f402.b22b6751.js deleted file mode 100644 index 2151566d..00000000 --- a/assets/js/9be9f402.b22b6751.js +++ /dev/null @@ -1 +0,0 @@ -"use strict";(self.webpackChunkdashy=self.webpackChunkdashy||[]).push([[698],{3905:function(t,e,a){a.d(e,{Zo:function(){return m},kt:function(){return u}});var n=a(7294);function r(t,e,a){return e in t?Object.defineProperty(t,e,{value:a,enumerable:!0,configurable:!0,writable:!0}):t[e]=a,t}function l(t,e){var a=Object.keys(t);if(Object.getOwnPropertySymbols){var n=Object.getOwnPropertySymbols(t);e&&(n=n.filter((function(e){return Object.getOwnPropertyDescriptor(t,e).enumerable}))),a.push.apply(a,n)}return a}function i(t){for(var e=1;e=0||(r[a]=t[a]);return r}(t,e);if(Object.getOwnPropertySymbols){var l=Object.getOwnPropertySymbols(t);for(n=0;n=0||Object.prototype.propertyIsEnumerable.call(t,a)&&(r[a]=t[a])}return r}var p=n.createContext({}),d=function(t){var e=n.useContext(p),a=e;return t&&(a="function"==typeof t?t(e):i(i({},e),t)),a},m=function(t){var e=d(t.components);return n.createElement(p.Provider,{value:e},t.children)},s={inlineCode:"code",wrapper:function(t){var e=t.children;return n.createElement(n.Fragment,{},e)}},k=n.forwardRef((function(t,e){var a=t.components,r=t.mdxType,l=t.originalType,p=t.parentName,m=o(t,["components","mdxType","originalType","parentName"]),k=d(a),u=r,N=k["".concat(p,".").concat(u)]||k[u]||s[u]||l;return a?n.createElement(N,i(i({ref:e},m),{},{components:a})):n.createElement(N,i({ref:e},m))}));function u(t,e){var a=arguments,r=e&&e.mdxType;if("string"==typeof t||r){var l=a.length,i=new Array(l);i[0]=k;var o={};for(var p in e)hasOwnProperty.call(e,p)&&(o[p]=e[p]);o.originalType=t,o.mdxType="string"==typeof t?t:r,i[1]=o;for(var d=2;d\n
\n \n Speedcheck\n \n
\n \n')),(0,l.kt)("p",null,"Or"),(0,l.kt)("pre",null,(0,l.kt)("code",{parentName:"pre",className:"language-yaml"},'- type: embed\n options:\n css: \'.coinmarketcap-currency-widget { color: var(--widget-text-color); }\'\n html: \'
\'\n scriptSrc: \'https://files.coinmarketcap.com/static/widget/currency.js\'\n')),(0,l.kt)("hr",null),(0,l.kt)("h3",{id:"api-response"},"API Response"),(0,l.kt)("p",null,"Directly output plain-text response from any API-enabled service."),(0,l.kt)("p",null,"// Coming soon..."),(0,l.kt)("hr",null),(0,l.kt)("h3",{id:"prometheus-data"},"Prometheus Data"),(0,l.kt)("p",null,"Display data from any service with a Prometheus exporter."),(0,l.kt)("p",null,"// Coming soon..."),(0,l.kt)("hr",null),(0,l.kt)("h3",{id:"data-feed"},"Data Feed"),(0,l.kt)("p",null,"Show live data from an RSS-enabled service. The only required parameter is ",(0,l.kt)("inlineCode",{parentName:"p"},"rssUrl"),", which is the URL to the ATOM feed. See ",(0,l.kt)("a",{parentName:"p",href:"#rss-feed"},"RSS Widget")," for full list of available options."),(0,l.kt)("p",{align:"center"},(0,l.kt)("img",{width:"700",src:"https://i.ibb.co/1r88pvL/rss-feed-example-1.png"})),(0,l.kt)("h5",{id:"example-48"},"Example"),(0,l.kt)("pre",null,(0,l.kt)("code",{parentName:"pre",className:"language-yaml"},"- type: rss-feed\n options:\n rssUrl: https://notes.aliciasykes.com/feed\n")),(0,l.kt)("hr",null),(0,l.kt)("h2",{id:"usage--customizations"},"Usage & Customizations"),(0,l.kt)("h3",{id:"widget-usage-guide"},"Widget Usage Guide"),(0,l.kt)("p",null,"Like items, widgets are placed under sections. You may have one or more widgets per section."),(0,l.kt)("p",null,"In your YAML config file, this will look something like:"),(0,l.kt)("pre",null,(0,l.kt)("code",{parentName:"pre",className:"language-yaml"},"sections:\n- name: Today\n icon: far fa-calendar-day\n widgets:\n - type: clock\n options:\n format: en-GB\n - type: weather\n options:\n apiKey: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx\n city: London\n units: metric\n")),(0,l.kt)("blockquote",null,(0,l.kt)("p",{parentName:"blockquote"},'In this example, there is a single section, named "Today", using a Calendar icon from Font-Awesome. It has 2 widgets, a clock and the current weather.')),(0,l.kt)("hr",null),(0,l.kt)("h3",{id:"continuous-updates"},"Continuous Updates"),(0,l.kt)("p",null,"By default, a widget which displays dynamic data from an external source, will only fetch results on page load. If you would like to keep data updated at all times, you can enable ",(0,l.kt)("strong",{parentName:"p"},"Continuous Updates"),". This is done by setting a time value in the ",(0,l.kt)("inlineCode",{parentName:"p"},"updateInterval")," field."),(0,l.kt)("p",null,"The value of ",(0,l.kt)("inlineCode",{parentName:"p"},"updateInterval")," is optional, and is specified and seconds. It must be more than ",(0,l.kt)("inlineCode",{parentName:"p"},"10")," and less than ",(0,l.kt)("inlineCode",{parentName:"p"},"7200"),"."),(0,l.kt)("p",null,"For example, the following widget displaying stats from Pi-Hole will update ever 20 seconds."),(0,l.kt)("pre",null,(0,l.kt)("code",{parentName:"pre",className:"language-yaml"},"widgets:\n- type: pi-hole-stats\n updateInterval: 20\n options:\n hostname: http://192.168.130.2\n")),(0,l.kt)("p",null,"Note that if you have many widgets, and set them to continuously update frequently, you will notice a hit to performance. A widget that relies on data from an external API, will also consume your usage quota faster, if set to keep updating."),(0,l.kt)("hr",null),(0,l.kt)("h3",{id:"proxying-requests"},"Proxying Requests"),(0,l.kt)("p",null,"If a widget fails to make a data request, and the console shows a CORS error, this means the server is blocking client-side requests."),(0,l.kt)("p",null,"Dashy has a built-in CORS proxy (",(0,l.kt)("a",{parentName:"p",href:"https://github.com/Lissy93/dashy/blob/master/services/cors-proxy.js"},(0,l.kt)("inlineCode",{parentName:"a"},"services/cors-proxy.js")),"), which will be used automatically by some widgets, or can be forced to use by other by setting the ",(0,l.kt)("inlineCode",{parentName:"p"},"useProxy")," option."),(0,l.kt)("p",null,"For example:"),(0,l.kt)("pre",null,(0,l.kt)("code",{parentName:"pre",className:"language-yaml"},"widgets:\n- type: pi-hole-stats\n useProxy: true\n options:\n hostname: http://pi-hole.local\n")),(0,l.kt)("p",null,"Alternativley, and more securley, you can set the auth headers on your service to accept requests from Dashy. For example:"),(0,l.kt)("pre",null,(0,l.kt)("code",{parentName:"pre"},"Access-Control-Allow-Origin: https://location-of-dashy/\nVary: Origin\n")),(0,l.kt)("hr",null),(0,l.kt)("h3",{id:"widget-styling"},"Widget Styling"),(0,l.kt)("p",null,"Like elsewhere in Dashy, all colours can be easily modified with CSS variables. "),(0,l.kt)("p",null,"Widgets use the following color variables, which can be overridden if desired:"),(0,l.kt)("ul",null,(0,l.kt)("li",{parentName:"ul"},(0,l.kt)("inlineCode",{parentName:"li"},"--widget-text-color")," - Text color, defaults to ",(0,l.kt)("inlineCode",{parentName:"li"},"--primary")),(0,l.kt)("li",{parentName:"ul"},(0,l.kt)("inlineCode",{parentName:"li"},"--widget-background-color")," - Background color, defaults to ",(0,l.kt)("inlineCode",{parentName:"li"},"--background-darker")),(0,l.kt)("li",{parentName:"ul"},(0,l.kt)("inlineCode",{parentName:"li"},"--widget-accent-color")," - Accent color, defaults to ",(0,l.kt)("inlineCode",{parentName:"li"},"--background"))),(0,l.kt)("p",null,"For more info on how to apply custom variables, see the ",(0,l.kt)("a",{parentName:"p",href:"/docs/theming#setting-custom-css-in-the-ui"},"Theming Docs")),(0,l.kt)("hr",null),(0,l.kt)("h3",{id:"customizing-charts"},"Customizing Charts"),(0,l.kt)("p",null,"For widgets that contain charts, you can set an array of colors under ",(0,l.kt)("inlineCode",{parentName:"p"},"chartColors"),".\nTo specify the chart height, set ",(0,l.kt)("inlineCode",{parentName:"p"},"chartHeight")," to an integer (in ",(0,l.kt)("inlineCode",{parentName:"p"},"px"),"), defaults to ",(0,l.kt)("inlineCode",{parentName:"p"},"300"),".\nFor example:"),(0,l.kt)("pre",null,(0,l.kt)("code",{parentName:"pre",className:"language-yaml"},"- type: gl-load-history\n options:\n hostname: http://192.168.130.2:61208\n chartColors: ['#9b5de5', '#f15bb5', '#00bbf9', '#00f5d4']\n chartHeight: 450\n")),(0,l.kt)("hr",null),(0,l.kt)("h3",{id:"language-translations"},"Language Translations"),(0,l.kt)("p",null,"Since most of the content displayed within widgets is fetched from an external API, unless that API supports multiple languages, translating dynamic content is not possible."),(0,l.kt)("p",null,"However, any hard-coded content is translatable, and all dates and times will display in your local format."),(0,l.kt)("p",null,"For more info about multi-language support, see the ",(0,l.kt)("a",{parentName:"p",href:"/docs/multi-language-support"},"Internationalization Docs"),"."),(0,l.kt)("hr",null),(0,l.kt)("h3",{id:"widget-ui-options"},"Widget UI Options"),(0,l.kt)("p",null,"Widgets can be opened in full-page view, by clicking the Arrow icon (top-right). The URL in your address bar will also update, and visiting that web address directly will take you straight to that widget."),(0,l.kt)("p",null,"You can reload the data of any widget, by clicking the Refresh Data icon (also in top-right). This will only affect the widget where the action was triggered from."),(0,l.kt)("p",null,"All ",(0,l.kt)("a",{parentName:"p",href:"/docs/configuring#section"},"config options")," that can be applied to sections, can also be applied to widget sections. For example, to make a widget section double the width, set ",(0,l.kt)("inlineCode",{parentName:"p"},"displayData.cols: 2")," within the parent section. You can collapse a widget (by clicking the section title), and collapse state will be saved locally."),(0,l.kt)("p",null,"Widgets cannot currently be edited through the UI. This feature is in development, and will be released soon. In the meantime, you can either use the JSON config editor, or use ",(0,l.kt)("a",{parentName:"p",href:"https://github.com/coder/code-server"},"VS Code Server"),", or just SSH into your box and edit the conf.yml file directly."),(0,l.kt)("hr",null),(0,l.kt)("h3",{id:"build-your-own-widget"},"Build your own Widget"),(0,l.kt)("p",null,"Widgets are built in a modular fashion, making it easy for anyone to create their own custom components."),(0,l.kt)("p",null,"For a full tutorial on creating your own widget, you can follow ",(0,l.kt)("a",{parentName:"p",href:"/docs/development-guides#building-a-widget"},"this guide"),", or take a look at ",(0,l.kt)("a",{parentName:"p",href:"https://github.com/Lissy93/dashy/commit/3da76ce2999f57f76a97454c0276301e39957b8e"},"here")," for a code example. "),(0,l.kt)("p",null,"Alternatively, for displaying simple data, you could also just use the either the ",(0,l.kt)("a",{parentName:"p",href:"#iframe-widget"},"iframe"),", ",(0,l.kt)("a",{parentName:"p",href:"#html-embedded-widget"},"embed"),", ",(0,l.kt)("a",{parentName:"p",href:"#data-feed"},"data feed")," or ",(0,l.kt)("a",{parentName:"p",href:"#api-response"},"API response")," widgets."),(0,l.kt)("hr",null),(0,l.kt)("h3",{id:"requesting-a-widget"},"Requesting a Widget"),(0,l.kt)("p",null,"Suggestions for widget ideas are welcome. But there is no guarantee that I will build your widget idea."),(0,l.kt)("p",null,"You can suggest a widget ",(0,l.kt)("a",{parentName:"p",href:"https://git.io/Jygo3"},"here"),", please star the repo before submitting a ticket."),(0,l.kt)("p",null,"Please only request widgets for services that:"),(0,l.kt)("ul",null,(0,l.kt)("li",{parentName:"ul"},"Have a publicly accessible API"),(0,l.kt)("li",{parentName:"ul"},"Are CORS and HTTPS enabled"),(0,l.kt)("li",{parentName:"ul"},"Are free to use, or have a free plan"),(0,l.kt)("li",{parentName:"ul"},"Allow for use in their Terms of Service"),(0,l.kt)("li",{parentName:"ul"},"Would be useful for other users")),(0,l.kt)("p",null,"For services that are not officially supported, it is likely still possible to display data using either the ",(0,l.kt)("a",{parentName:"p",href:"#iframe-widget"},"iframe"),", ",(0,l.kt)("a",{parentName:"p",href:"#html-embedded-widget"},"embed")," or ",(0,l.kt)("a",{parentName:"p",href:"#api-response"},"API response")," widgets. For more advanced features, like charts and action buttons, you could also build your own widget, using ",(0,l.kt)("a",{parentName:"p",href:"/docs/development-guides#building-a-widget"},"this tutorial"),", it's fairly straight forward, and you can use an ",(0,l.kt)("a",{parentName:"p",href:"https://github.com/Lissy93/dashy/tree/master/src/components/Widgets"},"existing widget")," (or ",(0,l.kt)("a",{parentName:"p",href:"https://git.io/JygKI"},"this example"),") as a template."))}k.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/9d9f8394.b33b7b16.js b/assets/js/9d9f8394.b33b7b16.js deleted file mode 100644 index 2a6573c0..00000000 --- a/assets/js/9d9f8394.b33b7b16.js +++ /dev/null @@ -1 +0,0 @@ -"use strict";(self.webpackChunkdashy=self.webpackChunkdashy||[]).push([[360],{3905:function(e,t,n){n.d(t,{Zo:function(){return d},kt:function(){return c}});var a=n(7294);function o(e,t,n){return t in e?Object.defineProperty(e,t,{value:n,enumerable:!0,configurable:!0,writable:!0}):e[t]=n,e}function r(e,t){var n=Object.keys(e);if(Object.getOwnPropertySymbols){var a=Object.getOwnPropertySymbols(e);t&&(a=a.filter((function(t){return Object.getOwnPropertyDescriptor(e,t).enumerable}))),n.push.apply(n,a)}return n}function i(e){for(var t=1;t=0||(o[n]=e[n]);return o}(e,t);if(Object.getOwnPropertySymbols){var r=Object.getOwnPropertySymbols(e);for(a=0;a=0||Object.prototype.propertyIsEnumerable.call(e,n)&&(o[n]=e[n])}return o}var l=a.createContext({}),u=function(e){var t=a.useContext(l),n=t;return e&&(n="function"==typeof e?e(t):i(i({},t),e)),n},d=function(e){var t=u(e.components);return a.createElement(l.Provider,{value:t},e.children)},h={inlineCode:"code",wrapper:function(e){var t=e.children;return a.createElement(a.Fragment,{},t)}},p=a.forwardRef((function(e,t){var n=e.components,o=e.mdxType,r=e.originalType,l=e.parentName,d=s(e,["components","mdxType","originalType","parentName"]),p=u(n),c=o,m=p["".concat(l,".").concat(c)]||p[c]||h[c]||r;return n?a.createElement(m,i(i({ref:t},d),{},{components:n})):a.createElement(m,i({ref:t},d))}));function c(e,t){var n=arguments,o=t&&t.mdxType;if("string"==typeof e||o){var r=n.length,i=new Array(r);i[0]=p;var s={};for(var l in t)hasOwnProperty.call(t,l)&&(s[l]=t[l]);s.originalType=e,s.mdxType="string"==typeof e?e:o,i[1]=s;for(var u=2;uRefused to Connect in Modal or Workspace View",id:"refused-to-connect-in-modal-or-workspace-view",children:[{value:"NGINX",id:"nginx",children:[]},{value:"Caddy",id:"caddy",children:[]},{value:"Apache",id:"apache",children:[]}]},{value:"404 On Static Hosting",id:"404-on-static-hosting",children:[]},{value:"Yarn Error",id:"yarn-error",children:[]},{value:"Auth Validation Error: "should be object"",id:"auth-validation-error-should-be-object",children:[]},{value:"Config Not Updating",id:"config-not-updating",children:[]},{value:"Config Still not Updating",id:"config-still-not-updating",children:[]},{value:"Styles and Assets not Updating",id:"styles-and-assets-not-updating",children:[]},{value:"DockerHub toomanyrequests",id:"dockerhub-toomanyrequests",children:[]},{value:"Config Validation Errors",id:"config-validation-errors",children:[]},{value:"Node Sass does not yet support your current environment",id:"node-sass-does-not-yet-support-your-current-environment",children:[]},{value:"Error: Cannot find module './_baseValues'",id:"error-cannot-find-module-_basevalues",children:[]},{value:"Invalid Host Header while running through ngrok",id:"invalid-host-header-while-running-through-ngrok",children:[]},{value:"Warnings in the Console during deploy",id:"warnings-in-the-console-during-deploy",children:[]},{value:"Docker Login Fails on Ubuntu",id:"docker-login-fails-on-ubuntu",children:[]},{value:"Status Checks Failing",id:"status-checks-failing",children:[]},{value:"How-To Open Browser Console",id:"how-to-open-browser-console",children:[]},{value:"Git Contributions not Displaying",id:"git-contributions-not-displaying",children:[]}],h={toc:d};function p(e){var t=e.components,n=(0,o.Z)(e,i);return(0,r.kt)("wrapper",(0,a.Z)({},h,n,{components:t,mdxType:"MDXLayout"}),(0,r.kt)("h1",{id:"troubleshooting"},"Troubleshooting"),(0,r.kt)("blockquote",null,(0,r.kt)("p",{parentName:"blockquote"},(0,r.kt)("em",{parentName:"p"},(0,r.kt)("strong",{parentName:"em"},"This document contains common problems and their solutions."))),(0,r.kt)("p",{parentName:"blockquote"},(0,r.kt)("em",{parentName:"p"},"If you came across an issue where the solution was not immediately obvious, consider adding it to this list to help other users."))),(0,r.kt)("h3",{id:"contents"},"Contents"),(0,r.kt)("ul",null,(0,r.kt)("li",{parentName:"ul"},(0,r.kt)("a",{parentName:"li",href:"#refused-to-connect-in-modal-or-workspace-view"},"Refused to Connect in Web Content View")),(0,r.kt)("li",{parentName:"ul"},(0,r.kt)("a",{parentName:"li",href:"#404-on-static-hosting"},"404 On Static Hosting")),(0,r.kt)("li",{parentName:"ul"},(0,r.kt)("a",{parentName:"li",href:"#yarn-error"},"Yarn Build or Run Error")),(0,r.kt)("li",{parentName:"ul"},(0,r.kt)("a",{parentName:"li",href:"#auth-validation-error-should-be-object"},'Auth Validation Error: "should be object"')),(0,r.kt)("li",{parentName:"ul"},(0,r.kt)("a",{parentName:"li",href:"#config-not-updating"},"Config Not Updating")),(0,r.kt)("li",{parentName:"ul"},(0,r.kt)("a",{parentName:"li",href:"#config-still-not-updating"},"Config Still not Updating")),(0,r.kt)("li",{parentName:"ul"},(0,r.kt)("a",{parentName:"li",href:"#styles-and-assets-not-updating"},"Styles and Assets not Updating")),(0,r.kt)("li",{parentName:"ul"},(0,r.kt)("a",{parentName:"li",href:"#dockerhub-toomanyrequests"},"DockerHub toomanyrequests")),(0,r.kt)("li",{parentName:"ul"},(0,r.kt)("a",{parentName:"li",href:"#config-validation-errors"},"Config Validation Errors")),(0,r.kt)("li",{parentName:"ul"},(0,r.kt)("a",{parentName:"li",href:"#node-sass-does-not-yet-support-your-current-environment"},"Node Sass unsupported environment")),(0,r.kt)("li",{parentName:"ul"},(0,r.kt)("a",{parentName:"li",href:"#error-cannot-find-module-_basevalues"},"Cannot find module './_baseValues'")),(0,r.kt)("li",{parentName:"ul"},(0,r.kt)("a",{parentName:"li",href:"#invalid-host-header-while-running-through-ngrok"},"Ngrok Invalid Host Headers")),(0,r.kt)("li",{parentName:"ul"},(0,r.kt)("a",{parentName:"li",href:"#warnings-in-the-console-during-deploy"},"Warnings in the Console during deploy")),(0,r.kt)("li",{parentName:"ul"},(0,r.kt)("a",{parentName:"li",href:"#docker-login-fails-on-ubuntu"},"Docker Login Fails on Ubuntu")),(0,r.kt)("li",{parentName:"ul"},(0,r.kt)("a",{parentName:"li",href:"#status-checks-failing"},"Status Checks Failing")),(0,r.kt)("li",{parentName:"ul"},(0,r.kt)("a",{parentName:"li",href:"#how-to-open-browser-console"},"How-To Open Browser Console")),(0,r.kt)("li",{parentName:"ul"},(0,r.kt)("a",{parentName:"li",href:"#git-contributions-not-displaying"},"Git Contributions not Displaying"))),(0,r.kt)("hr",null),(0,r.kt)("h2",{id:"refused-to-connect-in-modal-or-workspace-view"},(0,r.kt)("inlineCode",{parentName:"h2"},"Refused to Connect")," in Modal or Workspace View"),(0,r.kt)("p",null,"This is not an issue with Dashy, but instead caused by the target app preventing direct access through embedded elements. It can be fixed by setting the ",(0,r.kt)("a",{parentName:"p",href:"https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Frame-Options"},(0,r.kt)("inlineCode",{parentName:"a"},"X-Frame-Options"))," HTTP header set to ",(0,r.kt)("inlineCode",{parentName:"p"},"ALLOW [path to Dashy]")," or ",(0,r.kt)("inlineCode",{parentName:"p"},"SAMEORIGIN"),", as defined in ",(0,r.kt)("a",{parentName:"p",href:"https://datatracker.ietf.org/doc/html/rfc7034"},"RFC-7034"),". These settings are usually set in the config file for the web server that's hosting the target application, here are some examples of how to enable cross-origin access with common web servers:"),(0,r.kt)("h3",{id:"nginx"},"NGINX"),(0,r.kt)("p",null,"In NGINX, you can use the ",(0,r.kt)("a",{parentName:"p",href:"https://nginx.org/en/docs/http/ngx_http_headers_module.html"},(0,r.kt)("inlineCode",{parentName:"a"},"add_header"))," module within the app block."),(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre"},"server {\n ...\n add_header X-Frame-Options SAMEORIGIN always;\n}\n")),(0,r.kt)("p",null,"Then reload with ",(0,r.kt)("inlineCode",{parentName:"p"},"service nginx reload")),(0,r.kt)("h3",{id:"caddy"},"Caddy"),(0,r.kt)("p",null,"In Caddy, you can use the ",(0,r.kt)("a",{parentName:"p",href:"https://caddyserver.com/docs/caddyfile/directives/header"},(0,r.kt)("inlineCode",{parentName:"a"},"header"))," directive."),(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre",className:"language-yaml"},"header {\n X-Frame-Options SAMEORIGIN\n}\n")),(0,r.kt)("h3",{id:"apache"},"Apache"),(0,r.kt)("p",null,"In Apache, you can use the ",(0,r.kt)("a",{parentName:"p",href:"https://httpd.apache.org/docs/current/mod/mod_headers.html"},(0,r.kt)("inlineCode",{parentName:"a"},"mod_headers"))," module to set the ",(0,r.kt)("inlineCode",{parentName:"p"},"X-Frame-Options")," in your config file. This file is usually located somewhere like `/etc/apache2/httpd.conf"),(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre"},'Header set X-Frame-Options: "ALLOW-FROM http://[dashy-location]/" \n')),(0,r.kt)("hr",null),(0,r.kt)("h2",{id:"404-on-static-hosting"},"404 On Static Hosting"),(0,r.kt)("p",null,"If you're seeing Dashy's 404 page on initial load/ refresh, and then the main app when you go back to Home, then this is likely caused by the Vue router, and if so can be fixed in one of two ways. "),(0,r.kt)("p",null,"The first solution is to switch the routing mode, from HTML5 ",(0,r.kt)("inlineCode",{parentName:"p"},"history")," mode to ",(0,r.kt)("inlineCode",{parentName:"p"},"hash")," mode, by setting ",(0,r.kt)("inlineCode",{parentName:"p"},"appConfig.routingMode")," to ",(0,r.kt)("inlineCode",{parentName:"p"},"hash"),"."),(0,r.kt)("p",null,"If this works, but you wish to continue using HTML5 history mode, then a bit of extra ",(0,r.kt)("a",{parentName:"p",href:"/docs/management#web-server-configuration"},"server configuration")," is required. This is explained in more detaail in the ",(0,r.kt)("a",{parentName:"p",href:"https://router.vuejs.org/guide/essentials/history-mode.html"},"Vue Docs"),". Once completed, you can then use ",(0,r.kt)("inlineCode",{parentName:"p"},"routingMode: history")," again, for neater URLs."),(0,r.kt)("hr",null),(0,r.kt)("h2",{id:"yarn-error"},"Yarn Error"),(0,r.kt)("p",null,"For more info, see ",(0,r.kt)("a",{parentName:"p",href:"https://github.com/Lissy93/dashy/issues/1"},"Issue #1")),(0,r.kt)("p",null,"First of all, check that you've got yarn installed correctly - see the ",(0,r.kt)("a",{parentName:"p",href:"https://classic.yarnpkg.com/en/docs/install"},"yarn installation docs")," for more info."),(0,r.kt)("p",null,"If you're getting an error about scenarios, then you've likely installed the wrong yarn... (you're ",(0,r.kt)("a",{parentName:"p",href:"https://github.com/yarnpkg/yarn/issues/2821"},"not")," the only one!). You can fix it by uninstalling, adding the correct repo, and reinstalling, for example, in Debian:"),(0,r.kt)("ul",null,(0,r.kt)("li",{parentName:"ul"},(0,r.kt)("inlineCode",{parentName:"li"},"sudo apt remove yarn")),(0,r.kt)("li",{parentName:"ul"},(0,r.kt)("inlineCode",{parentName:"li"},"curl -sS https://dl.yarnpkg.com/debian/pubkey.gpg | sudo apt-key add -")),(0,r.kt)("li",{parentName:"ul"},(0,r.kt)("inlineCode",{parentName:"li"},'echo "deb https://dl.yarnpkg.com/debian/ stable main" | sudo tee /etc/apt/sources.list.d/yarn.list')),(0,r.kt)("li",{parentName:"ul"},(0,r.kt)("inlineCode",{parentName:"li"},"sudo apt update && sudo apt install yarn"))),(0,r.kt)("p",null,"Alternatively, as a workaround, you have several options:"),(0,r.kt)("ul",null,(0,r.kt)("li",{parentName:"ul"},"Try using ",(0,r.kt)("a",{parentName:"li",href:"https://www.npmjs.com/get-npm"},"NPM")," instead: So clone, cd, then run ",(0,r.kt)("inlineCode",{parentName:"li"},"npm install"),", ",(0,r.kt)("inlineCode",{parentName:"li"},"npm run build")," and ",(0,r.kt)("inlineCode",{parentName:"li"},"npm start")),(0,r.kt)("li",{parentName:"ul"},"Try using ",(0,r.kt)("a",{parentName:"li",href:"https://www.docker.com/get-started"},"Docker")," instead, and all of the system setup and dependencies will already be taken care of. So from within the directory, just run ",(0,r.kt)("inlineCode",{parentName:"li"},"docker build -t lissy93/dashy .")," to build, and then use docker start to run the project, e.g: ",(0,r.kt)("inlineCode",{parentName:"li"},"docker run -it -p 8080:80 lissy93/dashy")," (see the ",(0,r.kt)("a",{parentName:"li",href:"https://github.com/Lissy93/dashy/blob/master/docs/deployment.md#deploy-with-docker"},"deploying docs")," for more info)")),(0,r.kt)("hr",null),(0,r.kt)("h2",{id:"auth-validation-error-should-be-object"},'Auth Validation Error: "should be object"'),(0,r.kt)("p",null,"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 ",(0,r.kt)("inlineCode",{parentName:"p"},"appConfig.auth")," object is now an object, which has a ",(0,r.kt)("inlineCode",{parentName:"p"},"users")," property."),(0,r.kt)("p",null,"For more info, see ",(0,r.kt)("a",{parentName:"p",href:"https://github.com/Lissy93/dashy/discussions/177"},"this announcement"),"."),(0,r.kt)("p",null,"You can fix this by replacing:"),(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre",className:"language-yaml"},"auth:\n- user: xxx\n hash: xxx\n")),(0,r.kt)("p",null,"with"),(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre",className:"language-yaml"},"auth:\n users:\n - user: xxx\n hash: xxx\n")),(0,r.kt)("hr",null),(0,r.kt)("h2",{id:"config-not-updating"},"Config Not Updating"),(0,r.kt)("p",null,'Dashy has the option to save settings and config locally, in browser storage. Anything here will take precedence over whatever is in your config file, sometimes with unintended consequences. If you\'ve updated the config file manually, and are not seeing changes reflected in the UI, then try visiting the site in Incognito mode. If that works, then the solution is just to clear local storage. This can be done from the config menu, under "Clear Local Settings".'),(0,r.kt)("hr",null),(0,r.kt)("h2",{id:"config-still-not-updating"},"Config Still not Updating"),(0,r.kt)("p",null,"Sometimes your text editor updates files ",(0,r.kt)("a",{parentName:"p",href:"https://linuxhandbook.com/inode-linux/"},"inode"),", meaning changes will not be picked up by the Docker container. This ",(0,r.kt)("a",{parentName:"p",href:"https://medium.com/@jonsbun/why-need-to-be-careful-when-mounting-single-files-into-a-docker-container-4f929340834"},"article")," explains things further."),(0,r.kt)("hr",null),(0,r.kt)("h2",{id:"styles-and-assets-not-updating"},"Styles and Assets not Updating"),(0,r.kt)("p",null,"If you find that your styles and other visual assets work when visiting ",(0,r.kt)("inlineCode",{parentName:"p"},"ip:port")," by not ",(0,r.kt)("inlineCode",{parentName:"p"},"dashy.domain.com"),", then this is usually caused by caching. In your browser, do a hard-refresh (",(0,r.kt)("kbd",null,"Ctrl")," + ",(0,r.kt)("kbd",null,"F5"),"). If you use Cloudflare, then you can clear the cache through the management console, or set the cache level to Bypass for certain files, under the Rules tab."),(0,r.kt)("hr",null),(0,r.kt)("h2",{id:"dockerhub-toomanyrequests"},"DockerHub ",(0,r.kt)("inlineCode",{parentName:"h2"},"toomanyrequests")),(0,r.kt)("p",null,"This situation relates to error messages similar to one of the following, returned when pulling, updating or running the Docker container from Docker Hub."),(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre"},"Continuing execution. Pulling image lissy93/dashy:release-1.6.0 \nerror pulling image configuration: toomanyrequests\n")),(0,r.kt)("p",null,"or"),(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre"},"You have reached your pull rate limit. You may increase the limit by authenticating and upgrading: https://www.docker.com/increase-rate-limit\n")),(0,r.kt)("p",null,"When DockerHub returns one of these errors, or a ",(0,r.kt)("inlineCode",{parentName:"p"},"429")," status, that means you've hit your rate limit. This was ",(0,r.kt)("a",{parentName:"p",href:"https://www.docker.com/blog/scaling-docker-to-serve-millions-more-developers-network-egress/"},"introduced")," last year, and prevents unauthenticated or free users from running docker pull more than 100 times per 6 hours.\nYou can ",(0,r.kt)("a",{parentName:"p",href:"https://www.docker.com/blog/checking-your-current-docker-pull-rate-limits-and-status/"},"check your rate limit status")," by looking for the ",(0,r.kt)("inlineCode",{parentName:"p"},"ratelimit-remaining")," header in any DockerHub responses. "),(0,r.kt)("h4",{id:"solution-1---use-an-alternate-container-registry"},"Solution 1 - Use an alternate container registry"),(0,r.kt)("ul",null,(0,r.kt)("li",{parentName:"ul"},"Dashy is also availible through GHCR, which at present does not have any hard limits. Just use ",(0,r.kt)("inlineCode",{parentName:"li"},"docker pull ghcr.io/lissy93/dashy:latest")," to fetch the image"),(0,r.kt)("li",{parentName:"ul"},"You can also build the image from source, by cloning the repo, and running ",(0,r.kt)("inlineCode",{parentName:"li"},"docker build -t dashy .")," or use the pre-made docker compose")),(0,r.kt)("h4",{id:"solution-2---increase-your-rate-limits"},"Solution 2 - Increase your rate limits"),(0,r.kt)("ul",null,(0,r.kt)("li",{parentName:"ul"},"Logging in to DockerHub will increase your rate limit from 100 requests to 200 requests per 6 hour period"),(0,r.kt)("li",{parentName:"ul"},"Upgrading to a Pro for $5/month will increase your image requests to 5,000 per day, and any plans above have no rate limits"),(0,r.kt)("li",{parentName:"ul"},"Since rate limits are counted based on your IP address, proxying your requests, or using a VPN may work")),(0,r.kt)("hr",null),(0,r.kt)("h2",{id:"config-validation-errors"},"Config Validation Errors"),(0,r.kt)("p",null,"The configuration file is validated against ",(0,r.kt)("a",{parentName:"p",href:"https://github.com/Lissy93/dashy/blob/master/src/utils/ConfigSchema.json"},"Dashy's Schema")," using AJV."),(0,r.kt)("p",null,"First, check that your syntax is valid, using ",(0,r.kt)("a",{parentName:"p",href:"https://codebeautify.org/yaml-validator/"},"YAML Validator")," or ",(0,r.kt)("a",{parentName:"p",href:"https://codebeautify.org/jsonvalidator"},"JSON Validator"),". If the issue persists, then take a look at the ",(0,r.kt)("a",{parentName:"p",href:"https://github.com/Lissy93/dashy/blob/master/src/utils/ConfigSchema.json"},"schema"),", and verify that the field you are trying to add/ modify matches the required format. You can also use ",(0,r.kt)("a",{parentName:"p",href:"https://www.jsonschemavalidator.net/s/JFUj7X9J"},"this tool")," to validate your JSON config against the schema, or run ",(0,r.kt)("inlineCode",{parentName:"p"},"yarn validate-config"),"."),(0,r.kt)("p",null,"If you're trying to use a recently released feature, and are getting a warning, this is likely because you've not yet updated the the current latest version of Dashy."),(0,r.kt)("p",null,"If the issue still persists, you should raise an issue."),(0,r.kt)("hr",null),(0,r.kt)("h2",{id:"node-sass-does-not-yet-support-your-current-environment"},"Node Sass does not yet support your current environment"),(0,r.kt)("p",null,"Caused by node-sass's binaries being built for a for a different architecture\nTo fix this, just run: ",(0,r.kt)("inlineCode",{parentName:"p"},"yarn rebuild node-sass")),(0,r.kt)("hr",null),(0,r.kt)("h2",{id:"error-cannot-find-module-_basevalues"},"Error: Cannot find module './_baseValues'"),(0,r.kt)("p",null,"Clearing the cache should fix this: ",(0,r.kt)("inlineCode",{parentName:"p"},"yarn cache clean"),"\nIf the issue persists, remove (",(0,r.kt)("inlineCode",{parentName:"p"},"rm -rf node_modules\\ yarn.lock"),") and reinstall (",(0,r.kt)("inlineCode",{parentName:"p"},"yarn"),") node_modules"),(0,r.kt)("hr",null),(0,r.kt)("h2",{id:"invalid-host-header-while-running-through-ngrok"},"Invalid Host Header while running through ngrok"),(0,r.kt)("p",null,"Just add the ",(0,r.kt)("a",{parentName:"p",href:"https://ngrok.com/docs#http-host-header"},"-host-header")," flag, e.g. ",(0,r.kt)("inlineCode",{parentName:"p"},'ngrok http 8080 -host-header="localhost:8080"')),(0,r.kt)("hr",null),(0,r.kt)("h2",{id:"warnings-in-the-console-during-deploy"},"Warnings in the Console during deploy"),(0,r.kt)("p",null,"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."),(0,r.kt)("hr",null),(0,r.kt)("h2",{id:"docker-login-fails-on-ubuntu"},"Docker Login Fails on Ubuntu"),(0,r.kt)("p",null,"Run ",(0,r.kt)("inlineCode",{parentName:"p"},"sudo apt install gnupg2 pass && gpg2 -k")),(0,r.kt)("hr",null),(0,r.kt)("h2",{id:"status-checks-failing"},"Status Checks Failing"),(0,r.kt)("p",null,"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:"),(0,r.kt)("p",null,"If your service requires requests to include any authorization in the headers, then use the ",(0,r.kt)("inlineCode",{parentName:"p"},"statusCheckHeaders")," property, as described in the ",(0,r.kt)("a",{parentName:"p",href:"/docs/status-indicators#setting-custom-headers"},"docs"),"."),(0,r.kt)("p",null,"If you are still having issues, it may be because your target application is blocking requests from Dashy's IP. This is a ",(0,r.kt)("a",{parentName:"p",href:"https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS"},"CORS error"),", and can be fixed by setting the headers on your target app, to include:"),(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre"},"Access-Control-Allow-Origin: https://location-of-dashy/\nVary: Origin\n")),(0,r.kt)("p",null,"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 ",(0,r.kt)("inlineCode",{parentName:"p"},"statusCheckAllowInsecure")," to true for a given item."),(0,r.kt)("p",null,"If you get an error, like ",(0,r.kt)("inlineCode",{parentName:"p"},"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 ",(0,r.kt)("inlineCode",{parentName:"p"},"https://")," (or whatever protocol) before the URL, and ensure that if needed, you've specified the port."),(0,r.kt)("p",null,"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 ",(0,r.kt)("inlineCode",{parentName:"p"},"statusCheckUrl")," to your custom page."),(0,r.kt)("p",null,"For further troubleshooting, use an application like ",(0,r.kt)("a",{parentName:"p",href:"https://postman.com"},"Postman")," to diagnose the issue. Set the parameter to ",(0,r.kt)("inlineCode",{parentName:"p"},"GET"),", and then make a call to: ",(0,r.kt)("inlineCode",{parentName:"p"},"https://[url-of-dashy]/status-check/?&url=[service-url]"),". Where the service URL must have first been encoded (e.g. with ",(0,r.kt)("inlineCode",{parentName:"p"},"encodeURIComponent()")," or ",(0,r.kt)("a",{parentName:"p",href:"https://www.urlencoder.io/"},"urlencoder.io"),")"),(0,r.kt)("p",null,"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. "),(0,r.kt)("hr",null),(0,r.kt)("h2",{id:"how-to-open-browser-console"},"How-To Open Browser Console"),(0,r.kt)("p",null,"When raising a bug, one crucial piece of info needed is the browser's console output. This will help the developer diagnose and fix the issue."),(0,r.kt)("p",null,'If you\'ve been asked for this info, but are unsure where to find it, then it is under the "Console" tab, in the browsers developer tools, which can be opened with ',(0,r.kt)("kbd",null,"F12"),". You can right-click the console, and select Save As to download the log."),(0,r.kt)("p",null,"To open dev tools, and jump straight to the console:"),(0,r.kt)("ul",null,(0,r.kt)("li",{parentName:"ul"},"Win / Linux: ",(0,r.kt)("kbd",null,"Ctrl")," + ",(0,r.kt)("kbd",null,"Shift")," + ",(0,r.kt)("kbd",null,"J")),(0,r.kt)("li",{parentName:"ul"},"MacOS: ",(0,r.kt)("kbd",null,"Cmd")," + ",(0,r.kt)("kbd",null,"Option")," + ",(0,r.kt)("kbd",null,"J"))),(0,r.kt)("p",null,"For more detailed walk through, see ",(0,r.kt)("a",{parentName:"p",href:"https://support.shortpoint.com/support/solutions/articles/1000222881-save-browser-console-file"},"this article"),"."),(0,r.kt)("hr",null),(0,r.kt)("h2",{id:"git-contributions-not-displaying"},"Git Contributions not Displaying"),(0,r.kt)("p",null,"If you've contributed to Dashy (or any other project), but your contributions are not showing up on your GH profile, or in Dashy's ",(0,r.kt)("a",{parentName:"p",href:"https://github.com/Lissy93/dashy/blob/master/docs/credits.md"},"Credits Page"),", then this is likely a git config issue."),(0,r.kt)("p",null,"These statistics are generated using the username / email associated with commits. This info needs to be setup on your local machine using ",(0,r.kt)("a",{parentName:"p",href:"https://git-scm.com/docs/git-config"},(0,r.kt)("inlineCode",{parentName:"a"},"git config")),"."),(0,r.kt)("p",null,"Run the following commands (replacing name + email with your info):"),(0,r.kt)("ul",null,(0,r.kt)("li",{parentName:"ul"},(0,r.kt)("inlineCode",{parentName:"li"},'git config --global user.name "John Doe"')),(0,r.kt)("li",{parentName:"ul"},(0,r.kt)("inlineCode",{parentName:"li"},"git config --global user.email johndoe@example.com"))),(0,r.kt)("p",null,"For more info, see ",(0,r.kt)("a",{parentName:"p",href:"https://git-scm.com/book/en/v2/Getting-Started-First-Time-Git-Setup"},"Git First Time Setup Docs"),"."),(0,r.kt)("p",null,"Note that only contributions to the master / main branch or a project are counted"))}p.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/9d9f8394.c03267c6.js b/assets/js/9d9f8394.c03267c6.js new file mode 100644 index 00000000..ad1fac48 --- /dev/null +++ b/assets/js/9d9f8394.c03267c6.js @@ -0,0 +1 @@ +"use strict";(self.webpackChunkdashy=self.webpackChunkdashy||[]).push([[360],{3905:function(e,t,n){n.d(t,{Zo:function(){return h},kt:function(){return c}});var o=n(7294);function r(e,t,n){return t in e?Object.defineProperty(e,t,{value:n,enumerable:!0,configurable:!0,writable:!0}):e[t]=n,e}function a(e,t){var n=Object.keys(e);if(Object.getOwnPropertySymbols){var o=Object.getOwnPropertySymbols(e);t&&(o=o.filter((function(t){return Object.getOwnPropertyDescriptor(e,t).enumerable}))),n.push.apply(n,o)}return n}function i(e){for(var t=1;t=0||(r[n]=e[n]);return r}(e,t);if(Object.getOwnPropertySymbols){var a=Object.getOwnPropertySymbols(e);for(o=0;o=0||Object.prototype.propertyIsEnumerable.call(e,n)&&(r[n]=e[n])}return r}var l=o.createContext({}),u=function(e){var t=o.useContext(l),n=t;return e&&(n="function"==typeof e?e(t):i(i({},t),e)),n},h=function(e){var t=u(e.components);return o.createElement(l.Provider,{value:t},e.children)},d={inlineCode:"code",wrapper:function(e){var t=e.children;return o.createElement(o.Fragment,{},t)}},p=o.forwardRef((function(e,t){var n=e.components,r=e.mdxType,a=e.originalType,l=e.parentName,h=s(e,["components","mdxType","originalType","parentName"]),p=u(n),c=r,m=p["".concat(l,".").concat(c)]||p[c]||d[c]||a;return n?o.createElement(m,i(i({ref:t},h),{},{components:n})):o.createElement(m,i({ref:t},h))}));function c(e,t){var n=arguments,r=t&&t.mdxType;if("string"==typeof e||r){var a=n.length,i=new Array(a);i[0]=p;var s={};for(var l in t)hasOwnProperty.call(t,l)&&(s[l]=t[l]);s.originalType=e,s.mdxType="string"==typeof e?e:r,i[1]=s;for(var u=2;uRefused to Connect in Modal or Workspace View",id:"refused-to-connect-in-modal-or-workspace-view",children:[{value:"NGINX",id:"nginx",children:[]},{value:"Caddy",id:"caddy",children:[]},{value:"Apache",id:"apache",children:[]}]},{value:"404 On Static Hosting",id:"404-on-static-hosting",children:[]},{value:"Yarn Error",id:"yarn-error",children:[]},{value:"Auth Validation Error: "should be object"",id:"auth-validation-error-should-be-object",children:[]},{value:"Config Not Updating",id:"config-not-updating",children:[]},{value:"Config Still not Updating",id:"config-still-not-updating",children:[]},{value:"Styles and Assets not Updating",id:"styles-and-assets-not-updating",children:[]},{value:"DockerHub toomanyrequests",id:"dockerhub-toomanyrequests",children:[]},{value:"Config Validation Errors",id:"config-validation-errors",children:[]},{value:"Node Sass does not yet support your current environment",id:"node-sass-does-not-yet-support-your-current-environment",children:[]},{value:"Error: Cannot find module './_baseValues'",id:"error-cannot-find-module-_basevalues",children:[]},{value:"Invalid Host Header while running through ngrok",id:"invalid-host-header-while-running-through-ngrok",children:[]},{value:"Warnings in the Console during deploy",id:"warnings-in-the-console-during-deploy",children:[]},{value:"Docker Login Fails on Ubuntu",id:"docker-login-fails-on-ubuntu",children:[]},{value:"Status Checks Failing",id:"status-checks-failing",children:[]},{value:"Widget Errors",id:"widget-errors",children:[]},{value:"Widget CORS Errors",id:"widget-cors-errors",children:[]},{value:"How-To Open Browser Console",id:"how-to-open-browser-console",children:[]},{value:"Git Contributions not Displaying",id:"git-contributions-not-displaying",children:[]}],d={toc:h};function p(e){var t=e.components,n=(0,r.Z)(e,i);return(0,a.kt)("wrapper",(0,o.Z)({},d,n,{components:t,mdxType:"MDXLayout"}),(0,a.kt)("h1",{id:"troubleshooting"},"Troubleshooting"),(0,a.kt)("blockquote",null,(0,a.kt)("p",{parentName:"blockquote"},(0,a.kt)("em",{parentName:"p"},(0,a.kt)("strong",{parentName:"em"},"This document contains common problems and their solutions."))),(0,a.kt)("p",{parentName:"blockquote"},(0,a.kt)("em",{parentName:"p"},"If you came across an issue where the solution was not immediately obvious, consider adding it to this list to help other users."))),(0,a.kt)("h3",{id:"contents"},"Contents"),(0,a.kt)("ul",null,(0,a.kt)("li",{parentName:"ul"},(0,a.kt)("a",{parentName:"li",href:"#refused-to-connect-in-modal-or-workspace-view"},"Refused to Connect in Web Content View")),(0,a.kt)("li",{parentName:"ul"},(0,a.kt)("a",{parentName:"li",href:"#404-on-static-hosting"},"404 On Static Hosting")),(0,a.kt)("li",{parentName:"ul"},(0,a.kt)("a",{parentName:"li",href:"#yarn-error"},"Yarn Build or Run Error")),(0,a.kt)("li",{parentName:"ul"},(0,a.kt)("a",{parentName:"li",href:"#auth-validation-error-should-be-object"},'Auth Validation Error: "should be object"')),(0,a.kt)("li",{parentName:"ul"},(0,a.kt)("a",{parentName:"li",href:"#config-not-updating"},"Config Not Updating")),(0,a.kt)("li",{parentName:"ul"},(0,a.kt)("a",{parentName:"li",href:"#config-still-not-updating"},"Config Still not Updating")),(0,a.kt)("li",{parentName:"ul"},(0,a.kt)("a",{parentName:"li",href:"#styles-and-assets-not-updating"},"Styles and Assets not Updating")),(0,a.kt)("li",{parentName:"ul"},(0,a.kt)("a",{parentName:"li",href:"#dockerhub-toomanyrequests"},"DockerHub toomanyrequests")),(0,a.kt)("li",{parentName:"ul"},(0,a.kt)("a",{parentName:"li",href:"#config-validation-errors"},"Config Validation Errors")),(0,a.kt)("li",{parentName:"ul"},(0,a.kt)("a",{parentName:"li",href:"#node-sass-does-not-yet-support-your-current-environment"},"Node Sass unsupported environment")),(0,a.kt)("li",{parentName:"ul"},(0,a.kt)("a",{parentName:"li",href:"#error-cannot-find-module-_basevalues"},"Cannot find module './_baseValues'")),(0,a.kt)("li",{parentName:"ul"},(0,a.kt)("a",{parentName:"li",href:"#invalid-host-header-while-running-through-ngrok"},"Ngrok Invalid Host Headers")),(0,a.kt)("li",{parentName:"ul"},(0,a.kt)("a",{parentName:"li",href:"#warnings-in-the-console-during-deploy"},"Warnings in the Console during deploy")),(0,a.kt)("li",{parentName:"ul"},(0,a.kt)("a",{parentName:"li",href:"#docker-login-fails-on-ubuntu"},"Docker Login Fails on Ubuntu")),(0,a.kt)("li",{parentName:"ul"},(0,a.kt)("a",{parentName:"li",href:"#status-checks-failing"},"Status Checks Failing")),(0,a.kt)("li",{parentName:"ul"},(0,a.kt)("a",{parentName:"li",href:"#widget-errors"},"Diagnosing Widget Errors")),(0,a.kt)("li",{parentName:"ul"},(0,a.kt)("a",{parentName:"li",href:"#widget-cors-errors"},"Fixing Widget CORS Errors")),(0,a.kt)("li",{parentName:"ul"},(0,a.kt)("a",{parentName:"li",href:"#how-to-open-browser-console"},"How-To Open Browser Console")),(0,a.kt)("li",{parentName:"ul"},(0,a.kt)("a",{parentName:"li",href:"#git-contributions-not-displaying"},"Git Contributions not Displaying"))),(0,a.kt)("hr",null),(0,a.kt)("h2",{id:"refused-to-connect-in-modal-or-workspace-view"},(0,a.kt)("inlineCode",{parentName:"h2"},"Refused to Connect")," in Modal or Workspace View"),(0,a.kt)("p",null,"This is not an issue with Dashy, but instead caused by the target app preventing direct access through embedded elements. It can be fixed by setting the ",(0,a.kt)("a",{parentName:"p",href:"https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Frame-Options"},(0,a.kt)("inlineCode",{parentName:"a"},"X-Frame-Options"))," HTTP header set to ",(0,a.kt)("inlineCode",{parentName:"p"},"ALLOW [path to Dashy]")," or ",(0,a.kt)("inlineCode",{parentName:"p"},"SAMEORIGIN"),", as defined in ",(0,a.kt)("a",{parentName:"p",href:"https://datatracker.ietf.org/doc/html/rfc7034"},"RFC-7034"),". These settings are usually set in the config file for the web server that's hosting the target application, here are some examples of how to enable cross-origin access with common web servers:"),(0,a.kt)("h3",{id:"nginx"},"NGINX"),(0,a.kt)("p",null,"In NGINX, you can use the ",(0,a.kt)("a",{parentName:"p",href:"https://nginx.org/en/docs/http/ngx_http_headers_module.html"},(0,a.kt)("inlineCode",{parentName:"a"},"add_header"))," module within the app block."),(0,a.kt)("pre",null,(0,a.kt)("code",{parentName:"pre"},"server {\n ...\n add_header X-Frame-Options SAMEORIGIN always;\n}\n")),(0,a.kt)("p",null,"Then reload with ",(0,a.kt)("inlineCode",{parentName:"p"},"service nginx reload")),(0,a.kt)("h3",{id:"caddy"},"Caddy"),(0,a.kt)("p",null,"In Caddy, you can use the ",(0,a.kt)("a",{parentName:"p",href:"https://caddyserver.com/docs/caddyfile/directives/header"},(0,a.kt)("inlineCode",{parentName:"a"},"header"))," directive."),(0,a.kt)("pre",null,(0,a.kt)("code",{parentName:"pre",className:"language-yaml"},"header {\n X-Frame-Options SAMEORIGIN\n}\n")),(0,a.kt)("h3",{id:"apache"},"Apache"),(0,a.kt)("p",null,"In Apache, you can use the ",(0,a.kt)("a",{parentName:"p",href:"https://httpd.apache.org/docs/current/mod/mod_headers.html"},(0,a.kt)("inlineCode",{parentName:"a"},"mod_headers"))," module to set the ",(0,a.kt)("inlineCode",{parentName:"p"},"X-Frame-Options")," in your config file. This file is usually located somewhere like `/etc/apache2/httpd.conf"),(0,a.kt)("pre",null,(0,a.kt)("code",{parentName:"pre"},'Header set X-Frame-Options: "ALLOW-FROM http://[dashy-location]/" \n')),(0,a.kt)("hr",null),(0,a.kt)("h2",{id:"404-on-static-hosting"},"404 On Static Hosting"),(0,a.kt)("p",null,"If you're seeing Dashy's 404 page on initial load/ refresh, and then the main app when you go back to Home, then this is likely caused by the Vue router, and if so can be fixed in one of two ways. "),(0,a.kt)("p",null,"The first solution is to switch the routing mode, from HTML5 ",(0,a.kt)("inlineCode",{parentName:"p"},"history")," mode to ",(0,a.kt)("inlineCode",{parentName:"p"},"hash")," mode, by setting ",(0,a.kt)("inlineCode",{parentName:"p"},"appConfig.routingMode")," to ",(0,a.kt)("inlineCode",{parentName:"p"},"hash"),"."),(0,a.kt)("p",null,"If this works, but you wish to continue using HTML5 history mode, then a bit of extra ",(0,a.kt)("a",{parentName:"p",href:"/docs/management#web-server-configuration"},"server configuration")," is required. This is explained in more detaail in the ",(0,a.kt)("a",{parentName:"p",href:"https://router.vuejs.org/guide/essentials/history-mode.html"},"Vue Docs"),". Once completed, you can then use ",(0,a.kt)("inlineCode",{parentName:"p"},"routingMode: history")," again, for neater URLs."),(0,a.kt)("hr",null),(0,a.kt)("h2",{id:"yarn-error"},"Yarn Error"),(0,a.kt)("p",null,"For more info, see ",(0,a.kt)("a",{parentName:"p",href:"https://github.com/Lissy93/dashy/issues/1"},"Issue #1")),(0,a.kt)("p",null,"First of all, check that you've got yarn installed correctly - see the ",(0,a.kt)("a",{parentName:"p",href:"https://classic.yarnpkg.com/en/docs/install"},"yarn installation docs")," for more info."),(0,a.kt)("p",null,"If you're getting an error about scenarios, then you've likely installed the wrong yarn... (you're ",(0,a.kt)("a",{parentName:"p",href:"https://github.com/yarnpkg/yarn/issues/2821"},"not")," the only one!). You can fix it by uninstalling, adding the correct repo, and reinstalling, for example, in Debian:"),(0,a.kt)("ul",null,(0,a.kt)("li",{parentName:"ul"},(0,a.kt)("inlineCode",{parentName:"li"},"sudo apt remove yarn")),(0,a.kt)("li",{parentName:"ul"},(0,a.kt)("inlineCode",{parentName:"li"},"curl -sS https://dl.yarnpkg.com/debian/pubkey.gpg | sudo apt-key add -")),(0,a.kt)("li",{parentName:"ul"},(0,a.kt)("inlineCode",{parentName:"li"},'echo "deb https://dl.yarnpkg.com/debian/ stable main" | sudo tee /etc/apt/sources.list.d/yarn.list')),(0,a.kt)("li",{parentName:"ul"},(0,a.kt)("inlineCode",{parentName:"li"},"sudo apt update && sudo apt install yarn"))),(0,a.kt)("p",null,"Alternatively, as a workaround, you have several options:"),(0,a.kt)("ul",null,(0,a.kt)("li",{parentName:"ul"},"Try using ",(0,a.kt)("a",{parentName:"li",href:"https://www.npmjs.com/get-npm"},"NPM")," instead: So clone, cd, then run ",(0,a.kt)("inlineCode",{parentName:"li"},"npm install"),", ",(0,a.kt)("inlineCode",{parentName:"li"},"npm run build")," and ",(0,a.kt)("inlineCode",{parentName:"li"},"npm start")),(0,a.kt)("li",{parentName:"ul"},"Try using ",(0,a.kt)("a",{parentName:"li",href:"https://www.docker.com/get-started"},"Docker")," instead, and all of the system setup and dependencies will already be taken care of. So from within the directory, just run ",(0,a.kt)("inlineCode",{parentName:"li"},"docker build -t lissy93/dashy .")," to build, and then use docker start to run the project, e.g: ",(0,a.kt)("inlineCode",{parentName:"li"},"docker run -it -p 8080:80 lissy93/dashy")," (see the ",(0,a.kt)("a",{parentName:"li",href:"https://github.com/Lissy93/dashy/blob/master/docs/deployment.md#deploy-with-docker"},"deploying docs")," for more info)")),(0,a.kt)("hr",null),(0,a.kt)("h2",{id:"auth-validation-error-should-be-object"},'Auth Validation Error: "should be object"'),(0,a.kt)("p",null,"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 ",(0,a.kt)("inlineCode",{parentName:"p"},"appConfig.auth")," object is now an object, which has a ",(0,a.kt)("inlineCode",{parentName:"p"},"users")," property."),(0,a.kt)("p",null,"For more info, see ",(0,a.kt)("a",{parentName:"p",href:"https://github.com/Lissy93/dashy/discussions/177"},"this announcement"),"."),(0,a.kt)("p",null,"You can fix this by replacing:"),(0,a.kt)("pre",null,(0,a.kt)("code",{parentName:"pre",className:"language-yaml"},"auth:\n- user: xxx\n hash: xxx\n")),(0,a.kt)("p",null,"with"),(0,a.kt)("pre",null,(0,a.kt)("code",{parentName:"pre",className:"language-yaml"},"auth:\n users:\n - user: xxx\n hash: xxx\n")),(0,a.kt)("hr",null),(0,a.kt)("h2",{id:"config-not-updating"},"Config Not Updating"),(0,a.kt)("p",null,'Dashy has the option to save settings and config locally, in browser storage. Anything here will take precedence over whatever is in your config file, sometimes with unintended consequences. If you\'ve updated the config file manually, and are not seeing changes reflected in the UI, then try visiting the site in Incognito mode. If that works, then the solution is just to clear local storage. This can be done from the config menu, under "Clear Local Settings".'),(0,a.kt)("hr",null),(0,a.kt)("h2",{id:"config-still-not-updating"},"Config Still not Updating"),(0,a.kt)("p",null,"Sometimes your text editor updates files ",(0,a.kt)("a",{parentName:"p",href:"https://linuxhandbook.com/inode-linux/"},"inode"),", meaning changes will not be picked up by the Docker container. This ",(0,a.kt)("a",{parentName:"p",href:"https://medium.com/@jonsbun/why-need-to-be-careful-when-mounting-single-files-into-a-docker-container-4f929340834"},"article")," explains things further."),(0,a.kt)("hr",null),(0,a.kt)("h2",{id:"styles-and-assets-not-updating"},"Styles and Assets not Updating"),(0,a.kt)("p",null,"If you find that your styles and other visual assets work when visiting ",(0,a.kt)("inlineCode",{parentName:"p"},"ip:port")," by not ",(0,a.kt)("inlineCode",{parentName:"p"},"dashy.domain.com"),", then this is usually caused by caching. In your browser, do a hard-refresh (",(0,a.kt)("kbd",null,"Ctrl")," + ",(0,a.kt)("kbd",null,"F5"),"). If you use Cloudflare, then you can clear the cache through the management console, or set the cache level to Bypass for certain files, under the Rules tab."),(0,a.kt)("hr",null),(0,a.kt)("h2",{id:"dockerhub-toomanyrequests"},"DockerHub ",(0,a.kt)("inlineCode",{parentName:"h2"},"toomanyrequests")),(0,a.kt)("p",null,"This situation relates to error messages similar to one of the following, returned when pulling, updating or running the Docker container from Docker Hub."),(0,a.kt)("pre",null,(0,a.kt)("code",{parentName:"pre"},"Continuing execution. Pulling image lissy93/dashy:release-1.6.0 \nerror pulling image configuration: toomanyrequests\n")),(0,a.kt)("p",null,"or"),(0,a.kt)("pre",null,(0,a.kt)("code",{parentName:"pre"},"You have reached your pull rate limit. You may increase the limit by authenticating and upgrading: https://www.docker.com/increase-rate-limit\n")),(0,a.kt)("p",null,"When DockerHub returns one of these errors, or a ",(0,a.kt)("inlineCode",{parentName:"p"},"429")," status, that means you've hit your rate limit. This was ",(0,a.kt)("a",{parentName:"p",href:"https://www.docker.com/blog/scaling-docker-to-serve-millions-more-developers-network-egress/"},"introduced")," last year, and prevents unauthenticated or free users from running docker pull more than 100 times per 6 hours.\nYou can ",(0,a.kt)("a",{parentName:"p",href:"https://www.docker.com/blog/checking-your-current-docker-pull-rate-limits-and-status/"},"check your rate limit status")," by looking for the ",(0,a.kt)("inlineCode",{parentName:"p"},"ratelimit-remaining")," header in any DockerHub responses. "),(0,a.kt)("h4",{id:"solution-1---use-an-alternate-container-registry"},"Solution 1 - Use an alternate container registry"),(0,a.kt)("ul",null,(0,a.kt)("li",{parentName:"ul"},"Dashy is also availible through GHCR, which at present does not have any hard limits. Just use ",(0,a.kt)("inlineCode",{parentName:"li"},"docker pull ghcr.io/lissy93/dashy:latest")," to fetch the image"),(0,a.kt)("li",{parentName:"ul"},"You can also build the image from source, by cloning the repo, and running ",(0,a.kt)("inlineCode",{parentName:"li"},"docker build -t dashy .")," or use the pre-made docker compose")),(0,a.kt)("h4",{id:"solution-2---increase-your-rate-limits"},"Solution 2 - Increase your rate limits"),(0,a.kt)("ul",null,(0,a.kt)("li",{parentName:"ul"},"Logging in to DockerHub will increase your rate limit from 100 requests to 200 requests per 6 hour period"),(0,a.kt)("li",{parentName:"ul"},"Upgrading to a Pro for $5/month will increase your image requests to 5,000 per day, and any plans above have no rate limits"),(0,a.kt)("li",{parentName:"ul"},"Since rate limits are counted based on your IP address, proxying your requests, or using a VPN may work")),(0,a.kt)("hr",null),(0,a.kt)("h2",{id:"config-validation-errors"},"Config Validation Errors"),(0,a.kt)("p",null,"The configuration file is validated against ",(0,a.kt)("a",{parentName:"p",href:"https://github.com/Lissy93/dashy/blob/master/src/utils/ConfigSchema.json"},"Dashy's Schema")," using AJV."),(0,a.kt)("p",null,"First, check that your syntax is valid, using ",(0,a.kt)("a",{parentName:"p",href:"https://codebeautify.org/yaml-validator/"},"YAML Validator")," or ",(0,a.kt)("a",{parentName:"p",href:"https://codebeautify.org/jsonvalidator"},"JSON Validator"),". If the issue persists, then take a look at the ",(0,a.kt)("a",{parentName:"p",href:"https://github.com/Lissy93/dashy/blob/master/src/utils/ConfigSchema.json"},"schema"),", and verify that the field you are trying to add/ modify matches the required format. You can also use ",(0,a.kt)("a",{parentName:"p",href:"https://www.jsonschemavalidator.net/s/JFUj7X9J"},"this tool")," to validate your JSON config against the schema, or run ",(0,a.kt)("inlineCode",{parentName:"p"},"yarn validate-config"),"."),(0,a.kt)("p",null,"If you're trying to use a recently released feature, and are getting a warning, this is likely because you've not yet updated the the current latest version of Dashy."),(0,a.kt)("p",null,"If the issue still persists, you should raise an issue."),(0,a.kt)("hr",null),(0,a.kt)("h2",{id:"node-sass-does-not-yet-support-your-current-environment"},"Node Sass does not yet support your current environment"),(0,a.kt)("p",null,"Caused by node-sass's binaries being built for a for a different architecture\nTo fix this, just run: ",(0,a.kt)("inlineCode",{parentName:"p"},"yarn rebuild node-sass")),(0,a.kt)("hr",null),(0,a.kt)("h2",{id:"error-cannot-find-module-_basevalues"},"Error: Cannot find module './_baseValues'"),(0,a.kt)("p",null,"Clearing the cache should fix this: ",(0,a.kt)("inlineCode",{parentName:"p"},"yarn cache clean"),"\nIf the issue persists, remove (",(0,a.kt)("inlineCode",{parentName:"p"},"rm -rf node_modules\\ yarn.lock"),") and reinstall (",(0,a.kt)("inlineCode",{parentName:"p"},"yarn"),") node_modules"),(0,a.kt)("hr",null),(0,a.kt)("h2",{id:"invalid-host-header-while-running-through-ngrok"},"Invalid Host Header while running through ngrok"),(0,a.kt)("p",null,"Just add the ",(0,a.kt)("a",{parentName:"p",href:"https://ngrok.com/docs#http-host-header"},"-host-header")," flag, e.g. ",(0,a.kt)("inlineCode",{parentName:"p"},'ngrok http 8080 -host-header="localhost:8080"')),(0,a.kt)("hr",null),(0,a.kt)("h2",{id:"warnings-in-the-console-during-deploy"},"Warnings in the Console during deploy"),(0,a.kt)("p",null,"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."),(0,a.kt)("hr",null),(0,a.kt)("h2",{id:"docker-login-fails-on-ubuntu"},"Docker Login Fails on Ubuntu"),(0,a.kt)("p",null,"Run ",(0,a.kt)("inlineCode",{parentName:"p"},"sudo apt install gnupg2 pass && gpg2 -k")),(0,a.kt)("hr",null),(0,a.kt)("h2",{id:"status-checks-failing"},"Status Checks Failing"),(0,a.kt)("p",null,"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:"),(0,a.kt)("p",null,"If your service requires requests to include any authorization in the headers, then use the ",(0,a.kt)("inlineCode",{parentName:"p"},"statusCheckHeaders")," property, as described in the ",(0,a.kt)("a",{parentName:"p",href:"/docs/status-indicators#setting-custom-headers"},"docs"),"."),(0,a.kt)("p",null,"If you are still having issues, it may be because your target application is blocking requests from Dashy's IP. This is a ",(0,a.kt)("a",{parentName:"p",href:"https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS"},"CORS error"),", and can be fixed by setting the headers on your target app, to include:"),(0,a.kt)("pre",null,(0,a.kt)("code",{parentName:"pre"},"Access-Control-Allow-Origin: https://location-of-dashy/\nVary: Origin\n")),(0,a.kt)("p",null,"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 ",(0,a.kt)("inlineCode",{parentName:"p"},"statusCheckAllowInsecure")," to true for a given item."),(0,a.kt)("p",null,"If you get an error, like ",(0,a.kt)("inlineCode",{parentName:"p"},"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 ",(0,a.kt)("inlineCode",{parentName:"p"},"https://")," (or whatever protocol) before the URL, and ensure that if needed, you've specified the port."),(0,a.kt)("p",null,"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 ",(0,a.kt)("inlineCode",{parentName:"p"},"statusCheckUrl")," to your custom page."),(0,a.kt)("p",null,"For further troubleshooting, use an application like ",(0,a.kt)("a",{parentName:"p",href:"https://postman.com"},"Postman")," to diagnose the issue. Set the parameter to ",(0,a.kt)("inlineCode",{parentName:"p"},"GET"),", and then make a call to: ",(0,a.kt)("inlineCode",{parentName:"p"},"https://[url-of-dashy]/status-check/?&url=[service-url]"),". Where the service URL must have first been encoded (e.g. with ",(0,a.kt)("inlineCode",{parentName:"p"},"encodeURIComponent()")," or ",(0,a.kt)("a",{parentName:"p",href:"https://www.urlencoder.io/"},"urlencoder.io"),")"),(0,a.kt)("p",null,"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. "),(0,a.kt)("hr",null),(0,a.kt)("h2",{id:"widget-errors"},"Widget Errors"),(0,a.kt)("p",null,"If an error occurs when fetching or rendering results, you will see a short message in the UI. If that message doesn't addequatley explain the problem, then you can ",(0,a.kt)("a",{parentName:"p",href:"/docs/troubleshooting#how-to-open-browser-console"},"open the browser console")," to see more details."),(0,a.kt)("p",null,"Before proceeding, ensure that if the widget requires auth your API is correct, and for custom widgets, double check that the URL and protocol is correct."),(0,a.kt)("p",null,"If the console message mentions to corss-origin blocking, then this is a CORS error, see: ",(0,a.kt)("a",{parentName:"p",href:"#widget-cors-errors"},"Fixing Widget CORS Errors")),(0,a.kt)("p",null,"If you're able to, you can find more information about why the request may be failing in the Dev Tools under the Network tab, and you can ensure your endpoint is correct and working using a tool like Postman."),(0,a.kt)("hr",null),(0,a.kt)("h2",{id:"widget-cors-errors"},"Widget CORS Errors"),(0,a.kt)("p",null,"The most common widget issue is a CORS error. This is a browser security mechanism which prevents the client-side app (Dashy) from from accessing resources on a remote origin, without that server's explicit permission (e.g. with headers like Access-Control-Allow-Origin). See the MDN Docs for more info: ",(0,a.kt)("a",{parentName:"p",href:"https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS"},"Cross-Origin Resource Sharing"),"."),(0,a.kt)("p",null,"There are several ways to fix a CORS error:"),(0,a.kt)("h4",{id:"option-1---ensure-correct-protocol"},"Option 1 - Ensure Correct Protocol"),(0,a.kt)("p",null,"You will get a CORS error if you try and access a http service from a https source. So ensure that the URL you are requesting has the right protocol, and is correctly formatted."),(0,a.kt)("h4",{id:"option-2---set-headers"},"Option 2 - Set Headers"),(0,a.kt)("p",null,"If you have control over the destination (e.g. for a self-hosted service), then you can simply apply the correct headers.\nAdd the ",(0,a.kt)("inlineCode",{parentName:"p"},"Access-Control-Allow-Origin")," header, with the value of either ",(0,a.kt)("inlineCode",{parentName:"p"},"*")," to allow requests from anywhere, or more securely, the host of where Dashy is served from. For example:"),(0,a.kt)("pre",null,(0,a.kt)("code",{parentName:"pre"},"Access-Control-Allow-Origin: https://url-of-dashy.local\n")),(0,a.kt)("p",null,"or"),(0,a.kt)("pre",null,(0,a.kt)("code",{parentName:"pre"},"Access-Control-Allow-Origin: *\n")),(0,a.kt)("h4",{id:"option-3---proxying-request"},"Option 3 - Proxying Request"),(0,a.kt)("p",null,"You can route requests through Dashy's built-in CORS proxy. Instructions and more details can be found ",(0,a.kt)("a",{parentName:"p",href:"/docs/widgets#proxying-requests"},"here"),". 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."),(0,a.kt)("p",null,"Just add the ",(0,a.kt)("inlineCode",{parentName:"p"},"useProxy: true")," option to the failing widget."),(0,a.kt)("h4",{id:"option-4---use-a-plugin"},"Option 4 - Use a plugin"),(0,a.kt)("p",null,"For testing purposes, you can use an addon, which will disable the CORS checks. You can get the Allow-CORS extension for ",(0,a.kt)("a",{parentName:"p",href:"https://chrome.google.com/webstore/detail/allow-cors-access-control/lhobafahddgcelffkeicbaginigeejlf?hl=en-US"},"Chrome")," or ",(0,a.kt)("a",{parentName:"p",href:"https://addons.mozilla.org/en-US/firefox/addon/access-control-allow-origin/"},"Firefox"),", more details ",(0,a.kt)("a",{parentName:"p",href:"https://mybrowseraddon.com/access-control-allow-origin.html"},"here")),(0,a.kt)("hr",null),(0,a.kt)("h2",{id:"how-to-open-browser-console"},"How-To Open Browser Console"),(0,a.kt)("p",null,"When raising a bug, one crucial piece of info needed is the browser's console output. This will help the developer diagnose and fix the issue."),(0,a.kt)("p",null,'If you\'ve been asked for this info, but are unsure where to find it, then it is under the "Console" tab, in the browsers developer tools, which can be opened with ',(0,a.kt)("kbd",null,"F12"),". You can right-click the console, and select Save As to download the log."),(0,a.kt)("p",null,"To open dev tools, and jump straight to the console:"),(0,a.kt)("ul",null,(0,a.kt)("li",{parentName:"ul"},"Win / Linux: ",(0,a.kt)("kbd",null,"Ctrl")," + ",(0,a.kt)("kbd",null,"Shift")," + ",(0,a.kt)("kbd",null,"J")),(0,a.kt)("li",{parentName:"ul"},"MacOS: ",(0,a.kt)("kbd",null,"Cmd")," + ",(0,a.kt)("kbd",null,"Option")," + ",(0,a.kt)("kbd",null,"J"))),(0,a.kt)("p",null,"For more detailed walk through, see ",(0,a.kt)("a",{parentName:"p",href:"https://support.shortpoint.com/support/solutions/articles/1000222881-save-browser-console-file"},"this article"),"."),(0,a.kt)("hr",null),(0,a.kt)("h2",{id:"git-contributions-not-displaying"},"Git Contributions not Displaying"),(0,a.kt)("p",null,"If you've contributed to Dashy (or any other project), but your contributions are not showing up on your GH profile, or in Dashy's ",(0,a.kt)("a",{parentName:"p",href:"https://github.com/Lissy93/dashy/blob/master/docs/credits.md"},"Credits Page"),", then this is likely a git config issue."),(0,a.kt)("p",null,"These statistics are generated using the username / email associated with commits. This info needs to be setup on your local machine using ",(0,a.kt)("a",{parentName:"p",href:"https://git-scm.com/docs/git-config"},(0,a.kt)("inlineCode",{parentName:"a"},"git config")),"."),(0,a.kt)("p",null,"Run the following commands (replacing name + email with your info):"),(0,a.kt)("ul",null,(0,a.kt)("li",{parentName:"ul"},(0,a.kt)("inlineCode",{parentName:"li"},'git config --global user.name "John Doe"')),(0,a.kt)("li",{parentName:"ul"},(0,a.kt)("inlineCode",{parentName:"li"},"git config --global user.email johndoe@example.com"))),(0,a.kt)("p",null,"For more info, see ",(0,a.kt)("a",{parentName:"p",href:"https://git-scm.com/book/en/v2/Getting-Started-First-Time-Git-Setup"},"Git First Time Setup Docs"),"."),(0,a.kt)("p",null,"Note that only contributions to the master / main branch or a project are counted"))}p.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/runtime~main.cf68debf.js b/assets/js/runtime~main.d6586337.js similarity index 97% rename from assets/js/runtime~main.cf68debf.js rename to assets/js/runtime~main.d6586337.js index abf1d645..5c4f30e5 100644 --- a/assets/js/runtime~main.cf68debf.js +++ b/assets/js/runtime~main.d6586337.js @@ -1 +1 @@ -!function(){"use strict";var e,t,n,r,f,a={},o={};function c(e){var t=o[e];if(void 0!==t)return t.exports;var n=o[e]={id:e,loaded:!1,exports:{}};return a[e].call(n.exports,n,n.exports,c),n.loaded=!0,n.exports}c.m=a,c.c=o,e=[],c.O=function(t,n,r,f){if(!n){var a=1/0;for(i=0;i=f)&&Object.keys(c.O).every((function(e){return c.O[e](n[d])}))?n.splice(d--,1):(o=!1,f0&&e[i-1][2]>f;i--)e[i]=e[i-1];e[i]=[n,r,f]},c.n=function(e){var t=e&&e.__esModule?function(){return e.default}:function(){return e};return c.d(t,{a:t}),t},n=Object.getPrototypeOf?function(e){return Object.getPrototypeOf(e)}:function(e){return e.__proto__},c.t=function(e,r){if(1&r&&(e=this(e)),8&r)return e;if("object"==typeof e&&e){if(4&r&&e.__esModule)return e;if(16&r&&"function"==typeof e.then)return e}var f=Object.create(null);c.r(f);var a={};t=t||[null,n({}),n([]),n(n)];for(var o=2&r&&e;"object"==typeof o&&!~t.indexOf(o);o=n(o))Object.getOwnPropertyNames(o).forEach((function(t){a[t]=function(){return e[t]}}));return a.default=function(){return e},c.d(f,a),f},c.d=function(e,t){for(var n in t)c.o(t,n)&&!c.o(e,n)&&Object.defineProperty(e,n,{enumerable:!0,get:t[n]})},c.f={},c.e=function(e){return Promise.all(Object.keys(c.f).reduce((function(t,n){return c.f[n](e,t),t}),[]))},c.u=function(e){return"assets/js/"+({12:"52e2a80b",34:"9beb87c2",53:"935f2afb",80:"4d54d076",85:"1f391b9e",107:"ffd4f506",118:"f62d4472",120:"e505b3a5",168:"625b1ed7",171:"87124b4e",195:"c4f5d8e4",210:"ccab7630",221:"044d5aa6",239:"72e14192",316:"27d9d47d",352:"dea0f9ea",357:"25b7c3f2",360:"9d9f8394",414:"393be207",478:"1745c531",514:"1be78505",529:"ac5280f2",657:"18ba09e8",698:"9be9f402",714:"a63906ba",720:"a3713279",723:"0bfe2fe2",733:"1f5fb0df",775:"9b4185c1",781:"4bdb0d83",783:"68d50eef",800:"f52ebc2d",862:"f9f76190",865:"0276dc25",918:"17896441"}[e]||e)+"."+{12:"e50bbeab",34:"a6d8d871",40:"9e646974",53:"302a95d7",80:"6185bde3",85:"da34fa01",107:"ecb4ebc3",118:"a60b3802",120:"40785d16",168:"b270f754",171:"8ad3ceb4",195:"720df820",210:"a1e110fc",221:"314ea394",239:"d63fde4d",316:"473a50c8",352:"246552aa",357:"3488232d",360:"b33b7b16",402:"fe9687eb",414:"801e6b4e",478:"fce35f14",486:"018ae290",514:"a984814b",529:"06f97284",598:"f0fc4f25",608:"ef4abb81",657:"689f5477",698:"b22b6751",714:"966129bf",720:"b7e28823",723:"567fec0a",733:"e4b5b1ab",775:"c8ecaecc",781:"cb9d0015",783:"7b350d23",800:"914a4eb6",849:"2cf00947",862:"b7918a52",865:"2a6d588e",918:"a1a52f63",945:"20a8d61e"}[e]+".js"},c.miniCssF=function(e){return"assets/css/styles.de19e965.css"},c.g=function(){if("object"==typeof globalThis)return globalThis;try{return this||new Function("return this")()}catch(e){if("object"==typeof window)return window}}(),c.o=function(e,t){return Object.prototype.hasOwnProperty.call(e,t)},r={},f="dashy:",c.l=function(e,t,n,a){if(r[e])r[e].push(t);else{var o,d;if(void 0!==n)for(var u=document.getElementsByTagName("script"),i=0;i=f)&&Object.keys(c.O).every((function(e){return c.O[e](n[d])}))?n.splice(d--,1):(o=!1,f0&&e[i-1][2]>f;i--)e[i]=e[i-1];e[i]=[n,r,f]},c.n=function(e){var t=e&&e.__esModule?function(){return e.default}:function(){return e};return c.d(t,{a:t}),t},n=Object.getPrototypeOf?function(e){return Object.getPrototypeOf(e)}:function(e){return e.__proto__},c.t=function(e,r){if(1&r&&(e=this(e)),8&r)return e;if("object"==typeof e&&e){if(4&r&&e.__esModule)return e;if(16&r&&"function"==typeof e.then)return e}var f=Object.create(null);c.r(f);var a={};t=t||[null,n({}),n([]),n(n)];for(var o=2&r&&e;"object"==typeof o&&!~t.indexOf(o);o=n(o))Object.getOwnPropertyNames(o).forEach((function(t){a[t]=function(){return e[t]}}));return a.default=function(){return e},c.d(f,a),f},c.d=function(e,t){for(var n in t)c.o(t,n)&&!c.o(e,n)&&Object.defineProperty(e,n,{enumerable:!0,get:t[n]})},c.f={},c.e=function(e){return Promise.all(Object.keys(c.f).reduce((function(t,n){return c.f[n](e,t),t}),[]))},c.u=function(e){return"assets/js/"+({12:"52e2a80b",34:"9beb87c2",53:"935f2afb",80:"4d54d076",85:"1f391b9e",107:"ffd4f506",118:"f62d4472",120:"e505b3a5",168:"625b1ed7",171:"87124b4e",195:"c4f5d8e4",210:"ccab7630",221:"044d5aa6",239:"72e14192",316:"27d9d47d",352:"dea0f9ea",357:"25b7c3f2",360:"9d9f8394",414:"393be207",478:"1745c531",514:"1be78505",529:"ac5280f2",657:"18ba09e8",698:"9be9f402",714:"a63906ba",720:"a3713279",723:"0bfe2fe2",733:"1f5fb0df",775:"9b4185c1",781:"4bdb0d83",783:"68d50eef",800:"f52ebc2d",862:"f9f76190",865:"0276dc25",918:"17896441"}[e]||e)+"."+{12:"e50bbeab",34:"a6d8d871",40:"9e646974",53:"302a95d7",80:"6185bde3",85:"da34fa01",107:"ecb4ebc3",118:"a60b3802",120:"40785d16",168:"b270f754",171:"8ad3ceb4",195:"720df820",210:"a1e110fc",221:"314ea394",239:"d63fde4d",316:"473a50c8",352:"246552aa",357:"3488232d",360:"c03267c6",402:"fe9687eb",414:"801e6b4e",478:"fce35f14",486:"018ae290",514:"a984814b",529:"06f97284",598:"f0fc4f25",608:"ef4abb81",657:"689f5477",698:"1e6e9a05",714:"966129bf",720:"b7e28823",723:"567fec0a",733:"e4b5b1ab",775:"c8ecaecc",781:"cb9d0015",783:"7b350d23",800:"914a4eb6",849:"2cf00947",862:"b7918a52",865:"2a6d588e",918:"a1a52f63",945:"20a8d61e"}[e]+".js"},c.miniCssF=function(e){return"assets/css/styles.de19e965.css"},c.g=function(){if("object"==typeof globalThis)return globalThis;try{return this||new Function("return this")()}catch(e){if("object"==typeof window)return window}}(),c.o=function(e,t){return Object.prototype.hasOwnProperty.call(e,t)},r={},f="dashy:",c.l=function(e,t,n,a){if(r[e])r[e].push(t);else{var o,d;if(void 0!==n)for(var u=document.getElementsByTagName("script"),i=0;i Alternate Views & Opening Methods | Dashy - +

Alternate Views & Opening Methods

Views#

Dashy has three different views:

  • Default View - This is the main homepage with sections in a grid layout
  • Workspace View - Items displayed on the side, and are launched within Dashy
  • Minimal View - A clean + simple tabbed view

You can switch between views using the dropdown in the top-right corner. Set your chosen Starting View with appConfig.startingView. Click the page title at any time to go back to your selected starting view.

Default#

This is the main page that you will land on when you first launch the application. Here all of your sections (with items + widgets) are visible in a grid layout.

Example of Default View
Demo

Workspace#

The workspace view displays your links in a sidebar on the left-hand side, and apps are launched inside an iframe without having to leave Dashy. This enables you to use all of your self-hosted apps from one place, and makes multi-tasking easy.

You can specify a default app to be opened when you land on the workspace, by setting appConfig.workspaceLandingUrl: https://app-to-open/. If this app exists within your sections.items, then the corresponding section will also be expanded.

You can also opt to keep previously opened websites/ apps open in the background, by setting appConfig.enableMultiTasking: true. This comes at the cost of performance, but does mean that your session with each app is preserved, enabling you to quickly switch between them.

Example of Workspace View
Workspace view demo

Minimal View#

The minimal view aims to be super fast and simple, and can be used as a browser startpage. Items are grouped into a tab view, and the last opened tab will be remembered. Similar to the main view, you can search and launch items just by typing, and right-clicking will show more options (like open in modal, workspace or new tab).

Example of Minimal View
Workspace view demo

Opening Methods#

Dashy supports several different ways to launch your apps. The primary opening method for each app can be specified using the target attribute, with a value of one of the following:

  • sametab - The app will be launched in the current tab
  • newtab - The app will be launched in a new tab
  • top - Opens in the top-most browsing context, useful if your accessing Dashy through an iframe
  • modal - Launch app in a resizable/ movable popup modal on the current page
  • workspace - Changes to Workspace view, and launches app

You can also set a default opening method, which will be applied to all items that don't have a specified target, using appConfig.defaultOpeningMethod, to one of the above values.

Even if the target is not set (or is set to sametab), you can still launch any given app in an alternative method. Either right-click to see all options, or use one of the keyboard shortcuts: Alt + Click will open the modal, and Ctrl + Click will open in a new tab.

If you don't like the custom context menu, it can be disabled by setting appConfig.disableContextMenu: true.

If you get a 'Refused to Connect' error in the modal or workspace views, then the target app has it's X-Frame-Options HTTP set to block requests from embedded content. You can easily fix this by setting this header to ALLOW, for instructions on how to do so, see the Troubleshooting Docs.

- + \ No newline at end of file diff --git a/docs/authentication/index.html b/docs/authentication/index.html index 35133e88..24410a14 100644 --- a/docs/authentication/index.html +++ b/docs/authentication/index.html @@ -5,7 +5,7 @@ Authentication | Dashy - + @@ -17,7 +17,7 @@ Keycloak server administration and configuration is a deep topic; please refer t Once you have groups or roles assigned to users you can configure access under each sections 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.

sections:  - name: DeveloperResources    displayData:      showForKeycloakUsers:        roles: ['canViewDevResources']      hideForKeycloakUsers:        groups: ['ProductTeam']

Your app is now secured :) When you load Dashy, it will redirect to your Keycloak login page, and any user without valid credentials will be prevented from accessing your dashboard.

From within the Keycloak console, you can then configure things like time-outs, password policies, etc. You can also backup your full Keycloak config, and it is recommended to do this, along with your Dashy config. You can spin up both Dashy and Keycloak simultaneously and restore both applications configs using a docker-compose.yml file, and this is recommended.

Alternative Authentication Methods#

If you are self-hosting Dashy, and require secure authentication to prevent unauthorized access, then you can either use Keycloak, or one of the following options:

Authentication Server#

Authelia#

Authelia is an open-source full-featured authentication server, which can be self-hosted and either on bare metal, in a Docker container or in a Kubernetes cluster. It allows for fine-grained access control rules based on IP, path, users etc, and supports 2FA, simple password access or bypass policies for your domains.

  • git clone https://github.com/authelia/authelia.git
  • cd authelia/examples/compose/lite
  • Modify the users_database.yml the default username and password is authelia
  • Modify the configuration.yml and docker-compose.yml with your respective domains and secrets
  • docker-compose up -d

For more information, see the Authelia docs

VPN#

A catch-all solution to accessing services running from your home network remotely is to use a VPN. It means you do not need to worry about implementing complex authentication rules, or trusting the login implementation of individual applications. However it can be inconvenient to use on a day-to-day basis, and some public and corporate WiFi block VPN connections. Two popular VPN protocols are OpenVPN and WireGuard

IP-Based Access#

If you have a static IP or use a VPN to access your running services, then you can use conditional access to block access to Dashy from everyone except users of your pre-defined IP address. This feature is offered by most cloud providers, and supported by most web servers.

Apache#

In Apache, this is configured in your .htaccess file in Dashy's root folder, and should look something like:

Order Deny,AllowDeny from allAllow from [your-ip]
NGINX#

In NGINX you can specify control access rules for a given site in your nginx.conf or hosts file. For example:

server {    listen 80;    server_name www.dashy.example.com;    location / {        root /path/to/dashy/;        passenger_enabled on;        allow [your-ip];        deny all;    }  }
Caddy#

In Caddy, Request Matchers can be used to filter requests 

dashy.site {    @public_networks not remote_ip [your-ip]    respond @public_networks "Access denied" 403}

Web Server Authentication#

Most web servers make password protecting certain apps very easy. Note that you should also set up HTTPS and have a valid certificate in order for this to be secure.

Apache#

First crate a .htaccess file in Dashy's route directory. Specify the auth type and path to where you want to store the password file (usually the same folder). For example:

AuthType Basic  AuthName "Please Sign into Dashy"  AuthUserFile /path/dashy/.htpasswd  require valid-user

Then create a .htpasswd file in the same directory. List users and their hashed passwords here, with one user on each line, and a colon between username and password (e.g. [username]:[hashed-password]). You will need to generate an MD5 hash of your desired password, this can be done with an online tool. Your file will look something like:

alicia:$apr1$jv0spemw$RzOX5/GgY69JMkgV6u16l0
NGINX#

NGINX has an authentication module which can be used to add passwords to given sites, and is fairly simple to set up. Similar to above, you will need to create a .htpasswd file. Then just enable auth and specify the path to that file, for example:

location / {  auth_basic "closed site";  auth_basic_user_file conf/htpasswd;}
Caddy#

Caddy has a basic-auth directive, where you specify a username and hash. The password hash needs to be base-64 encoded, the caddy hash-password command can help with this. For example:

basicauth /secret/* {    alicia JDJhJDEwJEVCNmdaNEg2Ti5iejRMYkF3MFZhZ3VtV3E1SzBWZEZ5Q3VWc0tzOEJwZE9TaFlZdEVkZDhX}

For more info about implementing a single sign on for all your apps with Caddy, see this tutorial

Lighttpd#

You can use the mod_auth module to secure your site with Lighttpd. Like with Apache, you need to first create a password file listing your usersnames and hashed passwords, but in Lighttpd, it's usually called .lighttpdpassword.

Then in your lighttpd.conf file (usually in the /etc/lighttpd/ directory), load in the mod_auth module, and configure it's directives. For example:

server.modules += ( "mod_auth" )auth.debug = 2auth.backend = "plain"auth.backend.plain.userfile = "/home/lighttpd/.lighttpdpassword"
 $HTTP["host"] == "dashy.my-domain.net" {  server.document-root = "/home/lighttpd/dashy.my-domain.net/http"  server.errorlog = "/var/log/lighttpd/dashy.my-domain.net/error.log"  accesslog.filename = "/var/log/lighttpd/dashy.my-domain.net/access.log"  auth.require = (    "/docs/" => (      "method" => "basic",      "realm" => "Password protected area",      "require" => "user=alicia"    )  )}

Restart your web server for changes to take effect.

OAuth Services#

There are also authentication services, such as Ory.sh, Okta, Auth0, Firebase. Implementing one of these solutions would involve some changes to the Auth.js file, but should be fairly straight forward.

Static Site Hosting Providers#

If you are hosting Dashy on a cloud platform, you will probably find that it has built-in support for password protected access to web apps. For more info, see the relevant docs for your provider, for example: Netlify Password Protection, Cloudflare Access, AWS Cognito, Azure Authentication and Vercel Password Protection.

⬆️ Back to Top

- + \ No newline at end of file diff --git a/docs/backup-restore/index.html b/docs/backup-restore/index.html index 3d654f33..983095ca 100644 --- a/docs/backup-restore/index.html +++ b/docs/backup-restore/index.html @@ -5,7 +5,7 @@ Cloud Backup and Restore | Dashy - + @@ -14,7 +14,7 @@ workers_dev = trueroute = "example.com/*"zone_id = "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"account_id = "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" kv_namespaces = [ { binding = "DASHY_CLOUD_BACKUP", id = "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" }]

Complete index.js#

  • Write code to handle your requests, and interact with any other data sources in this file
  • Generally, this is done within an event listener for 'fetch', and returns a promise
    • For Example:
addEventListener('fetch', event => {  event.respondWith(handleRequest(event.request))})
 async function handleRequest(request) {  return new Response('Hello World!', {    headers: { 'content-type': 'text/plain' },  })}
  • For the code used for Dashy's cloud service, see here

Commands#

  • wrangler dev - To start the wrangler development server
  • wrangler publish - To publish to your cloudflare account (first run wrangler login)

API#

There are four endpoints, and to keep things simple, they all use the same base URL/ route.

  • GET - Get config for a given user
    • backupId - The ID of the desired encrypted object
    • subHash - The latter half of the password hash, to verify ownership
  • POST - Save a new config object, and returns backupId
    • userData - The encrypted, compressed and stringified user config
    • subHash - The latter half of the password hash, to verify ownership
  • PUT - Update an existing config object
    • backupId - The ID of the object to update
    • subHash - Part of the hash, to verify ownership of said object
    • userData - The new data to store
  • DELETE - Delete a specified config object
    • backupId - The ID of the object to be deleted
    • subHash - Part of the password hash, to verify ownership of the object

For more info, see the API Docs.

If you are using Postman, you may find this pre-made collection helpful in getting things setup.

- + \ No newline at end of file diff --git a/docs/changelog/index.html b/docs/changelog/index.html index f4cd1ee5..4df8461a 100644 --- a/docs/changelog/index.html +++ b/docs/changelog/index.html @@ -5,13 +5,13 @@ Changelog | Dashy - +

Changelog

⚡️ 1.8.3 - Improved UX for Initial Load PR #238#

  • Removes the old splash screen
  • Adds placeholder in the HTML index, which will usually be visible on initial load
  • Show progress bar on route switcher

✨ 1.8.2 - Serverless Functions for Netlify Instances PR #235#

  • Previously when Dashy was deployed as a static site to Netlify, it was not possible to use several features, which required server-side code
  • This PR adds serverless cloud functions to provide most of this functionality

🩹 1.8.1 - Additional Languages, Bug Fix, and more PR #234#

  • Merges 5 additional languages
  • Adds RickyCZ's dashboard to showcase
  • Fixes #323, and improves status indicator tooltip
  • Define constants for endpoints
  • Updates management, translations and readme docs

⚡️ 1.7.7 - Improved Error Handling PR #226#

  • Errors can be viewed via the UI (Config menu --> App Info)
  • Service workers should be disabled by default
  • Also renames actions to be easier to maintain
  • Updates docs to include release schedule + merge strategy

✨ 1.7.6 - Adds Multi-Search Support with Bangs PR #224#

  • Adds option for user to add custom search bangs, in order to specify search engine/ target app. Re: #206

🎨 1.7.5 - Improved Language Detection & UI PR #223#

  • Makes the auto language detection algo smarter
  • Improves responsiveness for the language selector form

🌐 1.7.4 - Adds Spanish Translations PR #222#

  • Adds Spanish language file, contributed by @lu4t

👷 1.7.3 - CI with GH Actions PR #212#

  • Adds a series of GH actions for repository maintenance and administration
  • Auto-labels PR and issues, adds helpful info to PRs based on files changed
  • Lints, tests, builds and deploys the app when PR submitted
  • Checks app size, dependencies, security, accessibility etc when PR submitted
  • Closes incomplete, stale or spammy issues and leaves a comment

✨ 1.7.2 - Item Sort Options PR #203#

  • Adds option for user to specify sortBy to order items within a section
  • Can sort by last clicked, most used, alphabetically and more
  • And fixes UI of the item tooltip and, if specified, will show Provider in the tooltip
  • Also improves error logging and console warning message

🐛 1.7.1 - Lots of Tiny Fixes and Improvements PR #200#

  • Removes background in console art
  • Updates auto environmental variables
  • Icon image assets max height Force same Icon/Item Height #200
  • Adds an action to close spammy issues
  • Adds option to enable SRI integrity, plus refactos PWA into defaults
  • Updates privacy and security docs
  • Adds option for different favicon API for each app [FEATURE_REQUEST] Allow using different faviconApi for each items #196
  • Fixes loading of local SVG icons #199

🍻 1.7.0 - Documentation Website PR #190#

  • Builds a quick website to host the docs. No code changes, but prepares for V1.7 release

✨ 1.6.9 - Web Search Feature PR #185#

  • Adds ability to search the web directly from Dashy by pressing enter on the search bar
  • Adds configuration options, for setting default search engine, opening method and disabling
  • Adds text under search bar, implements into minimal view also

⚡️ 1.6.8 - Improved Loading Experience PR #183#

  • During app initialization, show the build progress and status message
  • While requests are being made, show loader at top of screen
  • Also adds some UI improvements to Workspace view

⚡️ 1.6.7 - Option for non-SSL status checks plus minor things PR #182#

  • Adds an option for user to use status checks with non-HTTPS services, Re: #181
  • Updates the .env template, plus the variables used in the server
  • Uses the v-cloak to hide text before it's finished loading
  • Fixed the parsing of the update-checker during build

⚡️ 1.6.6 - Improved Search & Shortcuts PR #175#

  • Refactors the search algorithm to improve performance and code reusability
  • Updates search to ignore case, special characters and minor-typos
  • Adds the option for user to specify tags, which can be used for searching

✨ 1.6.5 - Adds support for Secure Authentication using Keycloak PR #174#

  • Major restructure of auth config
  • Implements keycloak support, adds docs and updates schema

✨ 1.6.4 - Adds functionality for Granular Auth Control PR #171#

  • Enables sections to be visible for all users except for those specified
  • Enables sections to be hidden from all users except for those specified
  • Enables sections to be hidden from guests, but visible to all authenticated users

⚡️ 1.6.3 - Dependency and Build File Updates PR #168#

  • Removes any dependencies which are not 100% essential
  • Moves packages that are only used for building into devDependencies
  • Updates dependencies to latest version
  • Adds a .dockerignore, so that non-essential files are not included in the container
  • Updates deployment config files for Netlify, Heroku and GH actions
  • Made a brand new bug-report template, with input fields and validation!

✨ 1.6.2 - Support for Guest Access PR #167#

  • Adds functionality for optional read-only guest access to dashboards with authentication
  • Can be enabled by setting appConfig.enableGuestAccess: true

💄 1.6.1 - Adds new Theme PR #166#

  • Adds Dashy theme, for use in the dev dashboard

✨ 1.5.9 - New Minimal/ Startpage View PR #155#

  • Adds a new view, called minimal view, designed to be like a light-weight startpage
  • Implemented all the required features (filtering, opening methods, icons, etc) into minimal view
  • Adds appConfig.startingView into schema, for specifying the initial default view to be loaded

✨ 1.5.8 - Multi-Tasking Support in Workspace View PR #146#

  • Adds option to keep launched apps open in the background, to reduce friction when switching between websites, Re: #144
  • This can be enabled by setting appConfig.enableMultiTasking: true
  • Note that having many apps opened simultaneously, will have an impact on performance

✨ 1.5.7 - Adds Support for Material Design Icons PR #141#

⚡️ 1.5.6 - Refactor + Couple of small things PR #135#

  • The main Dockerfile now uses yarn.lock instead of package-lock.json
  • Adds a check to verify password is not empty in cloud backup screen
  • Improves responsiveness of config modals for mobile devices
  • Enables the user to use their own self-hosted Sentry instance
  • Removes the View Config tab of the Config menu, as not needed
  • Updates and fixes some typos in the readme

🌐 1.5.5 - Adds Missing Translations + Small UI Issues PR #129#

  • Adds missing translations to several UI elements, Re: #126
  • Fixes login translations not being picked up on page load, Re: #127
  • Fixes small text overflow glitch in config icon, Re: #123
  • Several small UI improvements: height of config editor, scrollbar on theme dropdown, page height, white-on-white on material theme, etc
  • Adds an action to auto-assign reviewer based on ./.github/CODEOWNERS file

🐳 1.5.4 - Docker ARM Support PR #122#

  • Adds a Dockerfile for arm64v8 and arm32v7, to support Raspberry Pi and other modern ARM-based devices
  • Sets up automated workflow to publish ARM containers to DockerHub after every new release
  • Adds documentation for running Dashy on RPi/ ARM-based devices, Re: #117

🩹 1.5.3 - UI Quick Fix PR #121#

  • Downgrades and pins vue-material-tabs to 0.1.5, to prevent breaking changes. Fixes #118 p1
  • Sets auto-width for theme selector, so text doesn't wrap for long theme names. Fixes #119
  • Uses flex layout for config menu, so note doesn't overlap menu on small screens. Fixes #118 p2

🌐 1.5.2 - Adds Dutch Translations PR #120#

  • Dutch language support, contributed by @evroon

🩹 1.5.1 - UI Quick Fix PR #116#

  • Uses min-max width parent layout, to prevent longer languages (e.g. French) text overflow. Fixes #115

🔒 1.5.0 - Improve Robustness of Auth PR #113#

  • Use both username + password for generating token, so that a change in either will log the user out
  • Prevent privilege escalation by disallowing a user from modifying their user type through the UI
  • Improve the isAuthenticated check, by taking account of empty users array

✨ 1.4.8 - Optional Crash Reports PR #112#

  • Adds an optional, off by default method of getting crash reports
  • This can be enabled in appConfig.enableErrorReporting, and will not be used at all unless explicitly activated by user
  • This is needed for when a user raises a bug which is hard to fix
  • Also improves robustness of config accumulator, don't throw error when config is missing
  • Adds Privacy & Security docs

♻️ 1.4.7 - Refactor PR #110#

  • Moves cloud sync dialog into the config menu, and removes icon on homepage
  • Fixes typo in Default theme name, Re #106
  • Spell checks readme
  • Updates the contributor CI action, that generates list of contributors + sponsors

📝 1.4.6 - Documentation Updates PR #108#

  • Breaks many of the longer files into several more digestible articles
  • Writes repo pages including, Security, Code of Conduct, Legal, Updates license
  • Makes an automatically generated Credits page
  • Adds a contributing page, with several ways that users can help out
  • Implements this changelog, as requested in #87

🌐 1.4.5 - Adds German Translations PR #107#

  • German language support, contributed by @Niklashere

✨ 1.4.4 - Adds Support for Logo Image PR #105#

  • Adds option in config file for user to specify path to an image
  • If found, will display said image in the header

✨ 1.4.3 - Auto-Checks for Updates PR #101 and PR #102#

  • Write a script to compare current version with git master version
  • Periodically checks for updates, and displays message to user
  • Enables user to disable update-checks in the config file
  • Checks not using vulnerable version on project-build

✨ 1.4.2 - Adds Multi-Language Support PR #99#

  • Implements vue-i18n, sets object globally
  • Extracts all text to a single JSON file
  • Auto-detects users language, and applies, if availible
  • Builds a form to let user manually select their language
  • Lets users language be saved and read from local storage, or config file

✨ 1.4.1 - Adds Support for Custom Key Bindings PR #94#

  • Adds new attribute under item for saving numeric key binding
  • Listens for keypress, and launches corresponding item, if found

✨ 1.4.0 - Builds a Custom Theme Configurator#

  • Adds property to save custom theme variables
  • Builds UI form, with color pickers, a pallette and popup
  • Integrates the saving colors, and applying saved colors functionality

🔨 1.3.9 - Enable Custom Styesheet in Docker PR #92#

  • Enables the user to pass a custom stylesheet in with Docker
  • Adds support for 1-Click deployment to Render.com

🌟 1.3.8 - Showcase #91#

  • Adds @Shadowking001's screenshot to showcase

🌟 1.3.7 - Showcase PR #84#

  • Adds @dtctek's screenshot to showcase

✨ 1.3.6 - Enables User to Hide Unwanted Components PR #78#

  • Adds several additional options to the config, allowing the user to hide structural components that they don't need
  • Including hideHeading, hideNav, hideSearch, hideSettings, hideFooter, hideSplashScreen

✨ 1.3.5 - Adds Support for Emoji Icons PR #76#

  • Enables user to use emojis for item and section icons
  • Adds a handler to convert Unicode, or Shortcode into an Emoji

🌟 1.3.4 - Showcase Addition PR #75#

  • Adds @cerealconyogurt's screenshot to the showcase

💄 1.3.3 - UI Improvements PR #73#

  • New style of Large item
  • 2 new color themes
  • Added CSS variables for search label and footer background
  • Improves process for auto-checking if font-awesome is needed
  • Silences non-critical warnings in production build
  • Adds new optional font-face for cyber punk
  • Shortens readme, and adds contribute links to showcase

⚡️ 1.3.0 - Custom Headers for Status Check PR #72#

  • Enables user to pass custom headers to the status check endpoint
  • Enables user to use a different URL for the status check request

🌟 1.2.9 - Creates a Showcase Page PR #68#

  • Adds a page in the docs for users to share their screenshots of their dashboard

✨ 1.2.8 - Adds Remember-Me Functionality into the Login Form PR #66#

  • Adds a dropdown menu in the login form with various time intervals available
  • Adds appropriate expiry into session storage, in order to keep user logged in for their desired time interval

✨ 1.2.7 - Implements a Right-Click Context Menu #62#

  • Built a context menu, showing all item opening methods, on right-click
  • Made a clickOutside directive, in order to close menu when user clicks away
  • Adds launching functionality, user can click to launch

⚡️ 1.2.6 - Make Font Assets Local PR #60#

  • Downloaded font files to assets
  • Removed all calls to font CDN, replaced with local calls

🐛 1.2.5 - Small Fixes, and Efficiency Improvements PR #57#

  • Adds correct license
  • Improves service workers, and adds serviceWorkerStatus local storage item
  • Adds missing statusCheck and statusCheckInterval docs into Configuring
  • Adds an About App page, containing info needed to raise a bug report
  • Adds TDLR license into main readme
  • Introduces app versioning
  • Adds safeguards into ConfigAccumalaror, to prevent error being thrown
  • Updates PR template
  • Improved Webpack build experience, with progress bar and completion notification
  • Adds new and improved icons for layout options
  • Make the Page Title into a home page link
  • Adds missing favicon, fixes #55
  • Adds assets to PWA manifest.json
  • Documents app commands in readme
  • Enable passing website as URL param to the workspace
  • Modified items, so that title text doesn't get shortened,

✨ 1.2.4 - Adds Support for Continuous Status Checking #52#

  • Enables user to re-call the status check at a specified interval
  • Processes interval in ms, and updates the traffic light when required

🐛 1.2.3 - Bug Fix PR #49#

  • Removes duplicate Docker env var, fixes #48

✨ 1.2.2 - Better Favicon Support#

  • Enables user to force direct/ local favicon fetching
  • Adds support for additional favicon API, returning high-res app icons
  • Adds support for generative icons

🐛 1.2.1 - Bugfix #44#

  • Fixes footer positioning on mobile, makes sticky, fixes #42

✨ 1.2.0 - Adds Writing Config to Disk from UI Functionality PR #43#

  • Creates a new server endpoint for handling the backing up of a the file
  • Adds backup existing file functionality
  • Adds writing new file functionality
  • Does error checking, testing and adds some security parameters
  • Adds a radio button in the UI, so user chan choose save method
  • Process config within the UI, convert to YAML, and write changes to disk

🐛 1.1.8 - Bugfix #40#

  • Status check tooltip was not visible in Material themes, raised in issue #39

✨ 1.1.7 - Adds Workspace View PR #38#

  • Adds a new route, for the workspace view
  • Builds the sidebar, which displays the users apps
  • Loads the app into the workspace's main iframe when clicked
  • Adds some collapsing functionality, better styles, subtle animations and theme support

✨ 1.1.6 - Implements Status Indicators, and Monitoring Functionality PR #34#

  • Wrote a Node endpoint for pinging the users desired services
  • Added status checking functionality in frontend
  • Build small traffic-light component to display status of users services
  • Adds animations, and handles errors
  • Writes docs, and tests code

✨ 1.1.5 - Adds Authentication / Login Functionality PR #32#

  • Enables the user to protect their dashboard behind a login screen
  • Creates a Authentication handler to manage the hashing of passwords, and generation of a token
  • Build a quick login form, where user can input username and password
  • Adds a log out button

💄 1.1.4 - Support for Custom HTML Footer PR #30#

  • Enables user to insert structure for the footer defined as HTML

🚀 1.1.3 - Adds Support for 1-Click Cloud Deployments PR #29#

  • Support for 1-Click Deploy to Netlify
  • Support for 1-Click Deploy to Heroku

🔧 1.1.2 - Docker Efficiency Improvements PR #26#

  • Writes a Node health check script, and implements into the Docker container
  • Changes default port in docker-compose, as 8080 is commonly used by other apps
  • Adds the 1-Click deploy with PWD into the readme
  • Updates dependencies
  • Adds a getting started guide to the docs
  • Adds splash screen for first load
  • Deleted unused assets
  • Makes linter run as a pre-commit hook
  • Fixes lint errors in server.js and validate-config.js

🐛 1.1.1 - Bug Fixes PR #20 + PR #21#

  • Adds issue template
  • Bug fixes
    • Improves github PR and issue templates
    • Shortens readme file
    • Adds documentation in the docs folder
    • Fixes Layout tab not showing in portrait #19
    • Improves mobile performance for both the settings, config and backup pop-ups
    • Fixes issue where theme not applied on load when the settings are hidden
    • Adds minimum dimensions to modalsShortens readme file
    • Adds documentation in the docs folder
    • Adds minimum dimensions to modals

🚑️ 1.1.0 - Hotfix #18#

  • Implementing the JSON validator had actually broken the entire JSON editor
  • Fixed it by remove explicit use of Ajv, and using a derivative instead

📝 1.0.5 - Documentation PR #16#

  • Previously there was very little documentation, this release fixed that
  • Wrote specific docs for:
    • Getting Started
    • Configuring
    • Backup & Restore
    • Theming
    • Developing

✨ 1.0.0 - Implements Config Validation PR #13#

  • Write a JSON schema for the conf.yml file
  • Wrote a validation script to compare users config against schema
  • Adds a formatter to print helpful messages about what needs fixing
  • Implements validation process into build script
  • Implements validation process into UI config configurator's validation

🔧 0.9.5 - Brand New Docker Container PR #12#

  • With help from several users, a new container based on Alpine is released
  • A sample Docker Compose script is also written, and docs are updated
  • A 1-Click button for deploying to Play-with-Docker is added to the Readme

✨ 0.9.0 - Adds Hide Settings Functionality PR #11#

  • Enables user to hide settings from UI
  • Users preference is saved in local storage
  • User can hide other structural elements of the UI from the config

💄 0.8.5 - Adds new Built-In Themes PR #9#

  • Adds Minimal-Dark and Minimal-Light theme
  • Adds Material-Dark and Material-Light theme
  • Adds additional theme docs
  • Adds option for sections to have items too

✨ 0.8.0 - Implements Custom CSS Editor PR: #8#

  • Adds a page in the config menu
  • Adds syntax highlighting, CSS validation and sanitization
  • Saves users CSS, and applies styles on page load

✨ 0.7.5 - Adds Cloud Backup and Restore Feature PR #6#

  • Creates a form for entering backup ID and decryption password
  • Puts form in modal, and adds button to launch form, with custom icon
  • Implemented the cryptography stuff for end-to-end data encryption
  • Wrote and tested the backend, and deployed as a serverless function on CF workers
  • On the frontend, users input is encrypted, and passed to backend cloud function
  • Response from the backend is handles appropriately, and message displayed to the user
  • Implements the restoring from server functionality, with data integrity checks

✨ 0.7.0 - Support for Custom Nav Links PR #4#

  • User can add custom nav bar links from the Config Settings menu
  • Better UI styling to the config menu
  • New icons inside buttons

✨ 0.6.5 - UI Config Editor PR #3#

Adds the ability for the user to edit their configuration directly from the UI

  • Edit all section and item data using a rich JSON editor
  • Download/ backup conf.yml directly from the UI
  • Edit site meta data: title, description, footer, etc
  • Reset all locally stored data to the initial state
  • Also includes a new toast component, for subtle notifications

✨ 0.6.0 - Navbar, Footer and Background Image#

  • Adds option for a custom full-size background image
  • Made footer customizable
  • Fixes error being thrown when navbar links are empty

⚡️ 0.5.5 - Improved Theming#

  • Makes more specific color variables, which inherit base vars
  • Makes it possible for users to write their own theme
  • Fix some color edge cases
  • Adds docs for theming

✨ 0.5.0 - Theme Support#

  • Converts all SCSS variables to CSS variables
  • Implements theme switching functionality
  • Adds a dropdown menu, enabling user to select theme
  • Adds an initial theme option to appConfig.theme
  • Saves selected theme to local storage
  • Wrote a ton of color themes

✨ 0.4.5 - Keyboard Navigation#

  • Implements arrow key navigation

✨ 0.4.0 - Font Awesome Support#

  • Adds support for Font-Awesome icons
  • Auto-loads font-awesome only when needed
  • Adds support for SVG icons

✨ 0.3.5 - Opening Method#

  • Shows opening method on hover
  • Opening method can be specified in config, as item[n].target

🔨 0.3.0 - Docker#

  • Writes a Dockerfile

🎨 0.2.5 - Code Quality, Docs and UI#

  • Huge code quality overhaul, now uses AirBnB style ESLint
  • Adds in-code docs, removes unneeded code, moves reusable helpers into utils dir
  • Adds a readme, records a demo gif and adds some basic deployment docs
  • Removes dependencies which are not 100% necessary

✨ 0.2.0 - Collapsible Sections#

  • Implements collapsing functionality, for less used or very long sections
  • Sections can read default state from section[n].collapsed within config
  • After change, state of each section is stored in local storage

⚡️ 0.1.5 - Search and Navigation#

  • Improves instant search functionality
  • Implements keyboard navigation for selecting items
  • Launch selected item with enter, or Ctrl + Enter to open in new tab

🎉 0.1.0 - Init#

Project started. Forked from Lissy93/Dash

- + \ No newline at end of file diff --git a/docs/code-of-conduct/index.html b/docs/code-of-conduct/index.html index d35bb8fe..bb08ae00 100644 --- a/docs/code-of-conduct/index.html +++ b/docs/code-of-conduct/index.html @@ -5,7 +5,7 @@ Contributor Covenant Code of Conduct | Dashy - + @@ -60,7 +60,7 @@ version 2.0, available at enforcement ladder.

For answers to common questions about this code of conduct, see the FAQ at https://www.contributor-covenant.org/faq. Translations are available at https://www.contributor-covenant.org/translations.

- + \ No newline at end of file diff --git a/docs/configuring/index.html b/docs/configuring/index.html index 614257f2..fa0004bc 100644 --- a/docs/configuring/index.html +++ b/docs/configuring/index.html @@ -5,13 +5,13 @@ Configuring | Dashy - +

Configuring

All app configuration is specified in /public/conf.yml which is in YAML Format format. Changes can also be made directly through the UI and previewed live, from here you can also export, backup, reset, validate and download your configuration file.

The following file provides a reference of all supported configuration options.

Contents#

Tips:

  • You may find it helpful to look at some sample config files to get you started, a collection of which can be found here
  • You can check that your config file fits the schema, by running yarn validate-config
  • After modifying your config, the app needs to be recompiled, by running yarn build - this happens automatically 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 feature.
  • The config can also be modified directly through the UI, validated and written to the conf.yml file.
  • All fields are optional, unless otherwise stated.

Top-Level Fields#

FieldTypeRequiredDescription
pageInfoobjectRequiredBasic meta data like title, description, nav bar links, footer text. See pageInfo
appConfigobjectOptionalSettings related to how the app functions, including API keys and global styles. See appConfig
sectionsarrayRequiredAn array of sections, each containing an array of items, which will be displayed as links. See section

⬆️ Back to Top

PageInfo#

FieldTypeRequiredDescription
titlestringRequiredYour dashboard title, displayed in the header and browser tab
descriptionstringOptionalDescription of your dashboard, also displayed as a subtitle
navLinksarrayOptionalOptional list of a maximum of 6 links, which will be displayed in the navigation bar. See navLinks
footerTextstringOptionalText to display in the footer (note that this will override the default footer content). This can also include HTML and inline CSS
logostringOptionalThe path to an image to display in the header (to the right of the title). This can be either local, where / is the root of ./public, or any remote image, such as https://i.ibb.co/yhbt6CY/dashy.png. It's recommended to scale your image down, so that it doesn't impact load times

⬆️ Back to Top

pageInfo.navLinks (optional)#

FieldTypeRequiredDescription
titlestringRequiredThe text to display on the link button
pathstringRequiredThe URL to navigate to when clicked. Can be relative (e.g. /about) or absolute (e.g. https://example.com or http://192.168.1.1)

⬆️ Back to Top

appConfig (optional)#

FieldTypeRequiredDescription
languagestringOptionalThe 2 (or 4-digit) ISO 639-1 code for your language, e.g. en or en-GB. This must be a language that the app has already been translated into. If your language is unavailable, Dashy will fallback to English. By default Dashy will attempt to auto-detect your language, although this may not work on some privacy browsers.
startingViewenumOptionalWhich 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
defaultOpeningMethodenumOptionalThe default opening method for items, if no target is specified for a given item. Can be either newtab, sametab, modal, workspace, clipboard, top or parent. Defaults to newtab
statusCheckbooleanOptionalWhen 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
statusCheckIntervalbooleanOptionalThe 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
webSearchobjectOptionalConfiguration options for the web search feature, set your default search engine, opening method or disable web search. See webSearch
backgroundImgstringOptionalPath to an optional full-screen app background image. This can be either remote (http) or local (/). Note that this will slow down initial load
enableFontAwesomebooleanOptionalWhere true is enabled, if left blank font-awesome will be enabled only if required by 1 or more icons
fontAwesomeKeystringOptionalIf 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)
faviconApienumOptionalOnly applicable if you are using favicons for item icons. Specifies which service to use to resolve favicons. Set to local to do this locally, without using an API. Services running locally will use this option always. Available options are: local, faviconkit, iconhorse, google, clearbit, webmasterapi and allesedv. Defaults to faviconkit. See Icons for more info
authobjectOptionalAll settings relating to user authentication. See auth
layoutenumOptionalLayout for homepage, either horizontal, vertical or auto. Defaults to auto. This specifies the layout and direction of how sections are positioned on the home screen. This can also be modified and overridden from the UI.
iconSizeenumOptionalThe size of link items / icons. Can be either small, medium, or large. Defaults to medium. This can also be set directly from the UI.
colCountnumberOptionalThe number of columns of sections displayed on the homepage, using the default view. Should be in integer between 1 and 8. Note that by default this is applied responsively, based on current screen size, and specifying a value here will override this behavior, which may not be desirable.
themestringOptionalThe default theme for first load (you can change this later from the UI)
cssThemesstring[]OptionalAn array of custom theme names which can be used in the theme switcher dropdown
customColorsobjectOptionalEnables you to apply a custom color palette to any given theme. Use the theme name (lowercase) as the key, for an object including key-value-pairs, with the color variable name as keys, and 6-digit hex code as value. See Theming for more info
externalStyleSheetstring or string[]OptionalEither a URL to an external stylesheet or an array or URLs, which can be applied as themes within the UI
customCssstringOptionalRaw CSS that will be applied to the page. This can also be set from the UI. Please minify it first.
hideComponentsobjectOptionalA list of key page components (header, footer, search, settings, etc) that are present by default, but can be removed using this option. See appConfig.hideComponents
routingModestringOptionalCan be either hash or history. Determines the URL format for sub-pages, hash mode will look like /#/home whereas with history mode available you have nice clean URLs, like /home. For more info, see the Vue docs. If you're hosting Dashy with a custom BASE_URL, you will find that a bit of extra server config is necessary to get history mode working, so here you may want to instead use hash mode.Defaults to history.
enableMultiTaskingbooleanOptionalIf set to true, will keep apps open in the background when in the workspace view. Useful for quickly switching between multiple sites, and preserving their state, but comes at the cost of performance.
workspaceLandingUrlstringOptionalThe URL or an app, service or website to launch when the workspace view is opened, before another service has been launched
allowConfigEditbooleanOptionalShould 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.
showSplashScreenbooleanOptionalIf set to true, a loading screen will be shown. Defaults to false.
enableErrorReportingbooleanOptionalEnable reporting of unexpected errors and crashes. This is off by default, and no data will ever be captured unless you explicitly enable it. Turning on error reporting helps previously unknown bugs get discovered and fixed. Dashy uses Sentry for error reporting. Defaults to false.
sentryDsnbooleanOptionalIf you need to monitor errors in your instance, then you can use Sentry to collect and process bug reports. Sentry can be self-hosted, or used as SaaS, once your instance is setup, then all you need to do is pass in the DSN here, and enable error reporting. You can learn more on the Sentry DSN Docs. Note that this will only ever be used if enableErrorReporting is explicitly enabled.
disableSmartSortbooleanOptionalFor 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.
disableUpdateChecksbooleanOptionalIf set to true, Dashy will not check for updates. Defaults to false.
enableServiceWorkerbooleanOptionalService 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.
disableContextMenubooleanOptionalIf set to true, the custom right-click context menu will be disabled. Defaults to false.

⬆️ Back to Top

appConfig.auth (optional)#

FieldTypeRequiredDescription
usersarrayOptionalAn array of objects containing usernames and hashed passwords. If this is not provided, then authentication will be off by default, and you will not need any credentials to access the app. See appConfig.auth.users.
Note this method of authentication is handled on the client side, so for security critical situations, it is recommended to use an alternate authentication method.
enableKeycloakbooleanOptionalIf 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
keycloakobjectOptionalConfig options to point Dashy to your Keycloak server. Requires enableKeycloak: true. See auth.keycloak for more info
enableGuestAccessbooleanOptionalWhen 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.

For more info, see the Authentication Docs

⬆️ Back to Top

appConfig.auth.users (optional)#

FieldTypeRequiredDescription
userstringRequiredUsername to log in with
hashstringRequiredA SHA-256 hashed password
typestringOptionalThe user type, either admin or normal

⬆️ Back to Top

appConfig.auth.keycloak (optional)#

FieldTypeRequiredDescription
serverUrlstringRequiredThe URL (or URL/ IP + Port) where your keycloak server is running
realmstringRequiredThe name of the realm (must already be created) that you want to use
clientIdstringRequiredThe Client ID of the client you created for use with Dashy

⬆️ Back to Top

appConfig.webSearch (optional)#

FieldTypeRequiredDescription
disableWebSearchstringOptionalWeb search is enabled by default, but can be disabled by setting this property to true
searchEnginestringOptionalSet 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
customSearchEnginestringOptionalYou 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
openingMethodstringOptionalSet your preferred opening method for search results: newtab, sametab, workspace. Defaults to newtab
searchBangsobjectOptionalA 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)#

FieldTypeRequiredDescription
hideHeadingbooleanOptionalIf set to true, the page title & sub-title will not be visible. Defaults to false
hideNavbooleanOptionalIf set to true, the navigation menu will not be visible. Defaults to false
hideSearchbooleanOptionalIf set to true, the search bar will not be visible. Defaults to false
hideSettingsbooleanOptionalIf set to true, the settings menu will be initially collapsed. Defaults to false
hideFooterbooleanOptionalIf set to true, the footer will not be visible. Defaults to false

⬆️ Back to Top

section#

FieldTypeRequiredDescription
namestringRequiredThe title for the section
iconstringOptionalAn single icon to be displayed next to the title. See section.icon
itemsarrayOptionalAn array of items to be displayed within the section. See item. Sections must include either 1 or more items, or 1 or more widgets.
widgetsarrayOptionalAn array of widgets to be displayed within the section. See widget
displayDataobjectOptionalMeta-data to optionally overide display settings for a given section. See displayData

⬆️ Back to Top

section.item#

FieldTypeRequiredDescription
titlestringRequiredThe text to display/ title of a given item. Max length 18
descriptionstringOptionalAdditional info about an item, which is shown in the tooltip on hover, or visible on large tiles
urlstringRequiredThe URL / location of web address for when the item is clicked
iconstringOptionalThe icon for a given item. Can be a font-awesome icon, favicon, remote URL or local URL. See item.icon
targetstringOptionalThe opening method for when the item is clicked, either newtab, sametab, modal, workspace, clipboard, top or parent. Where newtab will open the link in a new tab, sametab will open it in the current tab, and modal will open a pop-up modal, workspace will open in the Workspace view and clipboard will copy the URL to system clipboard (but not launch app). Defaults to newtab
hotkeynumberOptionalGive frequently opened applications a numeric hotkey, between 0 - 9. You can then just press that key to launch that application.
tagsstring[]OptionalA list of tags, which can be used for improved search
statusCheckbooleanOptionalWhen 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
statusCheckUrlstringOptionalIf you've enabled statusCheck, and want to use a different URL to what is defined under the item, then specify it here
statusCheckHeadersobjectOptionalIf you're endpoint requires any specific headers for the status checking, then define them here
statusCheckAllowInsecurebooleanOptionalBy 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
colorstringOptionalAn 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
backgroundColorstringOptionalAn 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
providerstringOptionalThe name of the provider for a given service, useful for when including hosted apps. In some themes, this is visible under the item name

⬆️ Back to Top

section.widget (optional)#

FieldTypeRequiredDescription
typestringRequiredThe widget type. See Widget Docs for full list of supported widgets
optionsobjectOptionalSome widgets accept either optional or required additional options. Again, see the Widget Docs for full list of options
updateIntervalnumberOptionalYou can keep a widget constantly updated by specifying an update interval, in seconds. See Continuous Updates Docs for more info
useProxybooleanOptionalSome widgets make API requests to services that are not CORS-enabled. For these instances, you will need to route requests through a proxy, Dashy has a built in CORS-proxy, which you can use by setting this option to true. Defaults to false. See the Proxying Requests Docs for more info

⬆️ Back to Top

section.displayData (optional)#

FieldTypeRequiredDescription
sortBystringOptionalThe 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
collapsedbooleanOptionalIf 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
cutToHeightbooleanOptionalBy default, sections will fill available space. Set this option to true to match section height with content height
rowsnumberOptionalHeight of the section, specified as the number of rows it should span vertically, e.g. 2. Defaults to 1. Max is 5.
colsnumberOptionalWidth of the section, specified as the number of columns the section should span horizontally, e.g. 2. Defaults to 1. Max is 5.
itemSizestringOptionalSpecify the size for items within this group, either small, medium or large. Note that this will overide any settings specified through the UI
colorstringOptionalA custom accent color for the section, as a hex code or HTML color (e.g. #fff)
customStylesstringOptionalCustom CSS properties that should be applied to that section, e.g. border: 2px dashed #ff0000;
sectionLayoutstringOptionalSpecify 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
itemCountXnumberOptionalThe 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
itemCountYnumberOptionalThe 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
hideForUsersstring[]OptionalCurrent section will be visible to all users, except for those specified in this list
showForUsersstring[]OptionalCurrent section will be hidden from all users, except for those specified in this list
hideForGuestsbooleanOptionalCurrent section will be visible for logged in users, but not for guests (see appConfig.enableGuestAccess). Defaults to false
hideForKeycloakUsersobjectOptionalCurrent section will be visible to all keycloak users, except for those configured via these groups and roles. See hideForKeycloakUsers
showForKeycloakUsersobjectOptionalCurrent section will be hidden from all keyclaok users, except for those configured via these groups and roles. See showForKeycloakUsers

⬆️ Back to Top

section.icon and section.item.icon#

FieldTypeRequiredDescription
iconstringOptionalThe icon for a given item or section.
See Icon Docs for all available supported icon types, including: auto-fetched favicons, generative icons, emoji icons, home-lab service logos, font-awesome, simple-icons, material icons, and icons specified by URL

⬆️ Back to Top

section.displayData.hideForKeycloakUsers and section.displayData.showForKeycloakUsers#

FieldTypeRequiredDescription
groupsstring[]OptionalCurrent Section will be hidden or shown based on the user having any of the groups in this list
rolesstring[]OptionalCurrent Section will be hidden or shown based on the user having any of the roles in this list

⬆️ Back to Top

Notes#

Editing Config through the UI#

Config can be modified directly through the UI, and then written to disk, or applied locally. This can be done wither with the raw config editor (introduced in V 0.6.5 / #3), or the interactive editor (introduced in V 1.8.9 / #298).

Interactive Editor
Interactive Editor demo
JSON Editor
Config Editor demo

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 should get you up to speed in a few minutes, for more advanced topics take a look at this Wikipedia article.

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#

---pageInfo:  title: Home Labsections: # An array of sections- name: Section 1 - Getting Started  items: # An array of items  - title: GitHub    description: Source code and documentation on GitHub    icon: fab fa-github    url: https://github.com/Lissy93/dashy  - title: Issues    description: View currently open issues, or raise a new one    icon: fas fa-bug    url: https://github.com/Lissy93/dashy/issues  - title: Demo    description: A live demo    icon: far fa-rocket    url: https://dashy-demo-1.netlify.app - name: Section 2 - Local Services  items:  - title: Firewall    icon: favicon    url: http://192.168.1.1/  - title: Game Server    icon: https://i.ibb.co/710B3Yc/space-invader-x256.png    url: http://192.168.130.1/

For more example config files, see: this gist

If you need any help, feel free to Raise an Issue or Start a Discussion

Happy Configuring 🤓🔧

⬆️ Back to Top

- + \ No newline at end of file diff --git a/docs/contributing/index.html b/docs/contributing/index.html index 9a8a2e49..f5c81b25 100644 --- a/docs/contributing/index.html +++ b/docs/contributing/index.html @@ -5,7 +5,7 @@ Contributing | Dashy - + @@ -34,7 +34,7 @@ All content is located either in the ./README.md< Alicia Sykes's Website Alicia Sykes's Blog Alicia Sykes's PGP

If you like, you could also consider subscribing to my mailing list for occasional blog post updates.

Contributors#

For a full list of Dashy's contributors, see the Credits Page

Auto-generated contributors

Star-Gazers Over Time#

Stargazers

- + \ No newline at end of file diff --git a/docs/credits/index.html b/docs/credits/index.html index 9832461d..7bfcb513 100644 --- a/docs/credits/index.html +++ b/docs/credits/index.html @@ -5,13 +5,13 @@ Credits | Dashy - +

Credits

Sponsors#

BOZG
Stephen Rigney		Robert-Ernst
Robert Ernst		vlad-timofeev
Vlad Timofeev		KierenConnell
Kieren Connell		ratty222
Ratty222

Contributors#

Lissy93
Alicia Sykes		liss-bot
Alicia Bot		EVOTk
EVOTk		snyk-bot
Snyk Bot		evroon
Erik Vroon		UrekD
UrekD
walkxcode
Walkx		onedr0p
ᗪєνιη ᗷυнʟ		BOZG
Stephen Rigney		daentech
Dan Gilbert		BeginCI
Begin		skaarj1989
David
deepsourcebot
DeepSource Bot		FormatToday
FormatToday		Compunctus
Iaroslav Dronskii		KierenConnell
Kieren Connell		rubjo
Rubjo		turnrye
Ryan Turner
royshreyaaa
Shreya Roy		XertDev
Xert		jnach
Jnach

Helpful Users#

evotk
Evotk		shadowking001
LawrenceP.		urekd
Urekd		dylanbeme
DylanH		milesteg1
Milesteg1		lu4t
Lu4t

Bots#

liss-bot
Alicia Bot		snyk-bot
Snyk Bot		netlify
Netlify		viezly
Viezly		muse-dev
MuseDev		github-actions[bot]
github-actions[bot]

The above section is auto-generated, using contribute-list by @akhilmhdh.

Newest Stargazers#

Recent Star Gazers

Recent Forkers

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

Core#

At it's core, the application uses Vue.js, as well as it's services with VueX for state management. Styling is done with SCSS, JavaScript is currently Babel, (but I am in the process of converting to TypeScript). Linting is done with ESLint and Prettier, both following the AirBnB Styleguide. The config is defined in YAML, with a simple Node.js server to serve up the static app and the optional API endpoints, and container deployment is done with Docker.

Utilities#

  • crypto-js - Encryption implementations by @evanvosberg and community MIT
  • axios - Promise based HTTP client by @mzabriskie and community MIT
  • ajv - JSON schema Validator by @epoberezkin and community MIT
  • i18n - Internationalization plugin by @kazupon and community MIT
  • frappe-charts - Lightweight charting library by @frappe MIT

Frontend Components#

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 using KV and web crypto

External Services#

The 1-Click deploy demo uses Play-with-Docker Labs. Code is hosted on GitHub, Docker images are hosted on DockerHub, and the demos are hosted on Netlify.

Actions#

This repo makes heavy use of GitHub actions to run automated workflows. The following base actions are totally awesome, and have been extremely useful. Full credit to their respective authors

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 for ways that you can get involved. Huge thank you to everyone who has already contributed! 💖

- + \ No newline at end of file diff --git a/docs/deployment/index.html b/docs/deployment/index.html index 61a736dd..ad91636a 100644 --- a/docs/deployment/index.html +++ b/docs/deployment/index.html @@ -5,7 +5,7 @@ Deployment | Dashy - + @@ -13,7 +13,7 @@

Deployment

Welcome to Dashy, so glad you're here :) Deployment is super easy, and there are several methods available depending on what type of system you're using. If you're self-hosting, then deploying with Docker (or similar container engine) is the recommended approach.

Quick Start#

If you want to skip the fuss, and get straight down to it, then you can spin up a new instance of Dashy by running:

docker run -p 8080:80 lissy93/dashy

See Management Docs for info about securing, monitoring, updating, health checks, auto starting, web server configuration, etc

Once you've got Dashy up and running, you'll want to configure it with your own content, for this you can reference the configuring docs.

Deployment Methods#

Deploy with Docker#

Container Info: Docker Supported ArchitectureDocker Base ImageDocker Hosted on
Status: Docker Build StatusDocker PullsDocker StarsDocker Image SizeDocker Cloud Build

Dashy has a built container image hosted on Docker Hub. You will need Docker installed on your system.

docker run -d \  -p 8080:80 \  -v /root/my-local-conf.yml:/app/public/conf.yml \  --name my-dashboard \  --restart=always \  lissy93/dashy:latest

Explanation of the above options:

  • -d Detached mode (not running in the foreground of your terminal)
  • -p The port that should be exposed, and the port it should be mapped to in your host system [host-port][container-port], leave the container port as is
  • -v Specify volumes, to pass data from your host system to the container, in the format of [host-path]:[container-path], you can use this to pass your config file, directory of assets (like icons), custom CSS or web assets (like favicon.ico, manifest.json etc)
  • --name Give your container a human-readable name
  • --restart=always Spin up the container when the daemon starts, or after it has been stopped
  • lissy93/dashy:latest This last option is the image the container should be built from, you can also use a specific version or architecture type, by replacing :latest with one of the tags

For all available options, and to learn more, see the Docker Run Docs

Dashy is also available through GHCR: docker pull ghcr.io/lissy93/dashy:latest

If you're deploying Dashy on a modern ARM-based board, such as a Raspberry Pi (2+), then you'll need to use one of Dashy's ARM images. Set the base image + tag to either lissy93/dashy:arm64v8 or lissy93/dashy:arm32v7, depending on your system architecture. You can also use the multi-arch image, which should work on all system architectures.

The image defaults to :latest, but you can instead specify a specific version, e.g. docker pull lissy93/dashy:release-1.5.0

Using Docker Compose#

Using Docker Compose can be useful for saving your specific config in files, without having to type out a long run command each time. Save compose config as a YAML file, and then run docker compose up -d (optionally use the -f flag to specify file location, if it isn't located at ./docker-compose.yml), -d is detached mode (not running in the foreground of your terminal). Compose is also useful if you are using clusters, as the format is very similar to stack files, used with Docker Swarm.

The following is a complete example of a docker-compose.yml for Dashy. Run it as is, or uncomment the additional options you need.

---version: "3.8"services:  dashy:    # To build from source, replace 'image: lissy93/dashy' with 'build: .'    # build: .    image: lissy93/dashy    container_name: Dashy    # Pass in your config file below, by specifying the path on your host machine    # volumes:      # - /root/my-config.yml:/app/public/conf.yml    ports:      - 4000:80    # Set any environmental variables    environment:      - NODE_ENV=production    # Specify your user ID and group ID. You can find this by running `id -u` and `id -g`    #  - UID=1000    #  - GID=1000    # Specify restart policy    restart: unless-stopped    # Configure healthchecks    healthcheck:      test: ['CMD', 'node', '/app/services/healthcheck']      interval: 1m30s      timeout: 10s      retries: 3      start_period: 40s

You can use a different tag, by for example setting image: lissy93/dashy:arm64v8, or pull from GHCR instead by setting image: ghcr.io/lissy93/dashy.

If you are building from source, and would like to use one of the other Dockerfiles, then under services.dashy first set context: ., then specify the the path to the dockerfile, e.g. dockerfile: ./docker/Dockerfile-arm32v7

Unraid#

// TODO

Synology NAS#

// TODO

Build from Source#

If you do not want to use Docker, you can run Dashy directly on your host system. For this, you will need both git and the latest or LTS version of Node.js installed, and optionally yarn

  1. Get Code: git clone https://github.com/Lissy93/dashy.git and cd dashy
  2. Configuration: Fill in you're settings in ./public/conf.yml
  3. Install dependencies: yarn
  4. Build: yarn build
  5. Run: yarn start

Deploy to cloud service#

If you don't have a home server, then fear not - Dashy can be deployed to pretty much any cloud provider. The above Docker and NPM guides will work exactly the same on a VPS, but I've also setup some 1-Click deploy links for 10+ of the most common cloud providers, to make things easier. Note that if your instance is exposed to the internet, it will be your responsibility to adequately secure it.

Some hosting providers required a bit of extra configuration, which was why I've made separate branches for deploying to those services (named: deploy_cloudflare, deploy_digital-ocean, deploy_platform-sh and deploy_render). If there's another cloud service which you'd like 1-click deployment to be supported for, feel free to raise an issue.

Note If you use a static hosting provider, then status checks, writing new config changes to disk from the UI, and triggering a rebuild through the UI will not be availible. This is because these features need endpoints provided by Dashy's local Node server. Everything else should work just the same though.

Netlify#

Deploy to Netlify

Netlify offers Git-based serverless cloud hosting for web applications. Their services are free to use for personal use, and they support deployment from both public and private repos, as well as direct file upload. The free plan also allows you to use your own custom domain or sub-domain, and is easy to setup.

To deploy Dashy to Netlify, use the following link

https://app.netlify.com/start/deploy?repository=https://github.com/lissy93/dashy

Heroku#

Deploy to Heroku

Heroku is a fully managed cloud platform as a service. You define app settings in a Procfile and app.json, which specifying how the app should be build and how the server should be started. Heroku is free to use for unlimited, non-commercial, single dyno apps, and supports custom domains. Heroku's single-dyno service is not as quite performant as some other providers, and the app will have a short wake-up time when not visited for a while

To deploy Dashy to Heroku, use the following link

https://heroku.com/deploy?template=https://github.com/Lissy93/dashy

Cloudflare Workers#

Deploy to Cloudflare Workers

Cloudflare Workers is a simple yet powerful service for running cloud functions and hosting web content. It requires a Cloudflare account, but is completely free for smaller projects, and very reasonably priced ($0.15/million requests per month) for large applications. You can use your own domain, and applications are protected with Cloudflare's state of the art DDoS protection. For more info, see the docs on Worker Sites

To deploy Dashy to Cloudflare, use the following link

https://deploy.workers.cloudflare.com/?url=https://github.com/lissy93/dashy/tree/deploy_cloudflare

Vercel#

Deploy with Vercel

Vercel is a performance-focused platform for hosting static frontend apps. It comes bundled with some useful tools for monitoring and anaylzing application performance and other metrics. Vercel is free for personal use, allows for custom domains and has very reasonable limits.

To deploy Dashy to Vercel, use the following link

https://vercel.com/new/project?template=https://github.com/lissy93/dashy

DigitalOcean#

Deploy to DO

DigitalOcan is a cloud service providing affordable developer-friendly virtual machines from $5/month. But they also have an app platform, where you can run web apps, static sites, APIs and background workers. CDN-backed static sites are free for personal use.

https://cloud.digitalocean.com/apps/new?repo=https://github.com/lissy93/dashy/tree/deploy_digital-ocean

Google Cloud Platform#

Run on Google Cloud

Cloud Run is a service offered by Google Cloud. It's a fully managed serverless platform, for developing and deploying highly scalable containerized applications. Similar to AWS and Azure, GCP offers a wide range of cloud services, which are billed on a pay‐per‐use basis, but Cloud Run has a free tier offering 180,000 vCPU-seconds, 360,000 GiB-seconds, and 2 million requests per month.

To deploy Dashy to GCP, use the following link

https://deploy.cloud.run/?git_repo=https://github.com/lissy93/dashy.git

Platform.sh#

Deploy to Platform.sh

Platform.sh is an end-to-end solution for developing and deploying applications. It is geared towards enterprise users with large teams, and focuses on allowing applications to scale up and down. Unlike the above providers, Platform.sh is not free, although you can deploy a test app to it without needing a payment method

To deploy Dashy to Platform.sh, use the following link

https://console.platform.sh/projects/create-project/?template=https://github.com/lissy93/dashy

Render#

Deploy to Render

Render is cloud provider that provides easy deployments for static sites, Docker apps, web services, databases and background workers. Render is great for developing applications, and very easy to use. Static sites are free, and services start at $7/month. Currently there are only 2 server locations - Oregon, USA and Frankfurt, Germany. For more info, see the Render Docs

To deploy Dashy to Render, use the following link

https://render.com/deploy?repo=https://github.com/lissy93/dashy/tree/deploy_render

Scalingo#

Deploy on Scalingo

Scalingo is a scalable container-based cloud platform as a service. It's focus is on compliance and uptime, and is geared towards enterprise users. Scalingo is also not free, although they do have a 3-day free trial that does not require a payment method

To deploy Dashy to Scalingo, use the following link

https://my.scalingo.com/deploy?source=https://github.com/lissy93/dashy#master

Play-with-Docker#

Try in PWD

Play with Docker is a community project by Marcos Liljedhal and Jonathan Leibiusky and sponsored by Docker, intended to provide a hands-on learning environment. Their labs let you quickly spin up a Docker container or stack, and test out the image in a temporary, sandboxed environment. There's no need to sign up, and it's completely free.

To run Dashy in PWD, use the following URL:

https://labs.play-with-docker.com/?stack=https://raw.githubusercontent.com/Lissy93/dashy/master/docker-compose.yml

Surge.sh#

Follow instructions below

Surge.sh is quick and easy static web publishing platform for frontend-apps. Surge supports password-protected projects. You can also add a custom domain and then force HTTPS by default and optionally set a custom SSL certificate

To deploy Dashy to Surge.sh, first clone and cd into Dashy, install dependencies, and then use the following commands

yarn add -g surgeyarn buildsurge ./dist

Hosting with CDN#

Once Dashy has been built, it is effectivley just a static web app. This means that it can be served up with pretty much any static host, CDN or web server. To host Dashy through a CDN, the steps are very similar to building from source: clone the project, cd into it, install dependencies, write your config file and build the app. Once build is complete you will have a ./dist directory within Dashy's root, and this is the build application which is ready to be served up.

However without Dashy's node server, there are a couple of features that will be unavailible to you, including: Writing config changes to disk through the UI, triggering a rebuild through the UI and application status checks. Everything else will work fine.

Requirements#

System Requirements#

Dashy works well on a Raspberry Pi (tested on Pi 3 and later), but should also run well on any system.

Docker#

Initial app build causes a spike in resource usage, but once the built app is running it is fairly steady. For this reason, Dashy works best with a minimum of 1GB of memory, and 1GB of disk space.

Bare Metal#

Minimum 526mb mem, 2GB disk space,

CDN / Cloud Deploy#

No specific requirements. The built application alone (without the Node server) is very light-weight, and can be handled smoothly by pretty much any CDN or cloud deployment service (see this list or natively supported cloud providers).

If you're using your own icons, or other assets, additional disk space will be required for those resources.

Browser Support#

JavaScript is required to run Dashy.

In terms of browser support, pretty much any browser released since 2018 should render content just fine. However, for Internet Explorer, only IE11+ is supported, yet performance here is still not optimal. The recommended browser is either a Chromium-based / Webkit browser (Chrome, Brave, Vivaldi, Edge, Yandex, etc), or Firefox or one of it's forks (FF-ESR, Tor, LibreWolf, etc). Recent versions of Safari and Opera are also supported, but with limited continuous testing.

- + \ No newline at end of file diff --git a/docs/developing/index.html b/docs/developing/index.html index 04b5d170..6cc98f85 100644 --- a/docs/developing/index.html +++ b/docs/developing/index.html @@ -5,7 +5,7 @@ Developing | Dashy - + @@ -13,7 +13,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, for tutorials covering basic tasks.

Setting up the Dev Environment#

Prerequisites#

You will need either the latest or LTS version of Node.js to build and serve the application and Git to easily fetch the code, and push any changes. If you plan on running or deploying the container, you'll also need Docker. To avoid any unexpected issues, ensure you've got at least NPM V 7.5 or Yarn 1.22 (you may find NVM helpful for switching/ managing versions).

Running the Project#

  1. Get Code: git clone https://github.com/Lissy93/dashy.git
  2. Navigate into the directory: cd dashy
  3. Install dependencies: yarn
  4. Start dev server: yarn dev

Dashy should now be being served on http://localhost:8080/. Hot reload is enabled, so making changes to any of the files will trigger them to be rebuilt and the page refreshed.

Project Commands#

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)

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

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.
  • 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

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, 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. 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, 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 either in your environment, or using the .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. 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.

Git Strategy#

Git Flow#

Like most Git repos, we are following the Github Flow standard.

  1. Create a branch (or fork if you don'd have write access)
  2. Code some awesome stuff 🧑‍💻
  3. Add, commit and push your changes to your branch/ fork
  4. Head over to GitHub and create a Pull Request
  5. Fill in the required sections in the template, and hit submit
  6. Follow up with any reviews on your code
  7. 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

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!

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:

As well as Node, Git and Docker- you'll also need an IDE (e.g. VS Code or Vim) and a terminal (Windows users may find WSL more convenient).

App Info#

Style Guide#

Linting is done using ESLint, and using the Vue.js Styleguide, which is very similar to the AirBnB Stylguide. 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

The most significant things to note are:

  • Indentation should be done with two spaces
  • Strings should use single quotes
  • All statements must end in a semi-colon
  • The final element in all objects must be preceded with a comma
  • Maximum line length is 100
  • There must be exactly one blank line between sections, before function names, and at the end of the file
  • With conditionals, put else on the same line as your if block’s closing brace
  • All multiline blocks must use braces
  • Avoid console statements in the frontend

Styleguides:

Application Structure#

Files in the Root: ./#

╮├── package.json        # Project meta-data, dependencies and paths to scripts├── src/                # Project front-end source code├── server.js           # A Node.js server to serve up the /dist directory├── services/           # All server-side endpoints and utilities├── vue.config.js       # Vue.js configuration├── Dockerfile          # The blueprint for building the Docker container├── docker-compose.yml  # A Docker run command├── .env                # Location for any environmental variables├── yarn.lock           # Auto-generated list of current packages and version numbers├── docs/               # Markdown documentation├── README.md           # Readme, basic info for getting started├── LICENSE.md          # License for use╯

Frontend Source: ./src/#

./src├── App.vue                       # Vue.js starting file├── assets                        # Static non-compiled assets│  ├── fonts                      # .ttf font files│  ├── locales                    # All app text, each language in a separate JSON file│  ╰── interface-icons            # SVG icons used in the app ├── components                    # All front-end Vue web components│  ├── Charts                     # Charting components for dynamically displaying widget data│  │  ├── Gauge.vue               # A speed-dial style chart for showing 0 - 100 values│  │  ╰── PercentageChart.vue     # A horizontal bar for showing percentage breakdowns│  ├── 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│  │  ├── EditSiteMeta.vue        # Form where the user can edit site meta data│  │  ├── JsonEditor.vue          # JSON editor, where the user can modify the main config file│  │  ╰── RebuildApp.vue          # A component allowing user to trigger a rebuild through the UI│  ├── FormElements               # Basic form elements used throughout the app│  │  ├── Button.vue              # Standard button component│  │  ├── Radio.vue               # Standard radio button input│  │  ├── Select.vue              # Standard dropdown input selector│  │  ├── Input.vue               # Standard text field input component│  │  ╰── Toggle.vue              # Standard on / off toggle switch│  ├── InteractiveEditor          # Components for the interactive UI config editor│  │  ├── AddNewSectionLauncher   # Button that launches the EditSection form, used for adding new section│  │  ├── EditAppConfig.vue       # Form for editing appConfig│  │  ├── EditPageInfo.vue        # Form for editing pageInfo│  │  ├── EditSection.vue         # Form for adding / editing sections│  │  ├── EditItem.vue            # Form for adding or editing items│  │  ├── EditModeSaveMenu.vue    # The bar at the bottom of screen in edit mode, containing save buttons│  │  ├── EditModeTopBanner.vue   # The bar at the top of screen in edit mode│  │  ├── ExportConfigMenu.vue    # Modal for viewing / exporting edited config│  │  ├── MoveItemTo.vue          # Form for moving / copying items to other sections│  │  ╰── SaveCancelButtons.vue   # Buttons visible in all the edit menus, to save or cancel changes│  ├── LinkItems                  # Components for Sections and Link Items│  │  ├── Collapsable.vue         # The collapsible functionality of sections│  │  ├── IframeModal.vue         # Pop-up iframe modal, for viewing websites within the app│  │  ├── Item.vue                # Main link item, which is displayed within an item group│  │  ├── ItemGroup.vue           # Item group is a section containing icons│  │  ├── ItemIcon.vue            # The icon used by both items and sections│  │  ├── ItemOpenMethodIcon.vue  # A small icon, visible on hover, indicating opening method │  │  ├── ItemContextMenu.vue     # The right-click menu, for showing Item opening methods and info│  │  ├── SectionContextMenu.vue  # The right-click menu, for showing Section edit/ open options│  │  ╰── 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│  │  ╰── WidgetView.vue          # Workspace container for displaying widgets in main content│  ├── Widgets                    # Directory contains all custom widget components│  │  ╰── ....                    # Too many to list, see widget docs instead│  ╰── Settings                   # Components relating to the quick-settings, in the top-right│     ├── 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│     ├── KeyboardShortcutInfo.vue# Small pop-up displaying the available keyboard shortcuts│     ├── LanguageSwitcher.vue    # Dropdown in a modal for changing app language│     ├── LayoutSelector.vue      # Set of buttons, letting the user select their desired layout│     ├── SearchBar.vue           # The input field in the header, used for searching the app│     ├── SettingsContainer.vue   # Container that wraps all the quick-settings components│     ╰── ThemeSelector.vue       # Drop-down menu enabling the user to select and change themes├── main.js                       # Main front-end entry point├── registerServiceWorker.js      # Registers and manages service workers, for PWA apps├── router.js                     # Defines all available application routes├── styles                        # Directory of all globally used common SCSS styles│  ├── color-palette.scss         # All color variable names and default values│  ├── color-themes.scss          # All variable values for built-in themes│  ├── dimensions.scss            # Dimensions and sizes as variables│  ├── global-styles.scss         # Basics and style resets used globally│  ├── media-queries.scss         # Screen sizes and media queries│  ├── style-helpers.scss         # SCSS functions used for modifying values│  ├── typography.scss            # Font and text styles used globally│  ╰── user-defined-themes.scss   # Empty, put any custom styles or themes here├── mixins                        # Reusable component bases, extended by other views / components│  ├── ChartingMixin.js           # Functions for rendering charts in widget components│  ├── GlancesMixin.js            # Functions for fetching system info from Glances for widgets│  ├── HomeMixin.js               # Functions for homepage, used by default, minimal and workspace views│  ╰── WidgetMixin.js             # Functions for all widgets, like data fetching, updating and error handling├── 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│  ├── 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│  ├── KeycloakAuth.js            # Singleton class to manage Keycloak authentication│  ├── languages.js               # Handles fetching, switching and validating languages│  ╰── ThemeHelper.js             # Function that handles the fetching and setting of user themes╰── views                         # Directory of available pages, corresponding to available routes   ├── Home.vue                   # The home page container   ├── About.vue                  # About page   ├── Login.vue                  # TAuthentication page   ├── Minimal.vue                # The minimal view   ╰── Workspace.vue              # The workspace view with apps in sidebar

Visualisation of Source Directory#

File Breakdown

Development Tools#

Performance - Lighthouse#

The easiest method of checking performance is to use Chromium's build in auditing tool, Lighthouse. To run the test, open Developer Tools (usually F12) --> Lighthouse and click on the 'Generate Report' button at the bottom.

Dependencies - BundlePhobia#

BundlePhobia is a really useful app that lets you analyze the cost of adding any particular dependency to an application

Notes#

Known Warnings#

When running the build command, several warnings appear. These are not errors, and do not affect the security or performance of the application. They will be addressed in a future update

WARN A new version of sass-loader is available. Please upgrade for best experience. - Currently we're using an older version of SASS loader, since the more recent releases do not seem to be compatible with the Vue CLI's webpack configuration.

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.

- + \ No newline at end of file diff --git a/docs/development-guides/index.html b/docs/development-guides/index.html index 830e45b4..d813db9b 100644 --- a/docs/development-guides/index.html +++ b/docs/development-guides/index.html @@ -5,7 +5,7 @@ Development Guides | Dashy - + @@ -19,7 +19,7 @@ Then, from within the root of Dashy's directory, start the server, by runni import axios from 'axios';import WidgetMixin from '@/mixins/WidgetMixin';import { widgetApiEndpoints } from '@/utils/defaults'; export default { mixins: [WidgetMixin], data() { return { results: null, }; }, computed: { endpoint() { return `${widgetApiEndpoints.myApi}/something`; }, }, methods: { fetchData() { this.makeRequest(this.endpoint).then(this.processData); }, processData(data) { // Do processing any here, and set component data this.results = data; }, },};</script> <style scoped lang="scss"></style>

All widgets extend from the Widget mixin. This provides some basic functionality that is shared by all widgets. The mixin includes the following options, startLoading(), finishLoading(), error() and update().

  • Getting user options: options
    • Any user-specific config can be accessed with this.options.something (where something is the data key your accessing)
  • Loading state: startLoading() and finishLoading()
    • You can show the loader with this.startLoading(), then when your data request completes, hide it again with this.finishLoading()
  • Error handling: error()
    • If something goes wrong (such as API error, or missing user parameters), then call this.error() to show message to user
  • Updating data: update()
    • When the user clicks the update button, or if continuous updates are enabled, then the update() method within your widget will be called

Step 2 - Adding Functionality#

Accessing User Options

If your widget is going to accept any parameters from the user, then we can access these with this.options.[parmName]. It's best to put these as computed properties, which will enable us to check it exists, is valid, and if needed format it. For example, if we have an optional property called count (to determine number of results), we can do the following, and then reference it within our component with this.count

computed: {  count() {    if (!this.options.count) {      return 5;    }    return this.options.count;  },    ...},

Adding an API Endpoint

If your widget makes a data request, then add the URL for the API under point to the widgetApiEndpoints array in defaults.js

widgetApiEndpoints: {  ...  exampleEndpoint: 'https://hub.dummyapis.com/ImagesList',},

Then in your widget file:

import { widgetApiEndpoints } from '@/utils/defaults';

For GET requests, you may need to add some parameters onto the end of the URL. We can use another computed property for this, for example:

endpoint() {  return `${widgetApiEndpoints.exampleEndpoint}?count=${this.count}`;},

Making an API Request

Axios is used for making data requests, so import it into your component: import axios from 'axios';

Under the methods block, we'll create a function called fetchData, here we can use Axios to make a call to our endpoint.

fetchData() {  this.makeRequest(this.endpoint, this.headers).then(this.processData);},

There are three things happening here:

  • If the response completes successfully, we'll pass the results to another function that will handle them
  • If there's an error, then we call this.error(), which will show a message to the user
  • Whatever the result, once the request has completed, we call this.finishLoading(), which will hide the loader

Processing Response

In the above example, we call the processData() method with the result from the API, so we need to create that under the methods section. How you handle this data will vary depending on what's returned by the API, and what you want to render to the user. But however you do it, you will likely need to create a data variable to store the response, so that it can be easily displayed in the HTML.

data() {  return {    myResults: null,  };},

And then, inside your processData() method, you can set the value of this, with:

`this.myResults = 'whatever'`

Rendering Response

Now that the results are in the correct format, and stored as data variables, we can use them within the <template> to render results to the user. Again, how you do this will depend on the structure of your data, and what you want to display, but at it's simplest, it might look something like this:

<p class="results">{{ myResults }}</p>

Styling

Styles can be written your your widget within the <style> block.

There are several color variables used by widgets, which extend from the base pallete. Using these enables users to override colors to theme their dashboard, if they wish. The variables are: --widget-text-color, --widget-background-color and --widget-accent-color

<style scoped lang="scss">p.results {  color: var(--widget-text-color);}</style>

For examples of finished widget components, see the Widgets directory. Specifically, the XkcdComic.vue widget is quite minimal, so would make a good example, as will this example implementation.

Step 3 - Register#

Next, import and register your new widget, in WidgetBase.vue. In this file, you'll need to add the following:

Import your widget file

import ExampleWidget from '@/components/Widgets/ExampleWidget.vue';

Then register the component

components: {  ...  ExampleWidget,},

Finally, add the markup to render it. The only attribute you need to change here is, setting widgetType === 'example' to your widget's name.

<ExampleWidget  v-else-if="widgetType === 'example'"  :options="widgetOptions"  @loading="setLoaderState"  @error="handleError"  :ref="widgetRef"/>

Step 4 - Docs#

Finally, add some documentation for your widget in the Widget Docs, so that others know hoe to use it. Include the following information: Title, short description, screenshot, config options and some example YAML.

Summary: For a complete example of everything discussed here, see: 3da76ce

- + \ No newline at end of file diff --git a/docs/icons/index.html b/docs/icons/index.html index 81c36e07..3c3777e0 100644 --- a/docs/icons/index.html +++ b/docs/icons/index.html @@ -5,13 +5,13 @@ Icons | Dashy - +

Icons

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. Dashy supports multiple different icon providers, usage instructions for which are explained here.

Favicons#

Dashy can auto-fetch an icon for a given service, using it's favicon. Just set icon: favicon to use this feature.

Since different websites host their favicons at different paths, for the best results Dashy can use an API to resolve a websites icon.

The default favicon API is allesedv.com, but you can change this under appConfig.faviconApi. If you'd prefer not to use an API, just set this value to local. You can also use different APIs for individual items, by setting icon: favicon-[api], e.g. favicon-clearbit.

The following favicon APIs are supported:

  • allesedv - allesedv.com is a highly efficient IPv6-enabled service
  • iconhorse - Icon.Horse returns quality icons for any site, with caching for speed and fallbacks for sites without an icon
  • clearbit - Clearbit returns high-quality square logos from mainstream websites
  • faviconkit - faviconkit.com good quality icons and most sites supported (Note: down as of Nov '21)
  • besticon - BestIcon fetches websites icons from manifest
  • mcapi - MC-API fetches default website favicon, originally a Minecraft util
  • duckduckgo - Returns decent quality website icons, from DuckDuckGo search
  • google - Official Google favicon API service, good support for all sites, but poor quality
  • yandex - Lower quality icons, but useful in some regions where other services are blocked
  • local - Set to local to fetch the default icon at /favicon.ico instead of using an API

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. For example, icon: https://monitoring.local/faviconx128.png- you can find this path using the browser dev tools.

Font Awesome#

You can use any Font Awesome Icon simply by specifying it's identifier. This is in the format of [category] [name] and can be found on the page for that 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.

Simple Icons#

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, then just set your icon the the simple icon slug, prefixed with si-.

For example:

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

Generative Icons#

To uses a unique and programmatically generated icon for a given service just set icon: generative. 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 DiceBear (or Evatar for fallback), and use a hash of the services domain/ ip for entropy, so each domain will have a unique icon.

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 (near the bottom of emoji each page), or for a quick reference to emoji shortcodes, check out emojis.ninja by @nomanoff.

For example, these will all render the same rocket (🚀) emoji: icon: ':rocket:' or icon: 'U+1F680' or icon: 🚀

Home-Lab Icons#

The dashboard-icons repo by @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 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 method may be a better option for you.

For example:

sections:- name: Home Lab Icons Example  items:  - title: AdGuard Home    icon: hl-adguardhome  - title: Long Horn    icon: hl-longhorn  - title: Nagios    icon: hl-nagios  - title: Whoogle Search    icon: hl-whooglesearch

Material Design Icons#

Dashy also supports 5000+ material-design-icons. To use these, first find the name/ slug for your icon here, and then prefix is with mdi-.

For example:

sections:- name: Material Design Icons Example  items:  - title: Alien Icon    icon: mdi-alien   - title: Fire Icon    icon: mdi-fire   - title: Dino Icon    icon: mdi-google-downasaur

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 (local or remote) - 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#

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 organized. You would then specify an icon with it's folder name slash image name. For example: networking/monit.png

No Icon#

If you don't wish for a given item or section to have an icon, just leave out the icon attribute.

Icon Collections and Resources#

The following websites provide good-quality, free icon sets. To use any of these icons, either copy the link to the raw icon (it should end in .svg or .png) and paste it as your icon, or download and save the icons in /public/item-icons / mapped Docker volume. Full credit to the authors, please see the licenses for each service for usage and copyright information.

If you are a student, then you can get free access to premium icons on Icon Scout or Icons8 using the GitHub Student Pack.

Notes#

If you are using icons from an external source, these will be fetched on initial page load automatically, if and when needed. But combining icons from multiple services may have a negative impact on performance.

You can improve load speeds, by downloading your required icons, and serving them locally. Scaling icons to the minimum required dimensions (e.g. 128x128 or 64x64) will also greatly improve application load times.

For icons from external sources, please see the Privacy Policies and Licenses for that provider.

- + \ No newline at end of file diff --git a/docs/index.html b/docs/index.html index 883be423..d29c81e2 100644 --- a/docs/index.html +++ b/docs/index.html @@ -5,13 +5,13 @@ Dashy | Dashy - +

Dashy Docs

- + \ No newline at end of file diff --git a/docs/license/index.html b/docs/license/index.html index 2e0981ac..78abcb31 100644 --- a/docs/license/index.html +++ b/docs/license/index.html @@ -5,7 +5,7 @@ license | Dashy - + @@ -15,7 +15,7 @@ Permission is hereby granted, free of charge, to any person obtaining a copyof this software and associated documentation files (the "Software"), to dealin the Software without restriction, including without limitation the rightsto use, copy, modify, merge, publish, distribute, sublicense, and/or sellcopies of the Software, and to permit persons to whom the Software isfurnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in allcopies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS ORIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THEAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHERLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THESOFTWARE.
- + \ No newline at end of file diff --git a/docs/management/index.html b/docs/management/index.html index 6f6203ec..02987927 100644 --- a/docs/management/index.html +++ b/docs/management/index.html @@ -5,7 +5,7 @@ App Management | Dashy - + @@ -30,7 +30,7 @@ Similarly, never expose /var/run/docker.sock to other containers as For example: scp -r ./dist/* [username]@[server_ip]:/var/www/dashy/html

Apache#

Copy Dashy's dist folder to your apache server, sudo cp -r ./dashy/dist /var/www/html/dashy.

In your Apache config, /etc/apche2/apache2.conf add:

<Directory /var/www/html>    Options Indexes FollowSymLinks    AllowOverride All    Require all granted</Directory>
 <IfModule mod_rewrite.c>  RewriteEngine On  RewriteBase /  RewriteRule ^index\.html$ - [L]  RewriteCond %{REQUEST_FILENAME} !-f  RewriteCond %{REQUEST_FILENAME} !-d  RewriteRule . /index.html [L]</IfModule>

Add a .htaccess file within /var/www/html/dashy/.htaccess, and add:

Options -MultiViewsRewriteEngine OnRewriteCond %{REQUEST_FILENAME} !-fRewriteRule ^ index.html [QSA,L]

Then restart Apache, with sudo systemctl restart apache2

Caddy#

Caddy v2

try_files {path} /

Caddy v1

rewrite {  regexp .*  to {path} /}

Firebase Hosting#

Create a file names firebase.json, and populate it with something similar to:

{  "hosting": {    "public": "dist",    "rewrites": [      {        "source": "**",        "destination": "/index.html"      }    ]  }}

cPanel#

  1. Login to your WHM
  2. Open 'Feature Manager' on the left sidebar
  3. Under 'Manage feature list', click 'Edit'
  4. Find 'Application manager' in the list, enable it and hit 'Save'
  5. Log into your users cPanel account, and under 'Software' find 'Application Manager'
  6. Click 'Register Application', fill in the form using the path that Dashy is located, and choose a domain, and hit 'Save'
  7. The application should now show up in the list, click 'Ensure dependencies', and move the toggle switch to 'Enabled'
  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

Running a Modified Version of the App#

If you'd like to make any code changes to the app, and deploy your modified version, this section briefly explains how.

The first step is to fork the project on GitHub, and clone it to your local system. Next, install the dependencies (yarn), and start the development server (yarn dev) and visit localhost:8080 in your browser. You can then make changes to the codebase, and see the live app update in real-time. Once you've finished, running yarn build will build the app for production, and output the assets into ./dist which can then be deployed using a web server, CDN or the built-in Node server with yarn start. For more info on all of this, take a look at the Developing Docs. To build your own Docker container from the modified app, see Building your Own Container

⬆️ Back to Top

Building your Own Container#

Similar to above, you'll first need to fork and clone Dashy to your local system, and then install dependencies.

Then, either use Dashy's default Dockerfile as is, or modify it according to your needs.

To build and deploy locally, first build the app with: docker build -t dashy ., and then start the app with docker run -p 8080:80 --name my-dashboard dashy. Or modify the docker-compose.yml file, replacing image: lissy93/dashy with build: . and run docker compose up.

Your container should now be running, and will appear in the list when you run docker container ls –a. If you'd like to enter the container, run docker exec -it [container-id] /bin/ash.

You may wish to upload your image to a container registry for easier access. Note that if you choose to do this on a public registry, please name your container something other than just 'dashy', to avoid confusion with the official image. You can push your build image, by running: docker push ghcr.io/OWNER/IMAGE_NAME:latest. You will first need to authenticate, this can be done by running echo $CR_PAT | docker login ghcr.io -u USERNAME --password-stdin, where CR_PAT is an environmental variable containing a token generated from your GitHub account. For more info, see the Container Registry Docs.

⬆️ Back to Top

- + \ No newline at end of file diff --git a/docs/multi-language-support/index.html b/docs/multi-language-support/index.html index 4a94039e..f6754180 100644 --- a/docs/multi-language-support/index.html +++ b/docs/multi-language-support/index.html @@ -5,7 +5,7 @@ Internationalization | Dashy - + @@ -15,7 +15,7 @@ If your language is a specific dialect or regional translation, then use the Pos E.g. import de from '@/assets/locales/de.json';

Second, add it to the array of languages, e.g:

export const languages = [  {    name: 'English',    code: 'en',    locale: en,    flag: '🇬🇧',  },  {    name: 'German', // The name of your language    code: 'de', // The ISO code of your language    locale: de, // The name of the file you imported (no quotes)    flag: '🇩🇪', // An optional flag emoji  },];

You can also add your new language to the readme, under the Language Switching section and optionally include your name/ username if you'd like to be credited for your work. Done!

If you are not comfortable with making pull requests, or do not want to modify the code, then feel free to instead send the translated file to me, and I can add it into the application. I will be sure to credit you appropriately.

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#

Firstly, go to ./src/assets/locales/en.json, and either find the appropriate section, or create a new section. Lets say you're new component is called my-widget, you could add "my-widget": {} to store all your text as key-value-pairs. E.g.

"my-widget": {    "awesome-text": "I am some text, that will be seen by the user"}

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#

Once your text is in the translation file, you can now use it within your component. There is a global $t function, with takes the key of your new translation, and returns the value. For example:

<p>{{ $t('my-widget.awesome-text') }}</p>

Note that the {{ }} just tells Vue that this is JavaScript/ dynamic. This will render: <p>I am some text, that will be seen by the user</p>

If you need to display text programmatically, from within the components JavaScript (e.g. in a toast popup), then use this.$t. For example: alert(this.$t('my-widget.awesome-text')).

You may also need to pass a variable to be displayed within a translation. Vue I18n supports Interpolations using mustache-like syntax.

For example, you would set your translation to:

{    "welcome-message": "Hello {name}!"}

And then pass that variable (name) within a JSON object as the second parameter on $t, like:

$t('welcome-message', { name: 'Alicia' })

Which will render:

Hello Alicia!

There are many other advanced features, including Pluralization, Datetime & Number Formatting, Message Support and more, all of which are outlined in the Vue-i18n Docs.

Basic Example#

Using the search bar as an example, this would look something like:

In ./src/components/Settings/SearchBar.vue:

<template>  <form>    <label for="search-input">{{ $t('search.search-label') }}</label>    <input      v-model="searchValue"      :placeholder="$t('search.search-placeholder')"    />  </form></template>

Then in ./src/assets/locales/en.json:

{"search": {    "search-label": "Search",    "search-placeholder": "Start typing to filter",  },  ...}
- + \ No newline at end of file diff --git a/docs/privacy/index.html b/docs/privacy/index.html index 45347839..58e7d841 100644 --- a/docs/privacy/index.html +++ b/docs/privacy/index.html @@ -5,7 +5,7 @@ Privacy & Security | Dashy - + @@ -13,7 +13,7 @@

Privacy & Security

Dashy was built with privacy in mind. Self-hosting your own apps and services is a great way to protect yourself from the mass data collection employed by big tech companies, and Dashy was designed to keep your local services organized and accessible from a single place.

It's fully open source, and I've tried to keep to code as clear and thoroughly documented as possible, which will make it easy for you to understand exactly how it works, and what goes on behind the scenes.

For privacy and security tips, check out another project of mine: Personal Security Checklist.

External Requests#

By default, Dashy will not make any external requests, unless you configure it to. Some features (which are off by default) do require internat access, and this section outlines those features, the services used, and links to their privacy policies.

Font Awesome#

If either any of your sections or items are using font-awesome icons, then these will be fetched directly from font-awesome on page load. See the Font Awesome Privacy Policy for more info.

Favicon Fetching#

If an item's icon is set to favicon, then it will be auto-fetched from the corresponding URL. Since not all websites have their icon located at /favicon.ico, and if they do, it's often very low resolution (like 16 x 16 px). Therefore, the default behavior is for Dashy to check if the URL is public, and if so will use an API to fetch the favicon. For self-hosted services, the favion will be fetched from the default path, and no external requests will be made.

The default favicon API is Favicon Kit, but this can be changed by setting appConfig.faviconApi to an alternate source (google, clearbit, webmasterapi and allesedv are supported). If you do not want to use any API, then you can set this property to local, and the favicon will be fetched from the default path. For hosted services, this will still incur an external request.

Generative Icons#

If an item has the icon set to generative, then an external request it made to Dice Bear to fetch the uniquely generated icon. The URL of a given service is used as the key for generating the icon, but it is first hashed and encoded for basic privacy. For more info, please reference the Dicebear Privacy Policy

Other Icons#

Section icons, item icons and app icons are able to accept a URL to a raw image, if the image is hosted online then an external request will be made. To avoid the need to make external requests for icon assets, you can either use a self-hosted CDN, or store your images within ./public/item-icons (which can be mounted as a volume if you're using Docker).

Web Assets#

By default, all assets required by Dashy come bundled within the source, and so no external requests are made. If you add an additional font, which is imported from a CDN, then that will incur an external request. The same applies for other web assets, like external images, scripts or styles.

Status Checking#

The status check util will ping your services directly, and does not rely on any third party. If you are checking the uptime status of a public/ hosted application, then please refer to that services privacy policy. For all self-hosted services, requests happen locally within your network, and are not external.

Update Checks#

When the application loads, it checks for updates. The results of which are displayed in the config menu of the UI. This was implemented because using a very outdated version of Dashy may have unfixed issues. Your version is fetched from the source (local request), but the latest version is fetched from GitHub, which is an external request. This can be disabled by setting appConfig.disableUpdateChecks: true

Anonymous Error Reporting#

Error reporting is disabled by default, and no data will ever be sent without your explicit consent. In fact, the error tracking method will not even be imported unless you have actively enabled it. Sentry is used for this, it's an open source error tracking and performance monitoring tool, which is used to identify any issues which occur in the production app (if you enable it).

The crash report includes the file or line of code that triggered the error, and a 2-layer deep stack trace. Reoccurring errors will also include the following user information: OS type (Mac, Windows, Linux, Android or iOS) and browser type (Firefox, Chrome, IE, Safari). Data scrubbing is enabled. IP address will not be stored. If any potentially identifiable data ever finds its way into a crash report, it will be automatically and permanently erased. All statistics collected are anonomized and stored securely, and ae automatically deleted after 14 days. For more about privacy and security, see the Sentry Docs.

Enabling anonymous error reporting helps me to discover bugs I was unaware of, and then fix them, in order to make Dashy more reliable long term. Error reporting is activated by setting appConfig.enableErrorReporting: true.

If you need to monitor bugs yourself, then you can self-host your own Sentry Server, and use it by setting appConfig.sentryDsn to your Sentry instances Data Source Name, then just enable error reporting in Dashy.

Widgets#

Local Storage#

In order for user preferences to be persisted between sessions, certain data needs to be stored in the browsers local storage. No personal info is kept here, none of this data can be accessed by other domains, and no data is ever sent to any server without your prior consent. You can view your browsers session storage by opening up the dev tools (F12) --> Application --> Storage.

The following section outlines all data that is stored in the browsers, as cookies or local storage.

Cookies#

  • AUTH_TOKEN - A unique token, generated from a hash of users credentials, to verify they are authenticated. Only used when auth is enabled

Local Storage#

  • LANGUAGE - The locale to show app text in
  • HIDE_WELCOME_BANNER - Set to true once user dismissed welcome message, so that it's not shown again
  • 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 - 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. 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

Dependencies#

As with most web projects, Dashy relies on several dependencies. For links to each, and a breakdown of their licenses, please see Legal.

Dependencies can introduce security vulnerabilities, but since all these packages are open source any issues are usually very quickly spotted. Dashy is using Snyk for dependency security monitoring, and you can see the latest report here. If any issue is detected by Snyk, a note about it will appear at the top of the Reamde, and will usually be fixed within 48 hours.

Note that packages listed under devDependencies section are only used for building the project, and are not included in the production environment.

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.

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
  • Configure authentication to prevent unauthorized access
  • Keep your system, software and Dashy up-to-date
  • Ensure your server is appropriately secured
  • Manage users and SSH correctly
  • Enable and configure firewall rules
  • Implement security, malware and traffic scanning
  • Setup malicious traffic detection
  • Understand the Docker attack fronts, and follow Docker Security Best Practices

This is covered in more detail in App Management.

Security Features#

Subresource Integrity#

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. 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. You should receive a response within 48 hours.

All non-critical issues can be raised as a ticket.

Please include the following information:

  • Type of issue (e.g. buffer overflow, SQL injection, cross-site scripting, etc.)
  • Full paths of source file(s) related to the manifestation of the issue
  • The location of the affected source code (tag/branch/commit or direct URL)
  • Any special configuration required to reproduce the issue
  • Step-by-step instructions to reproduce the issue
  • Proof-of-concept or exploit code (if possible)
  • Impact of the issue, including how an attacker might exploit the issue
- + \ No newline at end of file diff --git a/docs/quick-start/index.html b/docs/quick-start/index.html index 305324e7..bdfc7987 100644 --- a/docs/quick-start/index.html +++ b/docs/quick-start/index.html @@ -5,7 +5,7 @@ Quick Start | Dashy - + @@ -14,7 +14,7 @@ If you don't want to use Docker, then you can use one of Dashy's other supported installation methods instead, all of which are outlined in the Deployment Docs.

2. Installation#

To pull the latest image, and build and start the app run:

docker run -d \  -p 8080:80 \  -v ~/my-conf.yml:/app/public/conf.yml \  --name my-dashboard \  --restart=always \  lissy93/dashy:latest

Either replace the -v path to point to your config file, or leave it out. For a full list of available options, then see Dashy with Docker Docs. If you'd prefer to use Docker Compose, then see Dashy with Docker Compose Docs. Alternate registries, architectures and pinned versions are also supported.

Your dashboard should now be up and running at http://localhost:8080 (or your servers IP address/ domain, and the port that you chose). The first time you build, it may take a few minutes.

3. Configure#

Now that you've got Dashy running, you are going to want to set it up with your own content. Config is written in YAML Format, and saved in /public/conf.yml. The format on the config file is pretty straight forward. There are three root attributes:

  • pageInfo - Dashboard meta data, like title, description, nav bar links and footer text
  • appConfig - Dashboard settings, like themes, authentication, language and customization
  • sections - An array of sections, each including an array of items

You can view a full list of all available config options in the Configuring Docs.

pageInfo:  title: Home Labsections: # An array of sections- name: Example Section  icon: far fa-rocket  items:  - title: GitHub    description: Dashy source code and docs    icon: fab fa-github    url: https://github.com/Lissy93/dashy  - title: Issues    description: View open issues, or raise a new one    icon: fas fa-bug    url: https://github.com/Lissy93/dashy/issues- name: Local Services  items:  - title: Firewall    icon: favicon    url: http://192.168.1.1/  - title: Game Server    icon: https://i.ibb.co/710B3Yc/space-invader-x256.png    url: http://192.168.130.1/

Notes:

  • You can use a Docker volume to pass a config file from your host system to the container
    • E.g. -v ./host-system/my-local-conf.yml:/app/public/conf.yml
  • It's also possible to edit your config directly through the UI, and changes will be saved in this file
  • Check your config against Dashy's schema, with docker exec -it [container-id] yarn validate-config
  • You might find it helpful to look at some examples, a collection of which can be found here
  • After editing your config, the app will rebuild in the background, which may take a minute

4. Further Customisation#

Once you've got Dashy setup, you'll want to ensure the container is properly healthy, secured, backed up and kept up-to-date. All this is covered in the Management Docs.

You might also want to check out the docs for specific features you'd like to use:

  • Authentication - Setting up authentication to protect your dashboard
  • Alternate Views - Using the startpage and workspace view
  • Backup & Restore - Guide to Dashy's cloud sync feature
  • Icons - Outline of all available icon types for sections and items
  • Localisation - How to change language, or add your own
  • Status Indicators - Using Dashy to monitor uptime and status of your apps
  • Search & Shortcuts - Using instant filter, web search and custom hotkeys
  • Theming - Complete guide to applying, writing and modifying themes and styles

5. Final Note#

If you need any help or support in getting Dashy running, head over to the Discussions page. If you think you've found a bug, please do raise it so it can be fixed. For contact options, see the Support Page.

If you're enjoying Dashy, and have a few minutes to spare, please do take a moment to look at the Contributing Page. Huge thanks to everyone who has already helped out!

Enjoy your dashboard :)

Alternative Deployment Method 1 - From Source#

You can also easily run the app on your system without Docker. For this Git, Node.js, and Yarn are required.

git clone https://github.com/Lissy93/dashy.git && cd dashyyarn # Install dependenciesyarn build # Build the appyarn start # Start the app

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). All you need it a GitHub account.

  1. Fork Dashy's repository on GitHub
  2. Log in 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

Alternative Deployment Method 3 - Cloud Services#

Dashy supports 1-Click deployments on several popular cloud platforms. To spin up a new instance, just click a link below:

- + \ No newline at end of file diff --git a/docs/readme/index.html b/docs/readme/index.html index 097ce04b..6057b5ad 100644 --- a/docs/readme/index.html +++ b/docs/readme/index.html @@ -5,13 +5,13 @@ readme | Dashy - +

readme

Dashy Docs

Running Dashy#

  • Quick Start - TDLR guide on getting Dashy up and running
  • Deployment - Full guide on deploying Dashy either locally or online
  • Configuring - Complete list of all available options in the config file
  • App Management - Managing your app, updating, security, web server configuration, etc
  • Troubleshooting - Common errors and problems, and how to fix them

Development and Contributing#

  • Developing - Running Dashy development server locally, and general workflow
  • Development Guides - Common development tasks, to help new contributors
  • Contributing - How you can help keep Dashy alive
  • Showcase - See how others are using Dashy, and share your dashboard
  • Credits - List of people and projects that have made Dashy possible
  • Release Workflow - Info about releases, CI and automated tasks

Feature Docs#

  • Authentication - Guide to setting up authentication to protect your dashboard
  • Alternate Views - Outline of available pages / views and item opening methods
  • Backup & Restore - Guide to backing up config with Dashy's cloud sync feature
  • Icons - Outline of all available icon types for sections and items, with examples
  • Language Switching - Details on how to switch language, or add a new locale
  • Status Indicators - Using Dashy to monitor uptime and status of your apps
  • Searching & Shortcuts - Searching, launching methods + keyboard shortcuts
  • Theming - Complete guide to applying, writing and modifying themes + styles
  • Widgets - List of all dynamic content widgets, with usage guides and examples

Misc#

- + \ No newline at end of file diff --git a/docs/release-workflow/index.html b/docs/release-workflow/index.html index 3eb59c4a..9b6a429a 100644 --- a/docs/release-workflow/index.html +++ b/docs/release-workflow/index.html @@ -5,14 +5,14 @@ Releases and Workflows | Dashy - +

Releases and Workflows

Release Schedule#

We're using Semantic Versioning, 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 file.

Typically there is a new major release every 2 weeks, usually on Sunday, and you can view these under the Releases Page. Each new version will also have a corresponding tag on GitHub, and each major release will also result in the creation of a new tag on DockerHub, so that you can fix your container to a certain version.

For a full breakdown of each change, you can view the 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

Netlify Status

Git Strategy#

Git Flow#

Like most Git repos, we are following the Github 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

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 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#

ActionDescription
Code Linter
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
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
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
get-size.yml		Adds comment to PR if the size of the built + bundled application has changed compared to the previous version
Security Scan
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#

ActionDescription
Create Tag
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
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
cache-artifacts.yml		After build, returned files will be cached for future actions for that commit
Docker Publish
docker-publish.yml		After PR is merged, the multi-architecture Docker container will be built, and then published to GHCR

Issue Management#

ActionDescription
Close Incomplete Issues
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
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
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
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
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
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
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
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
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
add-comment-from-tag.yml		Will add comment with useful info to certain issues, based on the tag applied

PR Management#

ActionDescription
PR Commenter
pr-commenter.yml		Adds comment with helpful info to pull requests, based on which files have been changes
Issue from Todo Code
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#

ActionDescription
Generate Credits
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		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/searching/index.html b/docs/searching/index.html index b4de1357..99fe6543 100644 --- a/docs/searching/index.html +++ b/docs/searching/index.html @@ -5,7 +5,7 @@ Keyboard Shortcuts | Dashy - + @@ -13,7 +13,7 @@

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 Tab to cycle through results, and Shift + Tab to go backwards. Or use the arrow keys, ↑, →, ↓ and ←.

Launching Apps#

You can launch a elected app by hitting Enter. This will open the app using your default opening method, specified in target (either newtab, sametab, modal, top or workspace). You can also use Alt + Enter to open the app in a pop-up modal, or Ctrl + Enter 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. 

  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.

- 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 2 will launch Bookstack. Or hitting 3 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 ⏎. 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:

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 or Searx). Set searchEngine: custom, and then specify the URL (plus query params) to you're search engine under customSearchEngine.

For example: 

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, 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:

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:

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 Esc. This can also be used to close any open pop-up modals.

- + \ No newline at end of file diff --git a/docs/showcase/index.html b/docs/showcase/index.html index 7c924873..4eec7420 100644 --- a/docs/showcase/index.html +++ b/docs/showcase/index.html @@ -5,7 +5,7 @@ *Dashy Showcase* 🌟 | Dashy - + @@ -16,7 +16,7 @@ ![dashboard-screenshot](https://example.com/url-to-screenshot.png) (required) ---
- + \ No newline at end of file diff --git a/docs/showcase/readme/index.html b/docs/showcase/readme/index.html index 00066882..3f00ef86 100644 --- a/docs/showcase/readme/index.html +++ b/docs/showcase/readme/index.html @@ -5,13 +5,13 @@ readme | Dashy - +
- + \ No newline at end of file diff --git a/docs/status-indicators/index.html b/docs/status-indicators/index.html index 18a28537..410b130a 100644 --- a/docs/status-indicators/index.html +++ b/docs/status-indicators/index.html @@ -5,7 +5,7 @@ Status Indicators | Dashy - + @@ -14,7 +14,7 @@ For example, statusCheckHeaders: { 'X-Custom-Header': 'foobar' }

Disabling Security#

By default, (if you're using HTTPS) any requests to insecure or non-HTTPS content will be blocked. This will cause the status check to fail. If you trust the endpoint (e.g. you're self-hosting it), then you can disable this security measure for an individual item. This is done by setting statusCheckAllowInsecure: true

Troubleshooting Failing Status Checks#

If the status is always returning an error, despite the service being online, then it is most likely an issue with access control, and should be fixed with the correct headers. Hover over the failing status to see the error code and response, in order to know where to start with addressing it. If your service requires requests to include any authorization in the headers, then use the statusCheckHeaders property, as described above. 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, and can be fixed by setting the headers on your target app, to include:

Access-Control-Allow-Origin: https://[dashy-location]/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 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 to diagnose the issue. Set the parameter to GET, and then make a call to: https://[url-of-dashy]/status-check/?&url=[service-url]. Where the service URL must have first been encoded (e.g. with encodeURIComponent() or 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#

When the app is loaded, if appConfig.statusCheck: true is set, or if any items have the statusCheck: true enabled, then Dashy will make a request, to https://[your-host-name]/status-check?url=[address-or-servce] (may al include GET params for headers and the secure flag), which in turn will ping that running service, and respond with a status code. Response time is calculated from the difference between start and end time of the request.

When the response completes, an indicator will display next to each item. The color denotes the status: Yellow while waiting for the response to return, green if request was successful, red if it failed, and grey if it was unable to make the request all together.

All requests are made straight from your server, there is no intermediary. So providing you are hosting Dashy yourself, and are checking the status of other self-hosted services, there shouldn't be any privacy concerns. Requests are made asynchronously, so this won't have any significant impact on page load speeds. However recurring requests (using statusCheckInterval) may run more slowly if the interval between requests is very short.

- + \ No newline at end of file diff --git a/docs/theming/index.html b/docs/theming/index.html index a271f6f2..639d9cf6 100644 --- a/docs/theming/index.html +++ b/docs/theming/index.html @@ -5,14 +5,14 @@ theming | Dashy - +

theming

Theming#

By default Dashy comes with 20 built in themes, which can be applied from the dropwodwn menu in the UI

Built-in Themes

You can also add your own themes, apply custom styles, and modify colors.

You can customize Dashy by writing your own CSS, which can be loaded either as an external stylesheet, set directly through the UI, or specified in the config file. Most styling options can be set through CSS variables, which are outlined below.

The following content requires that you have a basic understanding of CSS. If you're just beginning, you may find this article helpful.

How Theme-Switching Works#

The theme switching is done by simply changing the data-theme attribute on the root DOM element, which can then be targeted by CSS. First off, in order for the theme to show up in the theme switcher, it needs to be added to the config file, under appConfig.cssThemes, either as a string, or an array of strings for multiple themes. For example:

appConfig:  cssThemes: ['tiger', 'another-theme']

You can now create a block to target you're theme with html[data-theme='my-theme']{} and set some styles. The easiest method is by setting CSS variables, but you can also directly override elements by their selector. As an example, see the built-in CSS themes.

html[data-theme='tiger'] {  --primary: #f58233;  --background: #0b1021;}

Finally, from the UI use the theme dropdown menu to select your new theme, and your styles will be applied.

You can also set appConfig.theme to pre-select a default theme, which will be applied immediately after deployment.

Modifying Theme Colors#

Themes can be modified either through the UI, using the color picker menu (to the right of the theme dropdown), or directly in the config file, under appConfig.customColors. Here you can specify the value for any of the available CSS variables.

Example Themes

By default, any color modifications made to the current theme through the UI will only be applied locally. If you need these settings to be set globally, then click the 'Export' button, to get the color codes and variable names, which can then be backed up, or saved in your config file.

Custom colors are saved relative the the base theme selected. So if you switch themes after setting custom colors, then you're settings will no longer be applied. You're changes are not lost though, and switching back to the original theme will see your styles reapplied.

If these values are specified in your conf.yml file, then it will look something like the below example. Note that in YAML, values or keys which contain special characters, must be wrapped in quotes.

appConfig:  customColors:    oblivion:      primary: '#75efff'      background: '#2a3647'    dracula:      primary: '#8be9fd'

Adding your own Theme#

User-defined styles and custom themes should be defined in ./src/styles/user-defined-themes.scss. If you're using Docker, you can pass your own stylesheet in using the --volume flag. E.g. v ./my-themes.scss:/app/src/styles/user-defined-themes.scss. Don't forget to pass your theme name into appConfig.cssThemes so that it shows up on the theme-switcher dropdown.

Setting Custom CSS in the UI#

Custom CSS can be developed, tested and applied directly through the UI. Although you will need to make note of your changes to apply them across instances.

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.

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). This is handled in ThemeHelper.js.

For example:

appConfig:  externalStyleSheet: 'https://example.com/my-stylesheet.css'
appConfig:  externalStyleSheet: ['/themes/my-theme-1.css', '/themes/my-theme-2.css']

Hard-Coding Section or Item Colors#

Some UI components have a color option, that can be set in the config file, to force the color of a given item or section no matter what theme is selected. These colors should be expressed as hex codes (e.g. #fff) or HTML colors (e.g. red). The following attributes are supported:

  • section.color - Custom color for a given section
  • item.color - Font and icon color for a given item
  • item.backgroundColor - Background color for a given icon

Typography#

Essential fonts bundled within the app are located within ./src/assets/fonts/. All optional fonts that are used by themes are stored in ./public/fonts/, if you want to add your own font, this is where you should put it. As with assets, if you're using Docker then using a volume to link a directory on your host system with this path within the container will make management much easier.

Fonts which are not being used by the current theme are not fetched on page load. They are instead only loaded into the application if and when they are required. So having multiple themes with various typefaces shouldn't have any negative impact on performance.

Full credit to the typographers behind each of the included fonts. Specifically: Matt McInerney, Christian Robertson, Haley Fiege, Peter Hull, Cyreal and the legendary Vernon Adams

CSS Variables#

All colors as well as other variable values (such as borders, border-radius, shadows) are specified as CSS variables. This makes theming the application easy, as you only need to change a given color or value in one place. You can find all variables in color-palette.scss and the themes which make use of these color variables are specified in color-themes.scss

CSS variables are simple to use. You define them like: --background: #fff; and use them like: body { background-color: var(--background); }. For more information, see this guide on using CSS Variables.

You can determine the variable used by any given element, and visualize changes using the browser developer tools (Usually opened with F12, or Options --> More --> Developer Tools). Under the elements tab, click the Element Selector icon (usually top-left corner), you will then be able to select any DOM element on the page by hovering and clicking it. In the CSS panel you will see all styles assigned to that given element, including CSS variables. Click a variable to see it's parent value, and for color attributes, click the color square to modify the color. For more information, see this getting started guide, and these articles on selecting elements and inspecting and modifying colors.

Top-Level Variables#

These are all that are required to create a theme. All other variables inherit their values from these variables, and can optionally be overridden.

  • --primary - Application primary color. Used for title, text, accents, and other features
  • --background - Application background color
  • --background-darker - Secondary background color (usually darker), used for navigation bar, section fill, footer etc
  • --curve-factor - The border radius used globally throughout the application. Specified in px, defaults to 5px
  • --dimming-factor - Inactive elements have slight transparency. This can be between 0 (invisible) and 1 (normal), defaults to 0.7

Targeted Color Variables#

You can target specific elements on the UI with these variables. All are optional, since by default, they inherit their values from above

  • --heading-text-color - Text color for web page heading and sub-heading. Defaults to --primary
  • --nav-link-text-color - The text color for links displayed in the navigation bar. Defaults to --primary
  • --nav-link-background-color - The background color for links displayed in the navigation bar
  • --nav-link-text-color-hover - The text color when a navigation bar link is hovered over. Defaults to --primary
  • --nav-link-background-color-hover - The background color for nav bar links when hovered over
  • --nav-link-border-color - The border color for nav bar links. Defaults to transparent
  • --nav-link-border-color-hover - The border color for nav bar links when hovered over. Defaults to --primary
  • --search-container-background - Background for the container containing the search bar. Defaults to --background-darker
  • --search-field-background - Fill color for the search bar. Defaults to --background
  • --settings-background - The background for the quick settings. Defaults to --background
  • --settings-text-color - The text and icon color for quick settings. Defaults to --primary
  • --footer-text-color - Color for text within the footer. Defaults to --medium-grey
  • --footer-text-color-link - Color for any hyperlinks within the footer. Defaults to --primary
  • --item-text-color - The text and icon color for items. Defaults to --primary
  • --item-group-outer-background - The background color for the outer part of a section (including section head). Defaults to --primary
  • --item-group-background - The background color for the inner part of item groups. Defaults to #0b1021cc (semi-transparent black)
  • --item-group-heading-text-color - The text color for section headings. Defaults to --item-group-background;
  • --item-group-heading-text-color-hover - The text color for section headings, when hovered. Defaults to --background
  • --config-code-background - Background color for the JSON editor in the config menu. Defaults to #fff (white)
  • --config-code-color - Text color for the non-highlighted code within the JSON editor. Defaults to --background
  • --config-settings-color - The background for the config/ settings pop-up modal. Defaults to --primary
  • --config-settings-background - The text color for text within the settings container. Defaults to --background-darker
  • --scroll-bar-color - Color of the scroll bar thumb. Defaults to --primary
  • --scroll-bar-background Color of the scroll bar blank space. Defaults to --background-darker
  • --highlight-background Fill color for text highlighting. Defaults to --primary
  • --highlight-color Text color for selected/ highlighted text. Defaults to --background
  • --toast-background - Background color for the toast info popup. Defaults to --primary
  • --toast-color - Text, icon and border color in the toast info popup. Defaults to --background
  • --welcome-popup-background - Background for the info pop-up shown on first load. Defaults to --background-darker
  • --welcome-popup-text-color - Text color for the welcome pop-up. Defaults to --primary
  • --side-bar-background - Background color of the sidebar used in the workspace view. Defaults to --background-darker
  • --side-bar-color - Color of icons and text within the sidebar. Defaults to --primary
  • --status-check-tooltip-background - Background color for status check tooltips. Defaults to --background-darker
  • --status-check-tooltip-color - Text color for the status check tooltips. Defaults to --primary
  • --code-editor-color - Text color used within raw code editors. Defaults to --black
  • --code-editor-background - Background color for raw code editors. Defaults to --white
  • --context-menu-color - Text color for right-click context menu over items. Defaults to --primary
  • --context-menu-background - Background color of right-click context menu. Defaults to --background
  • --context-menu-secondary-color - Border and outline color for context menu. Defaults to --background-darker

Non-Color Variables#

  • --outline-color - Used to outline focused or selected elements
  • --curve-factor-navbar - The border radius of the navbar. Usually this is greater than --curve-factor
  • --scroll-bar-width - Width of horizontal and vertical scroll bars. E.g. 8px
  • --item-group-padding - Inner padding of sections, determines the width of outline. E.g. 5px
  • --item-shadow - Shadow for items. E.g. 1px 1px 2px #130f23
  • --item-hover-shadow - Shadow for items when hovered over. E.g. 1px 2px 4px #373737
  • --item-icon-transform - A transform property, to modify item icons. E.g. drop-shadow(2px 4px 6px var(--transparent-50)) saturate(0.65)
  • --item-icon-transform-hover - Same as above, but applied when an item is hovered over. E.g. drop-shadow(4px 8px 3px var(--transparent-50)) saturate(2)
  • --item-group-shadow - The shadow for an item group/ section. Defaults to --item-shadow
  • --settings-container-shadow - A shadow property for the settings container. E.g. none

Action Colors#

These colors represent intent, and so are not often changed, but you can do so if you wish

  • --info - Information color, usually blue / #04e4f4
  • --success - Success color, usually green / #20e253
  • --warning - Warning color, usually yellow / #f6f000
  • --danger - Error/ danger color, usually red / #f80363
  • --neutral - Neutral color, usually grey / #272f4d
  • --white - Just white / #fff
  • --black - Just black / #000
- + \ No newline at end of file diff --git a/docs/troubleshooting/index.html b/docs/troubleshooting/index.html index 8099db5c..bdd9a093 100644 --- a/docs/troubleshooting/index.html +++ b/docs/troubleshooting/index.html @@ -5,16 +5,17 @@ Troubleshooting | Dashy - +
-

Troubleshooting

This document contains common problems and their solutions.

If you came across an issue where the solution was not immediately obvious, consider adding it to this list to help other users.

Contents#

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. It can be fixed by setting the X-Frame-Options HTTP header set to ALLOW [path to Dashy] or SAMEORIGIN, as defined in RFC-7034. These settings are usually set in the config file for the web server that's hosting the target application, here are some examples of how to enable cross-origin access with common web servers:

NGINX#

In NGINX, you can use the add_header module within the app block.

server {  ...  add_header X-Frame-Options SAMEORIGIN always;}

Then reload with service nginx reload

Caddy#

In Caddy, you can use the header directive.

header {  X-Frame-Options SAMEORIGIN}

Apache#

In Apache, you can use the mod_headers module to set the X-Frame-Options in your config file. This file is usually located somewhere like `/etc/apache2/httpd.conf

Header set X-Frame-Options: "ALLOW-FROM http://[dashy-location]/"

404 On Static Hosting#

If you're seeing Dashy's 404 page on initial load/ refresh, and then the main app when you go back to Home, then this is likely caused by the Vue router, and if so can be fixed in one of two ways.

The first solution is to switch the routing mode, from HTML5 history mode to hash mode, by setting appConfig.routingMode to hash.

If this works, but you wish to continue using HTML5 history mode, then a bit of extra server configuration is required. This is explained in more detaail in the Vue Docs. Once completed, you can then use routingMode: history again, for neater URLs.

Yarn Error#

For more info, see Issue #1

First of all, check that you've got yarn installed correctly - see the yarn installation docs for more info.

If you're getting an error about scenarios, then you've likely installed the wrong yarn... (you're not the only one!). You can fix it by uninstalling, adding the correct repo, and reinstalling, for example, in Debian:

  • sudo apt remove yarn
  • curl -sS https://dl.yarnpkg.com/debian/pubkey.gpg | sudo apt-key add -
  • echo "deb https://dl.yarnpkg.com/debian/ stable main" | sudo tee /etc/apt/sources.list.d/yarn.list
  • sudo apt update && sudo apt install yarn

Alternatively, as a workaround, you have several options:

  • Try using NPM instead: So clone, cd, then run npm install, npm run build and npm start
  • Try using Docker instead, and all of the system setup and dependencies will already be taken care of. So from within the directory, just run docker build -t lissy93/dashy . to build, and then use docker start to run the project, e.g: docker run -it -p 8080:80 lissy93/dashy (see the deploying docs for more info)

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.

For more info, see this announcement.

You can fix this by replacing:

auth:- user: xxx  hash: xxx

with

auth:  users:  - user: xxx    hash: xxx

Config Not Updating#

Dashy has the option to save settings and config locally, in browser storage. Anything here will take precedence over whatever is in your config file, sometimes with unintended consequences. If you've updated the config file manually, and are not seeing changes reflected in the UI, then try visiting the site in Incognito mode. If that works, then the solution is just to clear local storage. This can be done from the config menu, under "Clear Local Settings".

Config Still not Updating#

Sometimes your text editor updates files inode, meaning changes will not be picked up by the Docker container. This article explains things further.

Styles and Assets not Updating#

If you find that your styles and other visual assets work when visiting ip:port by not dashy.domain.com, then this is usually caused by caching. In your browser, do a hard-refresh (Ctrl + F5). If you use Cloudflare, then you can clear the cache through the management console, or set the cache level to Bypass for certain files, under the Rules tab.

DockerHub toomanyrequests#

This situation relates to error messages similar to one of the following, returned when pulling, updating or running the Docker container from Docker Hub.

Continuing execution. Pulling image lissy93/dashy:release-1.6.0 error pulling image configuration: toomanyrequests

or

You have reached your pull rate limit. You may increase the limit by authenticating and upgrading: https://www.docker.com/increase-rate-limit

When DockerHub returns one of these errors, or a 429 status, that means you've hit your rate limit. This was introduced last year, and prevents unauthenticated or free users from running docker pull more than 100 times per 6 hours. +

Troubleshooting

This document contains common problems and their solutions.

If you came across an issue where the solution was not immediately obvious, consider adding it to this list to help other users.

Contents#

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. It can be fixed by setting the X-Frame-Options HTTP header set to ALLOW [path to Dashy] or SAMEORIGIN, as defined in RFC-7034. These settings are usually set in the config file for the web server that's hosting the target application, here are some examples of how to enable cross-origin access with common web servers:

NGINX#

In NGINX, you can use the add_header module within the app block.

server {  ...  add_header X-Frame-Options SAMEORIGIN always;}

Then reload with service nginx reload

Caddy#

In Caddy, you can use the header directive.

header {  X-Frame-Options SAMEORIGIN}

Apache#

In Apache, you can use the mod_headers module to set the X-Frame-Options in your config file. This file is usually located somewhere like `/etc/apache2/httpd.conf

Header set X-Frame-Options: "ALLOW-FROM http://[dashy-location]/"

404 On Static Hosting#

If you're seeing Dashy's 404 page on initial load/ refresh, and then the main app when you go back to Home, then this is likely caused by the Vue router, and if so can be fixed in one of two ways.

The first solution is to switch the routing mode, from HTML5 history mode to hash mode, by setting appConfig.routingMode to hash.

If this works, but you wish to continue using HTML5 history mode, then a bit of extra server configuration is required. This is explained in more detaail in the Vue Docs. Once completed, you can then use routingMode: history again, for neater URLs.

Yarn Error#

For more info, see Issue #1

First of all, check that you've got yarn installed correctly - see the yarn installation docs for more info.

If you're getting an error about scenarios, then you've likely installed the wrong yarn... (you're not the only one!). You can fix it by uninstalling, adding the correct repo, and reinstalling, for example, in Debian:

  • sudo apt remove yarn
  • curl -sS https://dl.yarnpkg.com/debian/pubkey.gpg | sudo apt-key add -
  • echo "deb https://dl.yarnpkg.com/debian/ stable main" | sudo tee /etc/apt/sources.list.d/yarn.list
  • sudo apt update && sudo apt install yarn

Alternatively, as a workaround, you have several options:

  • Try using NPM instead: So clone, cd, then run npm install, npm run build and npm start
  • Try using Docker instead, and all of the system setup and dependencies will already be taken care of. So from within the directory, just run docker build -t lissy93/dashy . to build, and then use docker start to run the project, e.g: docker run -it -p 8080:80 lissy93/dashy (see the deploying docs for more info)

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.

For more info, see this announcement.

You can fix this by replacing:

auth:- user: xxx  hash: xxx

with

auth:  users:  - user: xxx    hash: xxx

Config Not Updating#

Dashy has the option to save settings and config locally, in browser storage. Anything here will take precedence over whatever is in your config file, sometimes with unintended consequences. If you've updated the config file manually, and are not seeing changes reflected in the UI, then try visiting the site in Incognito mode. If that works, then the solution is just to clear local storage. This can be done from the config menu, under "Clear Local Settings".

Config Still not Updating#

Sometimes your text editor updates files inode, meaning changes will not be picked up by the Docker container. This article explains things further.

Styles and Assets not Updating#

If you find that your styles and other visual assets work when visiting ip:port by not dashy.domain.com, then this is usually caused by caching. In your browser, do a hard-refresh (Ctrl + F5). If you use Cloudflare, then you can clear the cache through the management console, or set the cache level to Bypass for certain files, under the Rules tab.

DockerHub toomanyrequests#

This situation relates to error messages similar to one of the following, returned when pulling, updating or running the Docker container from Docker Hub.

Continuing execution. Pulling image lissy93/dashy:release-1.6.0 error pulling image configuration: toomanyrequests

or

You have reached your pull rate limit. You may increase the limit by authenticating and upgrading: https://www.docker.com/increase-rate-limit

When DockerHub returns one of these errors, or a 429 status, that means you've hit your rate limit. This was introduced last year, and prevents unauthenticated or free users from running docker pull more than 100 times per 6 hours. You can check your rate limit status by looking for the ratelimit-remaining header in any DockerHub responses.

Solution 1 - Use an alternate container registry#

  • Dashy is also availible through GHCR, which at present does not have any hard limits. Just use docker pull ghcr.io/lissy93/dashy:latest to fetch the image
  • You can also build the image from source, by cloning the repo, and running docker build -t dashy . or use the pre-made docker compose

Solution 2 - Increase your rate limits#

  • Logging in to DockerHub will increase your rate limit from 100 requests to 200 requests per 6 hour period
  • Upgrading to a Pro for $5/month will increase your image requests to 5,000 per day, and any plans above have no rate limits
  • Since rate limits are counted based on your IP address, proxying your requests, or using a VPN may work

Config Validation Errors#

The configuration file is validated against Dashy's Schema using AJV.

First, check that your syntax is valid, using YAML Validator or JSON Validator. If the issue persists, then take a look at the schema, and verify that the field you are trying to add/ modify matches the required format. You can also use this tool to validate your JSON config against the schema, or run yarn validate-config.

If you're trying to use a recently released feature, and are getting a warning, this is likely because you've not yet updated the the current latest version of Dashy.

If the issue still persists, you should raise an issue.

Node Sass does not yet support your current environment#

Caused by node-sass's binaries being built for a for a different architecture To fix this, just run: yarn rebuild node-sass

Error: Cannot find module './_baseValues'#

Clearing the cache should fix this: yarn cache clean -If the issue persists, remove (rm -rf node_modules\ yarn.lock) and reinstall (yarn) node_modules

Invalid Host Header while running through ngrok#

Just add the -host-header flag, e.g. ngrok http 8080 -host-header="localhost:8080"

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.

Docker Login Fails on Ubuntu#

Run sudo apt install gnupg2 pass && gpg2 -k

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.

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, 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 to diagnose the issue. Set the parameter to GET, and then make a call to: https://[url-of-dashy]/status-check/?&url=[service-url]. Where the service URL must have first been encoded (e.g. with encodeURIComponent() or 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-To Open Browser Console#

When raising a bug, one crucial piece of info needed is the browser's console output. This will help the developer diagnose and fix the issue.

If you've been asked for this info, but are unsure where to find it, then it is under the "Console" tab, in the browsers developer tools, which can be opened with F12. You can right-click the console, and select Save As to download the log.

To open dev tools, and jump straight to the console:

  • Win / Linux: Ctrl + Shift + J
  • MacOS: Cmd + Option + J

For more detailed walk through, see this article.

Git Contributions not Displaying#

If you've contributed to Dashy (or any other project), but your contributions are not showing up on your GH profile, or in Dashy's Credits Page, then this is likely a git config issue.

These statistics are generated using the username / email associated with commits. This info needs to be setup on your local machine using git config.

Run the following commands (replacing name + email with your info):

  • git config --global user.name "John Doe"
  • git config --global user.email johndoe@example.com

For more info, see Git First Time Setup Docs.

Note that only contributions to the master / main branch or a project are counted

- +If the issue persists, remove (rm -rf node_modules\ yarn.lock) and reinstall (yarn) node_modules

Invalid Host Header while running through ngrok#

Just add the -host-header flag, e.g. ngrok http 8080 -host-header="localhost:8080"

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.

Docker Login Fails on Ubuntu#

Run sudo apt install gnupg2 pass && gpg2 -k

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.

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, 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 to diagnose the issue. Set the parameter to GET, and then make a call to: https://[url-of-dashy]/status-check/?&url=[service-url]. Where the service URL must have first been encoded (e.g. with encodeURIComponent() or 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.

Widget Errors#

If an error occurs when fetching or rendering results, you will see a short message in the UI. If that message doesn't addequatley explain the problem, then you can open the browser console to see more details.

Before proceeding, ensure that if the widget requires auth your API is correct, and for custom widgets, double check that the URL and protocol is correct.

If the console message mentions to corss-origin blocking, then this is a CORS error, see: Fixing Widget CORS Errors

If you're able to, you can find more information about why the request may be failing in the Dev Tools under the Network tab, and you can ensure your endpoint is correct and working using a tool like Postman.

Widget CORS Errors#

The most common widget issue is a CORS error. This is a browser security mechanism which prevents the client-side app (Dashy) from from accessing resources on a remote origin, without that server's explicit permission (e.g. with headers like Access-Control-Allow-Origin). See the MDN Docs for more info: Cross-Origin Resource Sharing.

There are several ways to fix a CORS error:

Option 1 - Ensure Correct Protocol#

You will get a CORS error if you try and access a http service from a https source. So ensure that the URL you are requesting has the right protocol, and is correctly formatted.

Option 2 - Set Headers#

If you have control over the destination (e.g. for a self-hosted service), then you can simply apply the correct headers. +Add the Access-Control-Allow-Origin header, with the value of either * to allow requests from anywhere, or more securely, the host of where Dashy is served from. For example:

Access-Control-Allow-Origin: https://url-of-dashy.local

or

Access-Control-Allow-Origin: *

Option 3 - Proxying Request#

You can route requests through Dashy's built-in CORS proxy. Instructions and more details can be found here. 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.

Option 4 - Use a plugin#

For testing purposes, you can use an addon, which will disable the CORS checks. You can get the Allow-CORS extension for Chrome or Firefox, more details here

How-To Open Browser Console#

When raising a bug, one crucial piece of info needed is the browser's console output. This will help the developer diagnose and fix the issue.

If you've been asked for this info, but are unsure where to find it, then it is under the "Console" tab, in the browsers developer tools, which can be opened with F12. You can right-click the console, and select Save As to download the log.

To open dev tools, and jump straight to the console:

  • Win / Linux: Ctrl + Shift + J
  • MacOS: Cmd + Option + J

For more detailed walk through, see this article.

Git Contributions not Displaying#

If you've contributed to Dashy (or any other project), but your contributions are not showing up on your GH profile, or in Dashy's Credits Page, then this is likely a git config issue.

These statistics are generated using the username / email associated with commits. This info needs to be setup on your local machine using git config.

Run the following commands (replacing name + email with your info):

  • git config --global user.name "John Doe"
  • git config --global user.email johndoe@example.com

For more info, see Git First Time Setup Docs.

Note that only contributions to the master / main branch or a project are counted

+ \ No newline at end of file diff --git a/docs/widgets/index.html b/docs/widgets/index.html index fc361591..4fd79c5a 100644 --- a/docs/widgets/index.html +++ b/docs/widgets/index.html @@ -5,17 +5,18 @@ Widgets | Dashy - +

Widgets

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#

Clock#

A simple, live-updating time and date widget with time-zone support. All fields are optional.

Options#
FieldTypeRequiredDescription
timeZonestringOptionalThe time zone to display date and time in.
Specified as Region/City, for example: Australia/Melbourne. See the Time Zone DB for a full list of supported TZs. Defaults to the browser / device's local time
formatstringOptionalA country code for displaying the date and time in local format.
Specified as [ISO-3166]-[ISO-639], for example: en-AU. See here for a full list of locales. Defaults to the browser / device's region
customCityNamestringOptionalBy default the city from the time-zone is shown, but setting this value will override that text
hideDatebooleanOptionalIf set to true, the date and city will not be shown. Defaults to false
Example#
- type: clock  options:    timeZone: Europe/London    format: en-GB    hideDate: false
Info#

No external data requests

Weather#

A simple, live-updating local weather component, showing temperature, conditions and more info.

Options#
FieldTypeRequiredDescription
apiKeystringRequiredYour OpenWeatherMap API key. You can get one for free at openweathermap.org
citystringRequiredA city name to use for fetching weather. This can also be a state code or country code, following the ISO-3166 format
unitsstringOptionalThe units to use for displaying data, can be either metric or imperial. Defaults to metric
hideDetailsbooleanOptionalIf set to true, the additional details (wind, humidity, pressure, etc) will not be shown. Defaults to false
Example#
- type: weather  options:    apiKey: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx    city: London    units: metric    hideDetails: false
Info#

Weather Forecast#

Displays the weather (temperature and conditions) for the next few days for a given location. Note that this requires either the free OpenWeatherMap Student Plan, or the Premium Plan.

Options#
FieldTypeRequiredDescription
apiKeystringRequiredYour OpenWeatherMap API key. You can get one at openweathermap.org or for free via the OWM Student Plan
citystringRequiredA city name to use for fetching weather. This can also be a state code or country code, following the ISO-3166 format
numDaysnumberOptionalThe number of days to display of forecast info to display. Defaults to 4, max 16 days
unitsstringOptionalThe units to use for displaying data, can be either metric or imperial. Defaults to metric
hideDetailsbooleanOptionalIf set to true, the additional details (wind, humidity, pressure, etc) will not be shown. Defaults to false
Example#
- type: weather-forecast  options:    city: California    numDays: 6    apiKey: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx    units: imperial
Info#
  • CORS: 🟢 Enabled
  • Auth: 🔴 Required
  • Price: 🔴 Premium (free for personal use only)
  • Privacy: See OWM Privacy Policy

RSS Feed#

Display news and updates from any RSS-enabled service.

Options#
FieldTypeRequiredDescription
rssUrlstringRequiredThe URL location of your RSS feed
apiKeystringOptionalAn API key for rss2json. It's free, and will allow you to make 10,000 requests per day, you can sign up here
limitnumberOptionalThe number of posts to return. If you haven't specified an API key, this will be limited to 10
orderBystringOptionalHow results should be sorted. Can be either pubDate, author or title. Defaults to pubDate
orderDirectionstringOptionalOrder direction of feed items to return. Can be either asc or desc. Defaults to desc
Example#
- type: rss-feed  options:    rssUrl: https://www.schneier.com/blog/atom.xml    apiKey: xxxx
Info#
  • CORS: 🟢 Enabled
  • Auth: 🟠 Optional
  • Price: 🟠 Free Plan (up to 10,000 requests / day)
  • Privacy: See Rss2Json Privacy Policy

Public IP#

Often find yourself searching "What's my IP", just so you can check your VPN is still connected? This widget displays your public IP address, along with ISP name and approx location. Data is fetched from IP-API.com.

Options#

No config options.

Example#
- type: public-ip
Info#
  • CORS: 🟢 Enabled
  • Auth: 🟠 Optional
  • Price: 🟢 Free
  • Host: Managed Instance Only
  • Privacy: See IP-API Privacy Policy

Crypto Watch List#

Keep track of price changes of your favorite crypto assets. Data is fetched from CoinGecko. All fields are optional.

Options#
FieldTypeRequiredDescription
assetsstringOptionalAn array of cryptocurrencies, coins and tokens. See list of supported assets. If none are specified, then the top coins by sortBy (defaults to market cap) will be returned
currencystringOptionalThe fiat currency to display price in, expressed as an ISO-4217 alpha code (see list of currencies). Defaults to USD
sortBystringOptionalThe method of sorting results. Can be marketCap, volume or alphabetical. Defaults to marketCap.
limitnumberOptionalNumber of results to return, useful when no assets are specified. Defaults to either all or 100
Example#
- type: crypto-watch-list  options:    limit: 10

Or

  - type: crypto-watch-list    options:      currency: GBP      sortBy: marketCap      assets:      - bitcoin      - ethereum      - monero      - cosmos      - polkadot      - dogecoin
Info#

Crypto Token Price History#

Shows recent price history for a given crypto asset, using price data fetched from CoinGecko

Options#
FieldTypeRequiredDescription
assetstringRequiredName of a crypto asset, coin or token to fetch price data for, see list of supported assets
currencystringOptionalThe fiat currency to display results in, expressed as an ISO-4217 alpha code (see list of currencies). Defaults to USD
numDaysnumberOptionalThe number of days of price history to render. Defaults to 7, min: 1, max: 30 days
chartColorstringOptionalColor of the chart value. Defaults to --widget-text-color which inherits dashboard primary color
chartHeightnumberOptionalThe height of rendered chart in px. Defaults to 300
Example#
- type: crypto-price-chart  options:    asset: bitcoin    currency: GBP    numDays: 7
Info#

Wallet Balance#

Keep track of your crypto balances and see recent transactions. Data is fetched from BlockCypher

Options#
FieldTypeRequiredDescription
coinstringRequiredSymbol of coin or asset, e.g. btc, eth or doge
addressstringRequiredAddress to monitor. This is your wallet's public / receiving address
networkstringOptionalTo use a different network, other than mainnet. Defaults to main
limitnumberOptionalLimit the number of transactions to display. Defaults to 10, set to large number to show all
Example#
- type: wallet-balance  options:    coin: btc    address: 3853bSxupMjvxEYfwGDGAaLZhTKxB2vEVC
Info#

Code Stats#

Display your coding summary. Code::Stats is a free and open source app that aggregates statistics about your programming activity. Dashy supports both the public instance, as well as self-hosted versions.

Options#
FieldTypeRequiredDescription
usernamestringRequiredYour CodeStats username
hostnamestringOptionalIf your self-hosting CodeStats, then supply the host name. By default it will use the public hosted instance
monthsToShownumberOptionalSpecify the number of months to render in the historical data chart. Defaults to 6
hideMetabooleanOptionalOptionally hide the meta section (username, level, all-time and recent XP)
hideHistorybooleanOptionalOptionally hide the historical calendar heat map
hideLanguagesbooleanOptionalOptionally hide the programming languages pie chart
hideMachinesbooleanOptionalOptionally hide the machines percentage chart
Example#
- type: code-stats  options:    username: alicia
Info#

AnonAddy#

AnonAddy is a free and open source mail forwarding service. Use it to protect your real email address, by using a different alias for each of your online accounts, and have all emails land in your normal inbox(es). Supports custom domains, email replies, PGP-encryption, multiple recipients and more

This widget display email addresses / aliases from AnonAddy. Click an email address to copy to clipboard, or use the toggle switch to enable/ disable it. Shows usage stats (bandwidth, used aliases etc), as well as total messages recieved, blocked and sent. Works with both self-hosted and managed instances of AnonAddy.

Options#
FieldTypeRequiredDescription
apiKeystringRequiredYour AnonAddy API Key / Personal Access Token. You can generate this under Account Settings
hostnamestringOptionalIf your self-hosting AnonAddy, then supply the host name. By default it will use the public hosted instance
apiVersionstringOptionalIf you're using an API version that is not version v1, then specify it here
limitnumberOptionalLimit the number of emails shown per page. Defaults to 10
sortBystringOptionalSpecify the sort order for email addresses. Defaults to updated_at. Can be either: local_part, domain, email, emails_forwarded, emails_blocked, emails_replied, emails_sent, created_at, updated_at or deleted_at. Precede with a - character to reverse order.
searchTermstringOptionalA search term to filter results by, will search the email, description and domain
disableControlsbooleanOptionalPrevent any changes being made to account through the widget. User will not be able to enable or disable aliases through UI when this option is set
hideMetabooleanOptionalDon't show account meta info (forward/ block count, quota usage etc)
hideAliasesbooleanOptionalDon't show email address / alias list. Will only show account meta info
Example#
  - type: anonaddy    options:      apiKey: "xxxxxxxxxxxxxxxxxxxxxxxx\        xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx\        xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"      limit: 5      sortBy: created_at      disableControls: true
Info#
  • CORS: 🟢 Enabled
  • Auth: 🔴 Required
  • Price: 🟠 Free for Self-Hosted / Free Plan available on managed instance or $1/month for premium
  • Host: Self-Hosted or Managed
  • Privacy: See AnonAddy Privacy Policy

Vulnerability Feed#

Keep track of recent security advisories and vulnerabilities, with optional filtering by score, exploits, vendor and product. All fields are optional.

Options#
FieldTypeRequiredDescription
sortBystringOptionalThe sorting method. Can be either publish-date, last-update or cve-code. Defaults to publish-date
limitnumberOptionalThe number of results to fetch. Can be between 5 and 30, defaults to 10
minScorenumberOptionalIf set, will only display results with a CVE score higher than the number specified. Can be a number between 0 and 9.9. By default, vulnerabilities of all CVE scores are shown
hasExploitbooleanOptionalIf set to true, will only show results with active exploits. Defaults to false
vendorIdnumberOptionalOnly show results from a specific vendor, specified by ID. See Vendor Search for list of vendors. E.g. 23 (Debian), 26 (Microsoft), 23682 (CloudFlare)
productIdnumberOptionalOnly show results from a specific app or product, specified by ID. See Product Search for list of products. E.g. 13534 (Docker), 15913 (NextCloud), 19294 (Portainer), 17908 (ProtonMail)
Example#
- type: cve-vulnerabilities

or

- type: cve-vulnerabilities  options:    sortBy: publish-date    productId: 28125    hasExploit: true    minScore: 5    limit: 30
Info#

Exchange Rates#

Display current FX rates in your native currency. Hover over a row to view more info, or click to show rates in that currency.

Options#
FieldTypeRequiredDescription
inputCurrencystringRequiredThe base currency to show results in. Specified as a 3-letter ISO-4217 code, see here for the full list of supported currencies, and their symbols
outputCurrenciesarrayRequiredList or currencies to show results for. Specified as a 3-letter ISO-4217 code, see here for the full list of supported currencies, and their symbols
apiKeystringRequiredAPI key for exchangerate-api.com, usually a 24-digit alpha-numeric string. You can sign up for a free account here
Example#
- type: exchange-rates  options:    apiKey: xxxxxxxxxxxxxxxxxxxxxxxx    inputCurrency: GBP    outputCurrencies:      - USD      - JPY      - HKD      - KPW
Info#
  • CORS: 🟢 Enabled
  • Auth: 🔴 Required
  • Price: 🟠 Free plan (upto 100,000 requests/ month)
  • Host: Managed Instance Only
  • Privacy: See ExchangeRateAPI Privacy Policy

Public Holidays#

Counting down to the next day off work? This widget displays upcoming public holidays for your country. Data is fetched from Enrico

Options#
FieldTypeRequiredDescription
countrystringRequiredThe region to fetch holiday data for, specified as a country code, e.g. GB or US
holidayTypestringOptionalThe type of holidays to fetch. Can be: all, public_holiday, observance, school_holiday, other_day or extra_working_day. Defaults to public_holiday
monthsToShownumberOptionalThe number of months in advance to show. Min: 1, max: 24. Defaults to 12
Example#
- type: public-holidays  options:    country: GB    holidayType: all    monthsToShow: 12
Info#
  • CORS: 🟢 Enabled
  • Auth: 🟢 Not Required
  • Price: 🟢 Free
  • Host: Self-Hosted (see jurajmajer/enrico) or Managed
  • Privacy: ⚫ No Policy Available

Covid-19 Status#

Keep track of the current COVID-19 status. Optionally also show cases by country, and a time-series chart. Uses live data from various sources, computed by disease.sh

Options#
FieldTypeRequiredDescription
showChartbooleanOptionalAlso display a time-series chart showing number of recent cases
showCountriesbooleanOptionalAlso display a list of cases per country
numDaysnumberOptionalSpecify number of days worth of history to render on the chart
countriesstring[]OptionalAn array of countries to display, specified by their ISO-3 codes. Leave blank to show all, sorted by most cases. showCountries must be set to true
limitnumberOptionalIf showing all countries, set a limit for number of results to return. Defaults to 10, no maximum
Example#
- type: covid-stats

Or

- type: covid-stats  options:    showChart: true    showCountries: true    countries:    - GBR    - USA    - IND    - RUS
Info#
  • CORS: 🟢 Enabled
  • Auth: 🟢 Not Required
  • Price: 🟢 Free
  • Host: Managed Instance or Self-Hosted (see disease-sh/api)
  • Privacy: ⚫ No Policy Available
  • Conditions: Terms of Use

Sports Scores#

Show recent scores and upcoming matches from your favourite sports team. Data is fetched from TheSportsDB.com. From the UI, you can click any other team to view their scores and upcoming games, or click a league name to see all teams.

Options#
FieldTypeRequiredDescription
teamIdstringOptionalThe ID of a team to fetch scores from. You can search for your team on the Teams Page
leagueIdstringOptionalAlternatively, provide a league ID to fetch all games from. You can find the ID on the Leagues Page
pastOrFuturestringOptionalSet to past to show scores for recent games, or future to show upcoming games. Defaults to past. You can change this within the UI
apiKeystringOptionalOptionally specify your API key, which you can sign up for at TheSportsDB.com
limitnumberOptionalTo limit output to a certain number of matches, defaults to 15
Example#
- type: sports-scores  options:    teamId: 133636
Info#
  • CORS: 🟢 Enabled
  • Auth: 🟠 Optional
  • Price: 🟠 Free plan (upto 30 requests / minute, limited endpoints)
  • Host: Managed Instance Only
  • Privacy: ⚫ No Policy Available

News Headlines#

Displays the latest news, click to read full article. Date is fetched from various news sources using Currents API

Options#
FieldTypeRequiredDescription
apiKeystringRequiredYour API key for CurrentsAPI. This is free, and you can get one here
countrystringOptionalFetch news only from a certain country or region. Specified as a country code, e.g. GB or US. See here for a list of supported regions
categorystringOptionalOnly return news from within a given category, e.g. sports, programming, world, science. The following categories are supported
langstringOptionalSpecify the language for returned articles as a 2-digit ISO code (limited article support). The following languages are supported, defaults to en
countnumberOptionalLimit the number of results. Can be between 1 and 200, defaults to 10
keywordsstringOptionalOnly return articles that contain an exact match within their title or description
hideImagesbooleanOptionalIf set to true, then article image thumbnails will not be displayed
Example#
- type: news-headlines    options:      apiKey: xxxxxxx      category: world
Info#
  • CORS: 🟢 Enabled
  • Auth: 🔴 Required
  • Price: 🟠 Free plan (upto 600 requests / day)
  • Host: Managed Instance Only
  • Privacy: See CurrentsAPI Privacy Policy

TFL Status#

Shows real-time tube status of the London Underground. All fields are optional.

Options#
FieldTypeRequiredDescription
showAllbooleanOptionalBy default, details for lines with a Good Service are not visible, but you can click More Details to see all. Setting this option to true will show all lines on initial page load
sortAlphabeticallybooleanOptionalBy default lines are sorted by current status, set this option to true to instead sort them alphabetically
linesToShowarrayOptionalBy default all lines are shown. If you're only interested in the status of a few lines, then pass in an array of lines to show, specified by name
Example#
- type: tfl-status
  - type: tfl-status    options:      showAll: true      sortAlphabetically: true      linesToShow:      - District      - Jubilee      - Central
Info#
  • CORS: 🟢 Enabled
  • Auth: 🟢 Not Required
  • Price: 🟢 Free
  • Host: Managed Instance Only
  • Privacy: See TFL Privacy Policy

Stock Price History#

Shows recent price history for a given publicly-traded stock or share

Options#
FieldTypeRequiredDescription
apiKeystringRequiredAPI key for Alpha Vantage, you can get a free API key here
stockstringRequiredThe stock symbol for the asset to fetch data for
priceTimestringOptionalThe time to fetch price for. Can be high, low, open or close. Defaults to high
chartColorstringOptionalColor of the chart value. Defaults to --widget-text-color which inherits dashboard primary color
chartHeightnumberOptionalThe height of rendered chart in px. Defaults to 300
Example#
- type: stock-price-chart  options:    stock: NET    apiKey: PGUWSWD6CZTXMT8N
Info#
  • CORS: 🟢 Enabled
  • Auth: 🔴 Required
  • Price: 🟠 Free plan (upto 500 requests/day)
  • Host: Managed Instance Only
  • Privacy: See AlphaVantage Privacy Policy

ETH Gas Prices#

Renders the current Gas cost of transactions on the Ethereum network (in both GWEI and USD), along with recent historical prices. Useful for spotting a good time to transact. Uses data from ethgas.watch

Options#

No config options.

Example#
- type: eth-gas-prices
Info#
  • CORS: 🟢 Enabled
  • Auth: 🟢 Not Required
  • Price: 🟢 Free
  • Host: Managed Instance or Self-Hosted (see wslyvh/ethgaswatch)
  • Privacy: ⚫ No Policy Available

Joke#

Renders a programming or generic joke. Data is fetched from the JokesAPI by @Sv443. All fields are optional.

Options#
FieldTypeRequiredDescription
categorystringOptionalSet the category of jokes to return. Use a string to specify a single category, or an array to pass in multiple options. Available options are: all, programming, pun, dark, spooky, christmas and misc. An up-to-date list of supported categories can be found here. Defaults to all
safeModebooleanOptionalSet to true, to prevent the fetching of any NSFW jokes. Defaults to false
languagestringOptionalSpecify the language for returned jokes. The following languages are supported: en, cs, de, es, fr and pt, and an up-to-date list of supported languages can be found here. By default, your system language will be used, if it's supported, otherwise English
Example#
- type: joke  options:    safeMode: true    language: en    category: Programming
Info#

XKCD Comics#

Have a laugh with the daily comic from XKCD. A classic webcomic website covering everything from Linux, math, romance, science and language. All fields are optional.

Options#
FieldTypeRequiredDescription
comicstring / numberOptionalChoose which comic to display. Set to either random, latest or the series number of a specific comic, like 627. Defaults to latest
Example#
- type: xkcd-comic  options:    comic: latest
Info#
  • CORS: 🟢 Enabled
  • Auth: 🟢 Not Required
  • Price: 🟢 Free
  • Privacy: ⚫ No Policy Available

Flight Data#

Displays airport departure and arrival flights, using data from AeroDataBox. Useful if you live near an airport and often wonder where the flight overhead is going to. Hover over a row for more flight data.

Options#
FieldTypeRequiredDescription
airportstringRequiredThe airport to show flight data from. Should be specified as a 4-character ICAO-code, a full list of which can be found here (example: KBJC or EGKK)
apiKeystringRequiredA valid RapidAPI Key, with AeroDataBox enabled (check in your Subscription Dashboard). This API is free to sign up for and use
limitnumberOptionalFor busy airports, you may wish to limit the number of results visible
directionstringOptionalBy default, both departure and arrival flights will be fetched, if you would like to only show flights in one direction, set this to wither departure or arrival
Example#
- type: flight-data  options:    airport: EGLC    apiKey: XXXXX    limit: 12    direction: all
Info#
  • CORS: 🟢 Enabled
  • Auth: 🔴 Required
  • Price: 🟠 Free plan (upto 150 requests / month)
  • Host: Managed Instance Only
  • Privacy: See AeroDataBox and RapidAPI Policy

Astronomy Picture of the Day#

Show the NASA Astronomy Pictore of the Day. Data is fetched from APOD using PawelPleskaczynski/apod_api.

Options#

No config options.

Example#
- type: apod
Info#

GitHub Trending#

Displays currently trending projects on GitHub. Optionally specify a language and time-frame. Data is fetched from Lissy93/gh-trending-no-cors using the GitHub API. All fields are optional.

Options#
FieldTypeRequiredDescription
langstringOptionalA programming language to fetch trending repos from that category. E.g. javascript or go
sincestringOptionalThe timeframe to use when calculating trends. Can be either daily, weekly or monthly. Defaults to daily
limitnumberOptionalOptionally limit the number of results. Max 25, default is 10
Example#
- type: github-trending-repos  options:    limit: 8    since: weekly
Info#

GitHub Profile Stats#

Display stats from your GitHub profile, using embedded cards from anuraghazra/github-readme-stats

Options#
FieldTypeRequiredDescription
usernamestringRequiredThe GitHub username to fetch info for. E.g. lissy93. (Not required if hideProfileCard and hideLanguagesCard are both set to true)
hideProfileCardbooleanOptionalIf set to true, the users profile card will not be shown. Defaults to false
hideLanguagesCardbooleanOptionalIf set to true, the users top languages card will not be shown. Defaults to false
reposarrayOptionalIf you'd like to also display stats for some GitHub reposotories, then add an array or repo names here. Specified as [username]/[repo-name], e.g. lissy93/dashy
Example#
- type: github-profile-stats  options:    username: Lissy93    hideLanguagesCard: true    repos:    - lissy93/dashy    - lissy93/personal-security-checklist    - lissy93/twitter-sentiment-visualisation
Info#

Self-Hosted Services Widgets#

System Info#

Displays info about the server which Dashy is hosted on. Includes user + host, operating system, uptime and basic memory & load data.

Options#

No config options.

Example#
- type: system-info
Info#

No external data requests made

Cron Monitoring (Health Checks)#

Cron job monitoring using Health Checks. Both managed and self-hosted instances are supported.

Options#
FieldTypeRequiredDescription
apiKeystringRequiredA read-only API key for the project to monitor. You can generate this by selecting a Project --> Settings --> API Access. Note that you must generate a separate key for each project
hoststringOptionalIf you're self-hosting, or using any instance other than the official (healthchecks.io), you will need to specify the host address. E.g. https://healthchecks.example.com or http://cron-monitoing.local
Example#
- type: health-checks  options:    apiKey: XXXXXXXXX
Info#

CPU History (NetData)#

Pull recent CPU usage history from NetData.

Options#
FieldTypeRequiredDescription
hoststringRequiredThe URL to your NetData instance
chartHeightnumberOptionalThe height of rendered chart in px. Defaults to 300
chartColor / chartColorsstring / arrayOptionalColor of the chart value(s) as hex codes. chartColor is a single value (defaults to --widget-text-color), whereas chartColors is an array of colors
Example#
- type: nd-cpu-history  options:  host: http://192.168.1.1:19999
Info#

Memory History (NetData)#

Pull recent system RAM usage from NetData, and show as a breakdown of different categories.

Options#
FieldTypeRequiredDescription
hoststringRequiredThe URL to your NetData instance
chartHeightnumberOptionalThe height of rendered chart in px. Defaults to 300
chartColor / chartColorsstring / arrayOptionalColor of the chart value(s) as hex codes. chartColor is a single value (defaults to --widget-text-color), whereas chartColors is an array of colors
Example#
- type: nd-ram-history  options:    host: http://192.168.1.1:19999
Info#

Load History (NetData)#

Pull recent load usage in 1, 5 and 15 minute intervals, from NetData.

Options#
FieldTypeRequiredDescription
hoststringRequiredThe URL to your NetData instance
chartHeightnumberOptionalThe height of rendered chart in px. Defaults to 300
chartColor / chartColorsstring / arrayOptionalColor of the chart value(s) as hex codes. chartColor is a single value (defaults to --widget-text-color), whereas chartColors is an array of colors
Example#
- type: nd-load-history  options:  host: http://192.168.1.1:19999
Info#

Pi Hole Stats#

Displays the number of queries blocked by Pi-Hole.

Options#
FieldTypeRequiredDescription
hostnamestringRequiredThe URL to your Pi-Hole instance
hideStatus / hideChart / hideInfobooleanOptionalOptionally hide any of the three parts of the widget
Example#
- type: pi-hole-stats  options:    hostname: http://192.168.130.1
Info#

Pi Hole Queries#

Shows top queries that were blocked and allowed by Pi-Hole.

Options#
FieldTypeRequiredDescription
hostnamestringRequiredThe URL to your Pi-Hole instance
apiKeystringRequiredYour Pi-Hole web password. It is NOT your pi-hole admin interface or server password. It can be found in /etc/pihole/setupVars.conf, and is a 64-character located on the line that starts with WEBPASSWORD
countnumberOptionalThe number of queries to display. Defaults to 10
Example#
- type: pi-hole-top-queries  options:    hostname: https://pi-hole.local    apiKey: xxxxxxxxxxxxxxxxxxxxxxx
Info#

Recent Traffic#

Shows number of recent traffic, using allowed and blocked queries from Pi-Hole

Options#
FieldTypeRequiredDescription
hostnamestringRequiredThe URL to your Pi-Hole instance
Example#
- type: pi-hole-traffic  options:    hostname: https://pi-hole.local
Info#

Stat Ping Statuses#

Displays the current and recent uptime of your running services, via a self-hosted instance of StatPing

Options#
FieldTypeRequiredDescription
hostnamestringRequiredThe URL to your StatPing instance, without a trailing slash
Example#
- type: stat-ping  options:    hostname: http://192.168.130.1:8080
Info#

System Resource Monitoring#

The easiest method for displaying system info and resource usage in Dashy is with Glances.

Glances is a cross-platform monitoring tool developed by @nicolargo. It's similar to top/htop but with a Rest API and many data exporters available. Under the hood, it uses psutil for retrieving system info.

If you don't already have it installed, either follow the Installation Guide for your system, or setup with Docker, or use the one-line install script: curl -L https://bit.ly/glances | /bin/bash.

Glances can be launched with the glances command. You'll need to run it in web server mode, using the -w option for the API to be reachable. If you don't plan on using the Web UI, then you can disable it using --disable-webui. See the command reference docs for more info.

Options#

All Glance's based widgets require a hostname. All other parameters are optional.

FieldTypeRequiredDescription
hostnamestringRequiredThe URL or IP + port to your Glances instance (without a trailing slash)
usernamestringOptionalIf you have setup basic auth on Glances, specify username here (defaults to glances)
passwordstringOptionalIf you have setup basic auth on Glances, specify password here. Note: since this password is in plaintext, it is important not to reuse it anywhere else
apiVersionstringOptionalSpecify an API version, defaults to V 3. Note that support for older versions is limited
limitnumberOptionalFor widgets that show a time-series chart, optionally limit the number of data points returned. A higher number will show more historical results, but will take longer to load. A value between 300 - 800 is usually optimal
Info#
  • CORS: 🟢 Enabled
  • Auth: 🟠 Optional
  • Price: 🟢 Free
  • Host: Self-Hosted (see GitHub - Nicolargo/Glances)
  • Privacy: ⚫ No Policy Available
Screenshot#

example-screenshot

Current CPU Usage#

Live-updating current CPU usage, as a combined average across alll cores

Example#
- type: gl-current-cpu  options:    hostname: http://192.168.130.2:61208

CPU Usage Per Core#

Live-updating CPU usage breakdown per core

Example#
- type: gl-current-cores  options:    hostname: http://192.168.130.2:61208

CPU Usage History#

Recent CPU usage history, across all cores, and displayed by user and system

Options#
FieldTypeRequiredDescription
limitnumberOptionalLimit the number of results returned, rendering more data points will take longer to load. Defaults to 100
Example#
- type: gl-cpu-history  options:    hostname: http://192.168.130.2:61208    limit: 60

Current Memory Usage#

Real-time memory usage gauge, with more info visible on click

Example#
- type: gl-current-mem  options:    hostname: http://192.168.130.2:61208

Memory Usage History#

Recent memory usage chart

Options#
FieldTypeRequiredDescription
limitnumberOptionalLimit the number of results returned, rendering more data points will take longer to load. Defaults to 100
Example#
- type: gl-mem-history  options:    hostname: http://localhost:61208    limit: 80

Disk Space#

List connected disks, showing free / used space and other info (file system, mount point and space available)

Example#
- type: gl-disk-space  options:    hostname: http://192.168.130.2:61208

Disk IO#

Shows real-time read and write speeds and operations per sec for each disk

Example#
- type: gl-disk-io  options:    hostname: http://192.168.130.2:61208

System Load#

Shows the number of processes waiting in the run-queue, averaged across all cores. Displays for past 5, 10 and 15 minutes

Example#
- type: gl-system-load  options:    hostname: http://192.168.130.2:61208

System Load History#

Shows recent historical system load, calculated from the number of processes waiting in the run-queue, in 1, 5 and 15 minute intervals, and averaged across all cores. Optionally specify limit to set number of results returned, defaults to 500, max 100000, but the higher the number the longer the load and render times will be.

Example#
- type: gl-load-history  options:    hostname: http://192.168.130.2:61208

Network Interfaces#

Lists visible network interfaces, including real-time upload/ download stats

Example#
- type: gl-network-interfaces  options:    hostname: http://192.168.130.2:61208

Network Traffic#

Shows amount of data recently uploaded/ downloaded across all network interfaces. Optionally set the limit option to specify number historical of data points to return

Example#
- type: gl-network-traffic  options:    hostname: http://192.168.130.2:61208    limit: 500

Resource Usage Alerts#

Lists recent high resource usage alerts (e.g. CPU, mem, IO, load, temp)

Example#
- type: gl-alerts  options:    hostname: http://192.168.130.2:61208

Dynamic Widgets#

Iframe Widget#

Embed any webpage into your dashboard as a widget.

Options#
FieldTypeRequiredDescription
urlstringRequiredThe URL to the webpage to embed
frameHeightnumberOptionalIf needed, specify height of iframe in px. E.g. 400, defaults to auto
Example#
- type: iframe  options:    url: https://fiatleak.com/

HTML Embedded Widget#

Many websites and apps provide their own embeddable widgets. These can be used with Dashy using the Embed widget, which lets you dynamically embed and HTML, CSS or JavaScript contents.

⚠️ NOTE: Use with extreme caution. Embedding a script from an untrustworthy source may have serious unintended consequences.

Options#
FieldTypeRequiredDescription
htmlstringOptionalHTML contents to render in the widget
scriptstringOptionalRaw JavaScript code to execute (caution)
scriptSrcstringOptionalA URL to JavaScript content (caution)
cssstringOptionalAny stylings for widget contents
Example#
- type: embed  options:    scriptSrc: https://cdn.speedcheck.org/basic/scbjs.min.js    html: |       <div id="sc-container">      <div id="sc-branding" class="sc-bb">      <a target="_blank" href="https://www.speedcheck.org/">      <img src="https://cdn.speedcheck.org/branding/speedcheck-logo-18.png" alt="Speedcheck"/>      </a>      </div>      </div>

Or

- type: embed    options:      css: '.coinmarketcap-currency-widget { color: var(--widget-text-color); }'      html: '<div class="coinmarketcap-currency-widget" data-currencyid="1" data-base="USD" data-secondary="" data-ticker="true" data-rank="true" data-marketcap="true" data-volume="true" data-statsticker="true" data-stats="USD"></div>'      scriptSrc: 'https://files.coinmarketcap.com/static/widget/currency.js'

API Response#

Directly output plain-text response from any API-enabled service.

// Coming soon...

Prometheus Data#

Display data from any service with a Prometheus exporter.

// Coming soon...

Data Feed#

Show live data from an RSS-enabled service. The only required parameter is rssUrl, which is the URL to the ATOM feed. See RSS Widget for full list of available options.

Example#
- type: rss-feed  options:    rssUrl: https://notes.aliciasykes.com/feed

Usage & Customizations#

Widget Usage Guide#

Like items, widgets are placed under sections. You may have one or more widgets per section.

In your YAML config file, this will look something like:

sections:- name: Today  icon: far fa-calendar-day  widgets:  - type: clock    options:      format: en-GB  - type: weather    options:      apiKey: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx      city: London      units: metric

In this example, there is a single section, named "Today", using a Calendar icon from Font-Awesome. It has 2 widgets, a clock and the current weather.

Continuous Updates#

By default, a widget which displays dynamic data from an external source, will only fetch results on page load. If you would like to keep data updated at all times, you can enable Continuous Updates. This is done by setting a time value in the updateInterval field.

The value of updateInterval is optional, and is specified and seconds. It must be more than 10 and less than 7200.

For example, the following widget displaying stats from Pi-Hole will update ever 20 seconds.

widgets:- type: pi-hole-stats  updateInterval: 20  options:    hostname: http://192.168.130.2

Note that if you have many widgets, and set them to continuously update frequently, you will notice a hit to performance. A widget that relies on data from an external API, will also consume your usage quota faster, if set to keep updating.

Proxying Requests#

If a widget fails to make a data request, and the console shows a CORS error, this means the server is blocking client-side requests.

Dashy has a built-in CORS proxy (services/cors-proxy.js), which will be used automatically by some widgets, or can be forced to use by other by setting the useProxy option.

For example:

widgets:- type: pi-hole-stats  useProxy: true  options:    hostname: http://pi-hole.local

Alternativley, and more securley, you can set the auth headers on your service to accept requests from Dashy. For example:

Access-Control-Allow-Origin: https://location-of-dashy/Vary: Origin

Widget Styling#

Like elsewhere in Dashy, all colours can be easily modified with CSS variables.

Widgets use the following color variables, which can be overridden if desired:

  • --widget-text-color - Text color, defaults to --primary
  • --widget-background-color - Background color, defaults to --background-darker
  • --widget-accent-color - Accent color, defaults to --background

For more info on how to apply custom variables, see the Theming Docs

Customizing Charts#

For widgets that contain charts, you can set an array of colors under chartColors. +Adding / editing widgets through the UI isn't yet supported, you will need to do this in the YAML config file.

Contents#

General Widgets#

Clock#

A simple, live-updating time and date widget with time-zone support. All fields are optional.

Options#
FieldTypeRequiredDescription
timeZonestringOptionalThe time zone to display date and time in.
Specified as Region/City, for example: Australia/Melbourne. See the Time Zone DB for a full list of supported TZs. Defaults to the browser / device's local time
formatstringOptionalA country code for displaying the date and time in local format.
Specified as [ISO-3166]-[ISO-639], for example: en-AU. See here for a full list of locales. Defaults to the browser / device's region
customCityNamestringOptionalBy default the city from the time-zone is shown, but setting this value will override that text
hideDatebooleanOptionalIf set to true, the date and city will not be shown. Defaults to false
Example#
- type: clock  options:    timeZone: Europe/London    format: en-GB    hideDate: false
Info#

No external data requests

Weather#

A simple, live-updating local weather component, showing temperature, conditions and more info.

Options#
FieldTypeRequiredDescription
apiKeystringRequiredYour OpenWeatherMap API key. You can get one for free at openweathermap.org
citystringRequiredA city name to use for fetching weather. This can also be a state code or country code, following the ISO-3166 format
unitsstringOptionalThe units to use for displaying data, can be either metric or imperial. Defaults to metric
hideDetailsbooleanOptionalIf set to true, the additional details (wind, humidity, pressure, etc) will not be shown. Defaults to false
Example#
- type: weather  options:    apiKey: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx    city: London    units: metric    hideDetails: false
Info#

Weather Forecast#

Displays the weather (temperature and conditions) for the next few days for a given location. Note that this requires either the free OpenWeatherMap Student Plan, or the Premium Plan.

Options#
FieldTypeRequiredDescription
apiKeystringRequiredYour OpenWeatherMap API key. You can get one at openweathermap.org or for free via the OWM Student Plan
citystringRequiredA city name to use for fetching weather. This can also be a state code or country code, following the ISO-3166 format
numDaysnumberOptionalThe number of days to display of forecast info to display. Defaults to 4, max 16 days
unitsstringOptionalThe units to use for displaying data, can be either metric or imperial. Defaults to metric
hideDetailsbooleanOptionalIf set to true, the additional details (wind, humidity, pressure, etc) will not be shown. Defaults to false
Example#
- type: weather-forecast  options:    city: California    numDays: 6    apiKey: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx    units: imperial
Info#
  • CORS: 🟢 Enabled
  • Auth: 🔴 Required
  • Price: 🔴 Premium (free for personal use only)
  • Privacy: See OWM Privacy Policy

RSS Feed#

Display news and updates from any RSS-enabled service.

Options#
FieldTypeRequiredDescription
rssUrlstringRequiredThe URL location of your RSS feed
apiKeystringOptionalAn API key for rss2json. It's free, and will allow you to make 10,000 requests per day, you can sign up here
limitnumberOptionalThe number of posts to return. If you haven't specified an API key, this will be limited to 10
orderBystringOptionalHow results should be sorted. Can be either pubDate, author or title. Defaults to pubDate
orderDirectionstringOptionalOrder direction of feed items to return. Can be either asc or desc. Defaults to desc
Example#
- type: rss-feed  options:    rssUrl: https://www.schneier.com/blog/atom.xml    apiKey: xxxx
Info#
  • CORS: 🟢 Enabled
  • Auth: 🟠 Optional
  • Price: 🟠 Free Plan (up to 10,000 requests / day)
  • Privacy: See Rss2Json Privacy Policy

Public IP#

Often find yourself searching "What's my IP", just so you can check your VPN is still connected? This widget displays your public IP address, along with ISP name and approx location. Data is fetched from IP-API.com.

Options#

No config options.

Example#
- type: public-ip
Info#
  • CORS: 🟢 Enabled
  • Auth: 🟠 Optional
  • Price: 🟢 Free
  • Host: Managed Instance Only
  • Privacy: See IP-API Privacy Policy

Crypto Watch List#

Keep track of price changes of your favorite crypto assets. Data is fetched from CoinGecko. All fields are optional.

Options#
FieldTypeRequiredDescription
assetsstringOptionalAn array of cryptocurrencies, coins and tokens. See list of supported assets. If none are specified, then the top coins by sortBy (defaults to market cap) will be returned
currencystringOptionalThe fiat currency to display price in, expressed as an ISO-4217 alpha code (see list of currencies). Defaults to USD
sortBystringOptionalThe method of sorting results. Can be marketCap, volume or alphabetical. Defaults to marketCap.
limitnumberOptionalNumber of results to return, useful when no assets are specified. Defaults to either all or 100
Example#
- type: crypto-watch-list  options:    limit: 10

Or

  - type: crypto-watch-list    options:      currency: GBP      sortBy: marketCap      assets:      - bitcoin      - ethereum      - monero      - cosmos      - polkadot      - dogecoin
Info#

Crypto Token Price History#

Shows recent price history for a given crypto asset, using price data fetched from CoinGecko

Options#
FieldTypeRequiredDescription
assetstringRequiredName of a crypto asset, coin or token to fetch price data for, see list of supported assets
currencystringOptionalThe fiat currency to display results in, expressed as an ISO-4217 alpha code (see list of currencies). Defaults to USD
numDaysnumberOptionalThe number of days of price history to render. Defaults to 7, min: 1, max: 30 days
chartColorstringOptionalColor of the chart value. Defaults to --widget-text-color which inherits dashboard primary color
chartHeightnumberOptionalThe height of rendered chart in px. Defaults to 300
Example#
- type: crypto-price-chart  options:    asset: bitcoin    currency: GBP    numDays: 7
Info#

Wallet Balance#

Keep track of your crypto balances and see recent transactions. Data is fetched from BlockCypher

Options#
FieldTypeRequiredDescription
coinstringRequiredSymbol of coin or asset, e.g. btc, eth or doge
addressstringRequiredAddress to monitor. This is your wallet's public / receiving address
networkstringOptionalTo use a different network, other than mainnet. Defaults to main
limitnumberOptionalLimit the number of transactions to display. Defaults to 10, set to large number to show all
Example#
- type: wallet-balance  options:    coin: btc    address: 3853bSxupMjvxEYfwGDGAaLZhTKxB2vEVC
Info#

Code Stats#

Display your coding summary. Code::Stats is a free and open source app that aggregates statistics about your programming activity. Dashy supports both the public instance, as well as self-hosted versions.

Options#
FieldTypeRequiredDescription
usernamestringRequiredYour CodeStats username
hostnamestringOptionalIf your self-hosting CodeStats, then supply the host name. By default it will use the public hosted instance
monthsToShownumberOptionalSpecify the number of months to render in the historical data chart. Defaults to 6
hideMetabooleanOptionalOptionally hide the meta section (username, level, all-time and recent XP)
hideHistorybooleanOptionalOptionally hide the historical calendar heat map
hideLanguagesbooleanOptionalOptionally hide the programming languages pie chart
hideMachinesbooleanOptionalOptionally hide the machines percentage chart
Example#
- type: code-stats  options:    username: alicia
Info#

AnonAddy#

AnonAddy is a free and open source mail forwarding service. Use it to protect your real email address, by using a different alias for each of your online accounts, and have all emails land in your normal inbox(es). Supports custom domains, email replies, PGP-encryption, multiple recipients and more

This widget display email addresses / aliases from AnonAddy. Click an email address to copy to clipboard, or use the toggle switch to enable/ disable it. Shows usage stats (bandwidth, used aliases etc), as well as total messages recieved, blocked and sent. Works with both self-hosted and managed instances of AnonAddy.

Options#
FieldTypeRequiredDescription
apiKeystringRequiredYour AnonAddy API Key / Personal Access Token. You can generate this under Account Settings
hostnamestringOptionalIf your self-hosting AnonAddy, then supply the host name. By default it will use the public hosted instance
apiVersionstringOptionalIf you're using an API version that is not version v1, then specify it here
limitnumberOptionalLimit the number of emails shown per page. Defaults to 10
sortBystringOptionalSpecify the sort order for email addresses. Defaults to updated_at. Can be either: local_part, domain, email, emails_forwarded, emails_blocked, emails_replied, emails_sent, created_at, updated_at or deleted_at. Precede with a - character to reverse order.
searchTermstringOptionalA search term to filter results by, will search the email, description and domain
disableControlsbooleanOptionalPrevent any changes being made to account through the widget. User will not be able to enable or disable aliases through UI when this option is set
hideMetabooleanOptionalDon't show account meta info (forward/ block count, quota usage etc)
hideAliasesbooleanOptionalDon't show email address / alias list. Will only show account meta info
Example#
  - type: anonaddy    options:      apiKey: "xxxxxxxxxxxxxxxxxxxxxxxx\        xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx\        xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"      limit: 5      sortBy: created_at      disableControls: true
Info#
  • CORS: 🟢 Enabled
  • Auth: 🔴 Required
  • Price: 🟠 Free for Self-Hosted / Free Plan available on managed instance or $1/month for premium
  • Host: Self-Hosted or Managed
  • Privacy: See AnonAddy Privacy Policy

Vulnerability Feed#

Keep track of recent security advisories and vulnerabilities, with optional filtering by score, exploits, vendor and product. All fields are optional.

Options#
FieldTypeRequiredDescription
sortBystringOptionalThe sorting method. Can be either publish-date, last-update or cve-code. Defaults to publish-date
limitnumberOptionalThe number of results to fetch. Can be between 5 and 30, defaults to 10
minScorenumberOptionalIf set, will only display results with a CVE score higher than the number specified. Can be a number between 0 and 9.9. By default, vulnerabilities of all CVE scores are shown
hasExploitbooleanOptionalIf set to true, will only show results with active exploits. Defaults to false
vendorIdnumberOptionalOnly show results from a specific vendor, specified by ID. See Vendor Search for list of vendors. E.g. 23 (Debian), 26 (Microsoft), 23682 (CloudFlare)
productIdnumberOptionalOnly show results from a specific app or product, specified by ID. See Product Search for list of products. E.g. 13534 (Docker), 15913 (NextCloud), 19294 (Portainer), 17908 (ProtonMail)
Example#
- type: cve-vulnerabilities

or

- type: cve-vulnerabilities  options:    sortBy: publish-date    productId: 28125    hasExploit: true    minScore: 5    limit: 30
Info#

Exchange Rates#

Display current FX rates in your native currency. Hover over a row to view more info, or click to show rates in that currency.

Options#
FieldTypeRequiredDescription
inputCurrencystringRequiredThe base currency to show results in. Specified as a 3-letter ISO-4217 code, see here for the full list of supported currencies, and their symbols
outputCurrenciesarrayRequiredList or currencies to show results for. Specified as a 3-letter ISO-4217 code, see here for the full list of supported currencies, and their symbols
apiKeystringRequiredAPI key for exchangerate-api.com, usually a 24-digit alpha-numeric string. You can sign up for a free account here
Example#
- type: exchange-rates  options:    apiKey: xxxxxxxxxxxxxxxxxxxxxxxx    inputCurrency: GBP    outputCurrencies:      - USD      - JPY      - HKD      - KPW
Info#
  • CORS: 🟢 Enabled
  • Auth: 🔴 Required
  • Price: 🟠 Free plan (upto 100,000 requests/ month)
  • Host: Managed Instance Only
  • Privacy: See ExchangeRateAPI Privacy Policy

Public Holidays#

Counting down to the next day off work? This widget displays upcoming public holidays for your country. Data is fetched from Enrico

Options#
FieldTypeRequiredDescription
countrystringRequiredThe region to fetch holiday data for, specified as a country code, e.g. GB or US
holidayTypestringOptionalThe type of holidays to fetch. Can be: all, public_holiday, observance, school_holiday, other_day or extra_working_day. Defaults to public_holiday
monthsToShownumberOptionalThe number of months in advance to show. Min: 1, max: 24. Defaults to 12
Example#
- type: public-holidays  options:    country: GB    holidayType: all    monthsToShow: 12
Info#
  • CORS: 🟢 Enabled
  • Auth: 🟢 Not Required
  • Price: 🟢 Free
  • Host: Self-Hosted (see jurajmajer/enrico) or Managed
  • Privacy: ⚫ No Policy Available

Covid-19 Status#

Keep track of the current COVID-19 status. Optionally also show cases by country, and a time-series chart. Uses live data from various sources, computed by disease.sh

Options#
FieldTypeRequiredDescription
showChartbooleanOptionalAlso display a time-series chart showing number of recent cases
showCountriesbooleanOptionalAlso display a list of cases per country
numDaysnumberOptionalSpecify number of days worth of history to render on the chart
countriesstring[]OptionalAn array of countries to display, specified by their ISO-3 codes. Leave blank to show all, sorted by most cases. showCountries must be set to true
limitnumberOptionalIf showing all countries, set a limit for number of results to return. Defaults to 10, no maximum
Example#
- type: covid-stats

Or

- type: covid-stats  options:    showChart: true    showCountries: true    countries:    - GBR    - USA    - IND    - RUS
Info#
  • CORS: 🟢 Enabled
  • Auth: 🟢 Not Required
  • Price: 🟢 Free
  • Host: Managed Instance or Self-Hosted (see disease-sh/api)
  • Privacy: ⚫ No Policy Available
  • Conditions: Terms of Use

Sports Scores#

Show recent scores and upcoming matches from your favourite sports team. Data is fetched from TheSportsDB.com. From the UI, you can click any other team to view their scores and upcoming games, or click a league name to see all teams.

Options#
FieldTypeRequiredDescription
teamIdstringOptionalThe ID of a team to fetch scores from. You can search for your team on the Teams Page
leagueIdstringOptionalAlternatively, provide a league ID to fetch all games from. You can find the ID on the Leagues Page
pastOrFuturestringOptionalSet to past to show scores for recent games, or future to show upcoming games. Defaults to past. You can change this within the UI
apiKeystringOptionalOptionally specify your API key, which you can sign up for at TheSportsDB.com
limitnumberOptionalTo limit output to a certain number of matches, defaults to 15
Example#
- type: sports-scores  options:    teamId: 133636
Info#
  • CORS: 🟢 Enabled
  • Auth: 🟠 Optional
  • Price: 🟠 Free plan (upto 30 requests / minute, limited endpoints)
  • Host: Managed Instance Only
  • Privacy: ⚫ No Policy Available

News Headlines#

Displays the latest news, click to read full article. Date is fetched from various news sources using Currents API

Options#
FieldTypeRequiredDescription
apiKeystringRequiredYour API key for CurrentsAPI. This is free, and you can get one here
countrystringOptionalFetch news only from a certain country or region. Specified as a country code, e.g. GB or US. See here for a list of supported regions
categorystringOptionalOnly return news from within a given category, e.g. sports, programming, world, science. The following categories are supported
langstringOptionalSpecify the language for returned articles as a 2-digit ISO code (limited article support). The following languages are supported, defaults to en
countnumberOptionalLimit the number of results. Can be between 1 and 200, defaults to 10
keywordsstringOptionalOnly return articles that contain an exact match within their title or description
hideImagesbooleanOptionalIf set to true, then article image thumbnails will not be displayed
Example#
- type: news-headlines    options:      apiKey: xxxxxxx      category: world
Info#
  • CORS: 🟢 Enabled
  • Auth: 🔴 Required
  • Price: 🟠 Free plan (upto 600 requests / day)
  • Host: Managed Instance Only
  • Privacy: See CurrentsAPI Privacy Policy

TFL Status#

Shows real-time tube status of the London Underground. All fields are optional.

Options#
FieldTypeRequiredDescription
showAllbooleanOptionalBy default, details for lines with a Good Service are not visible, but you can click More Details to see all. Setting this option to true will show all lines on initial page load
sortAlphabeticallybooleanOptionalBy default lines are sorted by current status, set this option to true to instead sort them alphabetically
linesToShowarrayOptionalBy default all lines are shown. If you're only interested in the status of a few lines, then pass in an array of lines to show, specified by name
Example#
- type: tfl-status
  - type: tfl-status    options:      showAll: true      sortAlphabetically: true      linesToShow:      - District      - Jubilee      - Central
Info#
  • CORS: 🟢 Enabled
  • Auth: 🟢 Not Required
  • Price: 🟢 Free
  • Host: Managed Instance Only
  • Privacy: See TFL Privacy Policy

Stock Price History#

Shows recent price history for a given publicly-traded stock or share

Options#
FieldTypeRequiredDescription
apiKeystringRequiredAPI key for Alpha Vantage, you can get a free API key here
stockstringRequiredThe stock symbol for the asset to fetch data for
priceTimestringOptionalThe time to fetch price for. Can be high, low, open or close. Defaults to high
chartColorstringOptionalColor of the chart value. Defaults to --widget-text-color which inherits dashboard primary color
chartHeightnumberOptionalThe height of rendered chart in px. Defaults to 300
Example#
- type: stock-price-chart  options:    stock: NET    apiKey: PGUWSWD6CZTXMT8N
Info#
  • CORS: 🟢 Enabled
  • Auth: 🔴 Required
  • Price: 🟠 Free plan (upto 500 requests/day)
  • Host: Managed Instance Only
  • Privacy: See AlphaVantage Privacy Policy

ETH Gas Prices#

Renders the current Gas cost of transactions on the Ethereum network (in both GWEI and USD), along with recent historical prices. Useful for spotting a good time to transact. Uses data from ethgas.watch

Options#

No config options.

Example#
- type: eth-gas-prices
Info#
  • CORS: 🟢 Enabled
  • Auth: 🟢 Not Required
  • Price: 🟢 Free
  • Host: Managed Instance or Self-Hosted (see wslyvh/ethgaswatch)
  • Privacy: ⚫ No Policy Available

Joke#

Renders a programming or generic joke. Data is fetched from the JokesAPI by @Sv443. All fields are optional.

Options#
FieldTypeRequiredDescription
categorystringOptionalSet the category of jokes to return. Use a string to specify a single category, or an array to pass in multiple options. Available options are: all, programming, pun, dark, spooky, christmas and misc. An up-to-date list of supported categories can be found here. Defaults to all
safeModebooleanOptionalSet to true, to prevent the fetching of any NSFW jokes. Defaults to false
languagestringOptionalSpecify the language for returned jokes. The following languages are supported: en, cs, de, es, fr and pt, and an up-to-date list of supported languages can be found here. By default, your system language will be used, if it's supported, otherwise English
Example#
- type: joke  options:    safeMode: true    language: en    category: Programming
Info#

XKCD Comics#

Have a laugh with the daily comic from XKCD. A classic webcomic website covering everything from Linux, math, romance, science and language. All fields are optional.

Options#
FieldTypeRequiredDescription
comicstring / numberOptionalChoose which comic to display. Set to either random, latest or the series number of a specific comic, like 627. Defaults to latest
Example#
- type: xkcd-comic  options:    comic: latest
Info#
  • CORS: 🟢 Enabled
  • Auth: 🟢 Not Required
  • Price: 🟢 Free
  • Privacy: ⚫ No Policy Available

Flight Data#

Displays airport departure and arrival flights, using data from AeroDataBox. Useful if you live near an airport and often wonder where the flight overhead is going to. Hover over a row for more flight data.

Options#
FieldTypeRequiredDescription
airportstringRequiredThe airport to show flight data from. Should be specified as a 4-character ICAO-code, a full list of which can be found here (example: KBJC or EGKK)
apiKeystringRequiredA valid RapidAPI Key, with AeroDataBox enabled (check in your Subscription Dashboard). This API is free to sign up for and use
limitnumberOptionalFor busy airports, you may wish to limit the number of results visible
directionstringOptionalBy default, both departure and arrival flights will be fetched, if you would like to only show flights in one direction, set this to wither departure or arrival
Example#
- type: flight-data  options:    airport: EGLC    apiKey: XXXXX    limit: 12    direction: all
Info#
  • CORS: 🟢 Enabled
  • Auth: 🔴 Required
  • Price: 🟠 Free plan (upto 150 requests / month)
  • Host: Managed Instance Only
  • Privacy: See AeroDataBox and RapidAPI Policy

Astronomy Picture of the Day#

Show the NASA Astronomy Pictore of the Day. Data is fetched from APOD using PawelPleskaczynski/apod_api.

Options#

No config options.

Example#
- type: apod
Info#

GitHub Trending#

Displays currently trending projects on GitHub. Optionally specify a language and time-frame. Data is fetched from Lissy93/gh-trending-no-cors using the GitHub API. All fields are optional.

Options#
FieldTypeRequiredDescription
langstringOptionalA programming language to fetch trending repos from that category. E.g. javascript or go
sincestringOptionalThe timeframe to use when calculating trends. Can be either daily, weekly or monthly. Defaults to daily
limitnumberOptionalOptionally limit the number of results. Max 25, default is 10
Example#
- type: github-trending-repos  options:    limit: 8    since: weekly
Info#

GitHub Profile Stats#

Display stats from your GitHub profile, using embedded cards from anuraghazra/github-readme-stats

Options#
FieldTypeRequiredDescription
usernamestringRequiredThe GitHub username to fetch info for. E.g. lissy93. (Not required if hideProfileCard and hideLanguagesCard are both set to true)
hideProfileCardbooleanOptionalIf set to true, the users profile card will not be shown. Defaults to false
hideLanguagesCardbooleanOptionalIf set to true, the users top languages card will not be shown. Defaults to false
reposarrayOptionalIf you'd like to also display stats for some GitHub reposotories, then add an array or repo names here. Specified as [username]/[repo-name], e.g. lissy93/dashy
Example#
- type: github-profile-stats  options:    username: Lissy93    hideLanguagesCard: true    repos:    - lissy93/dashy    - lissy93/personal-security-checklist    - lissy93/twitter-sentiment-visualisation
Info#

Self-Hosted Services Widgets#

System Info#

Displays info about the server which Dashy is hosted on. Includes user + host, operating system, uptime and basic memory & load data.

Options#

No config options.

Example#
- type: system-info
Info#

No external data requests made

Cron Monitoring (Health Checks)#

Cron job monitoring using Health Checks. Both managed and self-hosted instances are supported.

Options#
FieldTypeRequiredDescription
apiKeystringRequiredA read-only API key for the project to monitor. You can generate this by selecting a Project --> Settings --> API Access. Note that you must generate a separate key for each project
hoststringOptionalIf you're self-hosting, or using any instance other than the official (healthchecks.io), you will need to specify the host address. E.g. https://healthchecks.example.com or http://cron-monitoing.local
Example#
- type: health-checks  options:    apiKey: XXXXXXXXX
Info#

CPU History (NetData)#

Pull recent CPU usage history from NetData.

Options#
FieldTypeRequiredDescription
hoststringRequiredThe URL to your NetData instance
chartHeightnumberOptionalThe height of rendered chart in px. Defaults to 300
chartColor / chartColorsstring / arrayOptionalColor of the chart value(s) as hex codes. chartColor is a single value (defaults to --widget-text-color), whereas chartColors is an array of colors
Example#
- type: nd-cpu-history  options:  host: http://192.168.1.1:19999
Info#

Memory History (NetData)#

Pull recent system RAM usage from NetData, and show as a breakdown of different categories.

Options#
FieldTypeRequiredDescription
hoststringRequiredThe URL to your NetData instance
chartHeightnumberOptionalThe height of rendered chart in px. Defaults to 300
chartColor / chartColorsstring / arrayOptionalColor of the chart value(s) as hex codes. chartColor is a single value (defaults to --widget-text-color), whereas chartColors is an array of colors
Example#
- type: nd-ram-history  options:    host: http://192.168.1.1:19999
Info#

Load History (NetData)#

Pull recent load usage in 1, 5 and 15 minute intervals, from NetData.

Options#
FieldTypeRequiredDescription
hoststringRequiredThe URL to your NetData instance
chartHeightnumberOptionalThe height of rendered chart in px. Defaults to 300
chartColor / chartColorsstring / arrayOptionalColor of the chart value(s) as hex codes. chartColor is a single value (defaults to --widget-text-color), whereas chartColors is an array of colors
Example#
- type: nd-load-history  options:  host: http://192.168.1.1:19999
Info#

Pi Hole Stats#

Displays the number of queries blocked by Pi-Hole.

Options#
FieldTypeRequiredDescription
hostnamestringRequiredThe URL to your Pi-Hole instance
hideStatus / hideChart / hideInfobooleanOptionalOptionally hide any of the three parts of the widget
Example#
- type: pi-hole-stats  options:    hostname: http://192.168.130.1
Info#

Pi Hole Queries#

Shows top queries that were blocked and allowed by Pi-Hole.

Options#
FieldTypeRequiredDescription
hostnamestringRequiredThe URL to your Pi-Hole instance
apiKeystringRequiredYour Pi-Hole web password. It is NOT your pi-hole admin interface or server password. It can be found in /etc/pihole/setupVars.conf, and is a 64-character located on the line that starts with WEBPASSWORD
countnumberOptionalThe number of queries to display. Defaults to 10
Example#
- type: pi-hole-top-queries  options:    hostname: https://pi-hole.local    apiKey: xxxxxxxxxxxxxxxxxxxxxxx
Info#

Recent Traffic#

Shows number of recent traffic, using allowed and blocked queries from Pi-Hole

Options#
FieldTypeRequiredDescription
hostnamestringRequiredThe URL to your Pi-Hole instance
Example#
- type: pi-hole-traffic  options:    hostname: https://pi-hole.local
Info#

Stat Ping Statuses#

Displays the current and recent uptime of your running services, via a self-hosted instance of StatPing

Options#
FieldTypeRequiredDescription
hostnamestringRequiredThe URL to your StatPing instance, without a trailing slash
Example#
- type: stat-ping  options:    hostname: http://192.168.130.1:8080
Info#

System Resource Monitoring#

The easiest method for displaying system info and resource usage in Dashy is with Glances.

Glances is a cross-platform monitoring tool developed by @nicolargo. It's similar to top/htop but with a Rest API and many data exporters available. Under the hood, it uses psutil for retrieving system info.

If you don't already have it installed, either follow the Installation Guide for your system, or setup with Docker, or use the one-line install script: curl -L https://bit.ly/glances | /bin/bash.

Glances can be launched with the glances command. You'll need to run it in web server mode, using the -w option for the API to be reachable. If you don't plan on using the Web UI, then you can disable it using --disable-webui. See the command reference docs for more info.

Options#

All Glance's based widgets require a hostname. All other parameters are optional.

FieldTypeRequiredDescription
hostnamestringRequiredThe URL or IP + port to your Glances instance (without a trailing slash)
usernamestringOptionalIf you have setup basic auth on Glances, specify username here (defaults to glances)
passwordstringOptionalIf you have setup basic auth on Glances, specify password here. Note: since this password is in plaintext, it is important not to reuse it anywhere else
apiVersionstringOptionalSpecify an API version, defaults to V 3. Note that support for older versions is limited
limitnumberOptionalFor widgets that show a time-series chart, optionally limit the number of data points returned. A higher number will show more historical results, but will take longer to load. A value between 300 - 800 is usually optimal
Info#
  • CORS: 🟢 Enabled
  • Auth: 🟠 Optional
  • Price: 🟢 Free
  • Host: Self-Hosted (see GitHub - Nicolargo/Glances)
  • Privacy: ⚫ No Policy Available
Screenshot#

example-screenshot

Current CPU Usage#

Live-updating current CPU usage, as a combined average across alll cores

Example#
- type: gl-current-cpu  options:    hostname: http://192.168.130.2:61208

CPU Usage Per Core#

Live-updating CPU usage breakdown per core

Example#
- type: gl-current-cores  options:    hostname: http://192.168.130.2:61208

CPU Usage History#

Recent CPU usage history, across all cores, and displayed by user and system

Options#
FieldTypeRequiredDescription
limitnumberOptionalLimit the number of results returned, rendering more data points will take longer to load. Defaults to 100
Example#
- type: gl-cpu-history  options:    hostname: http://192.168.130.2:61208    limit: 60

Current Memory Usage#

Real-time memory usage gauge, with more info visible on click

Example#
- type: gl-current-mem  options:    hostname: http://192.168.130.2:61208

Memory Usage History#

Recent memory usage chart

Options#
FieldTypeRequiredDescription
limitnumberOptionalLimit the number of results returned, rendering more data points will take longer to load. Defaults to 100
Example#
- type: gl-mem-history  options:    hostname: http://localhost:61208    limit: 80

Disk Space#

List connected disks, showing free / used space and other info (file system, mount point and space available)

Example#
- type: gl-disk-space  options:    hostname: http://192.168.130.2:61208

Disk IO#

Shows real-time read and write speeds and operations per sec for each disk

Example#
- type: gl-disk-io  options:    hostname: http://192.168.130.2:61208

System Load#

Shows the number of processes waiting in the run-queue, averaged across all cores. Displays for past 5, 10 and 15 minutes

Example#
- type: gl-system-load  options:    hostname: http://192.168.130.2:61208

System Load History#

Shows recent historical system load, calculated from the number of processes waiting in the run-queue, in 1, 5 and 15 minute intervals, and averaged across all cores. Optionally specify limit to set number of results returned, defaults to 500, max 100000, but the higher the number the longer the load and render times will be.

Example#
- type: gl-load-history  options:    hostname: http://192.168.130.2:61208

Network Interfaces#

Lists visible network interfaces, including real-time upload/ download stats

Example#
- type: gl-network-interfaces  options:    hostname: http://192.168.130.2:61208

Network Traffic#

Shows amount of data recently uploaded/ downloaded across all network interfaces. Optionally set the limit option to specify number historical of data points to return

Example#
- type: gl-network-traffic  options:    hostname: http://192.168.130.2:61208    limit: 500

Resource Usage Alerts#

Lists recent high resource usage alerts (e.g. CPU, mem, IO, load, temp)

Example#
- type: gl-alerts  options:    hostname: http://192.168.130.2:61208

Dynamic Widgets#

Iframe Widget#

Embed any webpage into your dashboard as a widget.

Options#
FieldTypeRequiredDescription
urlstringRequiredThe URL to the webpage to embed
frameHeightnumberOptionalIf needed, specify height of iframe in px. E.g. 400, defaults to auto
Example#
- type: iframe  options:    url: https://fiatleak.com/

HTML Embedded Widget#

Many websites and apps provide their own embeddable widgets. These can be used with Dashy using the Embed widget, which lets you dynamically embed and HTML, CSS or JavaScript contents.

⚠️ NOTE: Use with extreme caution. Embedding a script from an untrustworthy source may have serious unintended consequences.

Options#
FieldTypeRequiredDescription
htmlstringOptionalHTML contents to render in the widget
scriptstringOptionalRaw JavaScript code to execute (caution)
scriptSrcstringOptionalA URL to JavaScript content (caution)
cssstringOptionalAny stylings for widget contents
Example#
- type: embed  options:    scriptSrc: https://cdn.speedcheck.org/basic/scbjs.min.js    html: |       <div id="sc-container">      <div id="sc-branding" class="sc-bb">      <a target="_blank" href="https://www.speedcheck.org/">      <img src="https://cdn.speedcheck.org/branding/speedcheck-logo-18.png" alt="Speedcheck"/>      </a>      </div>      </div>

Or

- type: embed    options:      css: '.coinmarketcap-currency-widget { color: var(--widget-text-color); }'      html: '<div class="coinmarketcap-currency-widget" data-currencyid="1" data-base="USD" data-secondary="" data-ticker="true" data-rank="true" data-marketcap="true" data-volume="true" data-statsticker="true" data-stats="USD"></div>'      scriptSrc: 'https://files.coinmarketcap.com/static/widget/currency.js'

API Response#

Directly output plain-text response from any API-enabled service.

// Coming soon...

Prometheus Data#

Display data from any service with a Prometheus exporter.

// Coming soon...

Data Feed#

Show live data from an RSS-enabled service. The only required parameter is rssUrl, which is the URL to the ATOM feed. See RSS Widget for full list of available options.

Example#
- type: rss-feed  options:    rssUrl: https://notes.aliciasykes.com/feed

Usage & Customizations#

Widget Usage Guide#

Like items, widgets are placed under sections. You may have one or more widgets per section.

In your YAML config file, this will look something like:

sections:- name: Today  icon: far fa-calendar-day  widgets:  - type: clock    options:      format: en-GB  - type: weather    options:      apiKey: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx      city: London      units: metric

In this example, there is a single section, named "Today", using a Calendar icon from Font-Awesome. It has 2 widgets, a clock and the current weather.

Continuous Updates#

By default, a widget which displays dynamic data from an external source, will only fetch results on page load. If you would like to keep data updated at all times, you can enable Continuous Updates. This is done by setting a time value in the updateInterval field.

The value of updateInterval is optional, and is specified and seconds. It must be more than 10 and less than 7200.

For example, the following widget displaying stats from Pi-Hole will update ever 20 seconds.

widgets:- type: pi-hole-stats  updateInterval: 20  options:    hostname: http://192.168.130.2

Note that if you have many widgets, and set them to continuously update frequently, you will notice a hit to performance. A widget that relies on data from an external API, will also consume your usage quota faster, if set to keep updating.

Proxying Requests#

If a widget fails to make a data request, and the console shows a CORS error, this means the server is blocking client-side requests.

Dashy has a built-in CORS proxy (services/cors-proxy.js), which will be used automatically by some widgets, or can be forced to use by other by setting the useProxy option.

For example:

widgets:- type: pi-hole-stats  useProxy: true  options:    hostname: http://pi-hole.local

Alternatively, and more securely, you can set the auth headers on your service to accept requests from Dashy. For example:

Access-Control-Allow-Origin: https://location-of-dashy/Vary: Origin

Widget Styling#

Like elsewhere in Dashy, all colours can be easily modified with CSS variables.

Widgets use the following color variables, which can be overridden if desired:

  • --widget-text-color - Text color, defaults to --primary
  • --widget-background-color - Background color, defaults to --background-darker
  • --widget-accent-color - Accent color, defaults to --background

For more info on how to apply custom variables, see the Theming Docs

Customizing Charts#

For widgets that contain charts, you can set an array of colors under chartColors. To specify the chart height, set chartHeight to an integer (in px), defaults to 300. -For example:

- type: gl-load-history  options:    hostname: http://192.168.130.2:61208    chartColors: ['#9b5de5', '#f15bb5', '#00bbf9', '#00f5d4']    chartHeight: 450

Language Translations#

Since most of the content displayed within widgets is fetched from an external API, unless that API supports multiple languages, translating dynamic content is not possible.

However, any hard-coded content is translatable, and all dates and times will display in your local format.

For more info about multi-language support, see the Internationalization Docs.

Widget UI Options#

Widgets can be opened in full-page view, by clicking the Arrow icon (top-right). The URL in your address bar will also update, and visiting that web address directly will take you straight to that widget.

You can reload the data of any widget, by clicking the Refresh Data icon (also in top-right). This will only affect the widget where the action was triggered from.

All config options that can be applied to sections, can also be applied to widget sections. For example, to make a widget section double the width, set displayData.cols: 2 within the parent section. You can collapse a widget (by clicking the section title), and collapse state will be saved locally.

Widgets cannot currently be edited through the UI. This feature is in development, and will be released soon. In the meantime, you can either use the JSON config editor, or use VS Code Server, or just SSH into your box and edit the conf.yml file directly.

Build your own Widget#

Widgets are built in a modular fashion, making it easy for anyone to create their own custom components.

For a full tutorial on creating your own widget, you can follow this guide, or take a look at here for a code example.

Alternatively, for displaying simple data, you could also just use the either the iframe, embed, data feed or API response widgets.

Requesting a Widget#

Suggestions for widget ideas are welcome. But there is no guarantee that I will build your widget idea.

You can suggest a widget here, please star the repo before submitting a ticket.

Please only request widgets for services that:

  • Have a publicly accessible API
  • Are CORS and HTTPS enabled
  • Are free to use, or have a free plan
  • Allow for use in their Terms of Service
  • Would be useful for other users

For services that are not officially supported, it is likely still possible to display data using either the iframe, embed or API response widgets. For more advanced features, like charts and action buttons, you could also build your own widget, using this tutorial, it's fairly straight forward, and you can use an existing widget (or this example) as a template.

- +For example:

- type: gl-load-history  options:    hostname: http://192.168.130.2:61208    chartColors: ['#9b5de5', '#f15bb5', '#00bbf9', '#00f5d4']    chartHeight: 450

Language Translations#

Since most of the content displayed within widgets is fetched from an external API, unless that API supports multiple languages, translating dynamic content is not possible.

However, any hard-coded content is translatable, and all dates and times will display in your local format.

For more info about multi-language support, see the Internationalization Docs.

Widget UI Options#

Widgets can be opened in full-page view, by clicking the Arrow icon (top-right). The URL in your address bar will also update, and visiting that web address directly will take you straight to that widget.

You can reload the data of any widget, by clicking the Refresh Data icon (also in top-right). This will only affect the widget where the action was triggered from.

All config options that can be applied to sections, can also be applied to widget sections. For example, to make a widget section double the width, set displayData.cols: 2 within the parent section. You can collapse a widget (by clicking the section title), and collapse state will be saved locally.

Widgets cannot currently be edited through the UI. This feature is in development, and will be released soon. In the meantime, you can either use the JSON config editor, or use VS Code Server, or just SSH into your box and edit the conf.yml file directly.

Build your own Widget#

Widgets are built in a modular fashion, making it easy for anyone to create their own custom components.

For a full tutorial on creating your own widget, you can follow this guide, or take a look at here for a code example.

Alternatively, for displaying simple data, you could also just use the either the iframe, embed, data feed or API response widgets.

Requesting a Widget#

Suggestions for widget ideas are welcome. But there is no guarantee that I will build your widget idea.

You can suggest a widget here, please star the repo before submitting a ticket.

Please only request widgets for services that:

  • Have a publicly accessible API
  • Are CORS and HTTPS enabled
  • Are free to use, or have a free plan
  • Allow for use in their Terms of Service
  • Would be useful for other users

For services that are not officially supported, it is likely still possible to display data using either the iframe, embed or API response widgets. For more advanced features, like charts and action buttons, you could also build your own widget, using this tutorial, it's fairly straight forward, and you can use an existing widget (or this example) as a template.

Troubleshooting Widget Errors#

If an error occurs when fetching or rendering results, you will see a short message in the UI. If that message doesn't addequatley explain the problem, then you can open the browser console to see more details.

Before proceeding, ensure that if the widget requires auth your API is correct, and for custom widgets, double check that the URL and protocol is correct.

If you're able to, you can find more information about why the request may be failing in the Dev Tools under the Network tab, and you can ensure your endpoint is correct and working using a tool like Postman.

CORS Errors#

The most common issue is a CORS error. This is a browser security mechanism which prevents the client-side app (Dashy) from from accessing resources on a remote origin, without that server's explicit permission (e.g. with headers like Access-Control-Allow-Origin). See the MDN Docs for more info: Cross-Origin Resource Sharing.

There are several ways to fix a CORS error:

Option 1 - Ensure Correct Protocol#

You will get a CORS error if you try and access a http service from a https source. So ensure that the URL you are requesting has the right protocol, and is correctly formatted.

Option 2 - Set Headers#

If you have control over the destination (e.g. for a self-hosted service), then you can simply apply the correct headers. +Add the Access-Control-Allow-Origin header, with the value of either * to allow requests from anywhere, or more securely, the host of where Dashy is served from. For example:

Access-Control-Allow-Origin: https://url-of-dashy.local

or

Access-Control-Allow-Origin: *
Option 3 - Proxying Request#

You can route requests through Dashy's built-in CORS proxy. Instructions and more details can be found here. 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.

Option 4 - Use a plugin#

For testing purposes, you can use an addon, which will disable the CORS checks. You can get the Allow-CORS extension for Chrome or Firefox, more details here

Raising an Issue#

If you need to submit a bug report for a failing widget, then please include the full console output (see how) as well as the relevant parts of your config file. Before sending the request, ensure you've read the docs. If you're new to GitHub, an haven't previously contributed to the project, then please fist star the repo to avoid your ticket being closed by the anti-spam bot.

+ \ No newline at end of file diff --git a/index.html b/index.html index 91863cc6..5d922b55 100644 --- a/index.html +++ b/index.html @@ -5,13 +5,13 @@ Dashy | Dashy - +

Dashy

The Ultimate Homepage for your Homelab

Get StartedLive DemoSource CodeDocumentation
Dashy is an open source, highly customizable, easy to use, privacy-respecting dashboard app.Keep Reading...
Feature List

Theming

With tons of built-in themes to choose form, plus a UI color palette editor, you can have a unique looking dashboard in no time. There is also support for custom CSS, and since all properties use CSS variables, it is easy to override.
Learn more in the Docs Docs

Icons

Dashy can auto-fetch icons from the favicon of each of your apps/ services. There is also native support for Font Awesome, Material Design Icons, emoji icons and of course normal images.
Learn more in the Docs Docs
Screenshot Coming Soon

Status Indicators

Get an instant overview of the health of each of your apps with status indicators. Once enabled, a small dot next to each app will show weather it is up and online, with more info like response time visible on hover.
Learn more in the Docs Docs

Authentication

Need to protect your dashboard, the simple auth feature is super quick to enable, and has support for multiple users with granular controls. Dashy also has built-in support for Keycloak and other SSO providers.
Learn more in the Docs Docs
Screenshot Coming Soon

Widgets

Display dynamic content from any API-enabled service. Dashy comes bundled with 50+ pre-built widgets for self-hosted services, productivity and monitoring.
Learn more in the Docs Docs

Alternate Views

As well as the default home, there is also a minimal view, which makes a great fast-loading browser startpage. Plus a workspace view useful for working on multiple apps at once, all without having to leave your dashboard.
Learn more in the Docs Docs

Launching Methods

Choose how to launch each of your apps by default, or right click for all options. Apps can be opened in a new tab, the same tab, a quick pop-up modal or in the workspace view.
Learn more in the Docs Docs
Screenshot Coming Soon

Search & Shortcuts

To search, just start typing, results will be filtered instantly. Use the arrow keys or tab to navigate through results, and press enter to launch. You can also create custom shortcuts for frequently used apps, or add custom tags for easier searching. Dashy can also be used to search the web using your favorite search engine.
Learn more in the Docs Docs

Cloud Backup & Sync

There is an optional, end-to-end encrypted, free backup cloud service. This enables you to have your config backed up off-site, and to sync data between multiple instances easily.
Learn more in the Docs Docs
Screenshot Coming Soon

Configuration

Dashy's config is specified in a simple YAML file. But you can also configure the directly through the UI, and have changes written to, and backed up on disk. Real-time validation and hints are in place to help you.
Learn more in the Docs Docs

Multi-Language Support

Dashy's UI has been translated into several languages by several amazing contributors. Currently English, German, French, Dutch and Slovenian are supported. Your language should be applied automatically, or you can change it in the config menu.
Learn more in the Docs Docs
Screenshot Coming Soon

Easy Deployment

Although Dashy can be easily run on bare metal, the quickest method of getting started is with Docker. Just run `docker run -p 8080:80 lissy93/dashy` to pull, build and and run Dashy.
Learn more in the Docs Docs
Screenshot Coming Soon

Customizable Layouts

Structure your dashboard to fit your use case. From the UI, you can choose between different layouts, item sizes, show/ hide components, switch themes plus more. You can customize pretty much every area of your dashboard. There are config options for custom header, footer, nav bar links, title etc. You can also choose to hide any elements you don't need.
Learn more in the Docs Docs
Screenshot Coming Soon
- + \ No newline at end of file diff --git a/markdown-page/index.html b/markdown-page/index.html index 16ab1c0c..b288fc44 100644 --- a/markdown-page/index.html +++ b/markdown-page/index.html @@ -5,13 +5,13 @@ Markdown page example | Dashy - +

Markdown page example

You don't need React to write simple standalone pages.

- + \ No newline at end of file diff --git a/search/index.html b/search/index.html index 1d3d454c..2ead3408 100644 --- a/search/index.html +++ b/search/index.html @@ -5,13 +5,13 @@ Search the documentation | Dashy - +

Search the documentation

- + \ No newline at end of file diff --git a/survey/index.html b/survey/index.html index b6711c99..ad699c2f 100644 --- a/survey/index.html +++ b/survey/index.html @@ -5,13 +5,13 @@ Dashy Survey | Dashy - +
- + \ No newline at end of file