Lissy93/dashy
1
1
Fork 0
mirror of https://github.com/Lissy93/dashy.git synced 2024-12-23 00:41:37 +03:00
Code Issues Packages Projects Releases Wiki Activity

Freshly generated docs, to test prod site

Browse Source
This commit is contained in:
Alicia Sykes 2024-03-06 21:59:45 +00:00
parent 2e67dc718e
commit c3c6bbee16
26 changed files with 3578 additions and 3136 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

128
docs/alternate-views.md
View File

@ -1,64 +1,64 @@
# 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.
<p align="center">
<b>Example of Default View</b><br />
<img width="800" src="https://i.ibb.co/L8YbNNc/dashy-demo2.gif" alt="Demo" />
</p>
### 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.
<p align="center">
<b>Example of Workspace View</b><br />
<img alt="Workspace view demo" src="https://raw.githubusercontent.com/Lissy93/dashy/master/docs/assets/workspace-demo.gif" width="800" />
</p>
### 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).
<p align="center">
<b>Example of Minimal View</b><br />
<img alt="Workspace view demo" src="https://raw.githubusercontent.com/Lissy93/dashy/master/docs/assets/minimal-view-demo.gif" width="800" />
</p>
## 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.
<p align="center">
<img width="500" src="https://i.ibb.co/vmZdSRt/dashy-context-menu-2.png" />
</p>
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](/docs/troubleshootingrefused-to-connect-in-modal-or-workspace-view).
# 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.
<p align="center">
<b>Example of Default View</b><br />
<img width="800" src="https://i.ibb.co/L8YbNNc/dashy-demo2.gif" alt="Demo" />
</p>
### 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.
<p align="center">
<b>Example of Workspace View</b><br />
<img alt="Workspace view demo" src="https://raw.githubusercontent.com/Lissy93/dashy/master/docs/assets/workspace-demo.gif" width="800" />
</p>
### 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).
<p align="center">
<b>Example of Minimal View</b><br />
<img alt="Workspace view demo" src="https://raw.githubusercontent.com/Lissy93/dashy/master/docs/assets/minimal-view-demo.gif" width="800" />
</p>
## 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 you're 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.
<p align="center">
<img width="500" src="https://i.ibb.co/vmZdSRt/dashy-context-menu-2.png" />
</p>
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](/docs/troubleshooting#refused-to-connect-in-modal-or-workspace-view).

459
docs/assets/CONTRIBUTORS.svg
View File

File diff suppressed because one or more lines are too long
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 22 MiB

After

Width:  |  Height:  |  Size: 29 MiB

2
docs/assets/repo-visualization.svg
View File

File diff suppressed because one or more lines are too long
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 104 KiB

After

Width:  |  Height:  |  Size: 94 KiB

32
docs/authentication.md
View File

@ -18,6 +18,12 @@
- [OAuth Services](#oauth-services)
- [Auth on Cloud Hosting Services](#static-site-hosting-providers)
> [!IMPORTANT]
> Dashy's built-in auth is not indented to protect a publicly hosted instance against unauthorized access. Instead you should use an auth provider compatible with your reverse proxy, or access Dashy via your VPN.
>
> In cases where Dashy is only accessibly within your home network, and you just want to add a login page, then the built-in auth may be sufficient, but keep in mind that configuration can still be accessed.
## Built-In Auth
Dashy has a basic login page included, and frontend authentication. You can enable this by adding users to the `auth` section under `appConfig` in your `conf.yml`. If this section is not specified, then no authentication will be required to access the app, and the homepage will resolve to your dashboard.
@ -55,13 +61,25 @@ With authentication set up, by default no access is allowed to your dashboard wi
### Granular Access
You can use the following properties to make certain sections or items only visible to some users, or hide sections and items from guests.
You can use the following properties to make certain pages, sections or items only visible to some users, or hide pages, sections and items from guests.
- `hideForUsers` - Section or Item will be visible to all users, except for those specified in this list
- `showForUsers` - Section or Item will be hidden from all users, except for those specified in this list
- `hideForGuests` - Section or Item will be visible for logged in users, but not for guests
- `hideForUsers` - Page, Section or Item will be visible to all users, except for those specified in this list
- `showForUsers` - Page, Section or Item will be hidden from all users, except for those specified in this list
- `hideForGuests` - Page, Section or Item will be visible for logged in users, but not for guests
For Example:
```yaml
pages:
- name: Home Lab
path: home-lab.yml
displayData:
showForUsers: [admin]
- name: Intranet
path: intranet.yml
displayData:
hideForGuests: true
hideForUsers: [alicia, bob]
```
```yaml
- name: Code Analysis & Monitoring
@ -88,7 +106,7 @@ For Example:
Any user who is not an admin (with `type: admin`) will not be able to write changes to disk.
You can also prevent any user from writing changes to disk, using `preventWriteToDisk`. Or prevent any changes from being saved locally in browser storage, using `preventLocalSave`. Both properties can be found under [`appConfig`](/docs/configuringappconfig-optional).
You can also prevent any user from writing changes to disk, using `preventWriteToDisk`. Or prevent any changes from being saved locally in browser storage, using `preventLocalSave`. Both properties can be found under [`appConfig`](/docs/configuring#appconfig-optional).
To disable all UI config features, including View Config, set `disableConfiguration`. Alternatively you can disable UI config features for all non admin users by setting `disableConfigurationForNonAdmin` to true.
@ -96,7 +114,7 @@ To disable all UI config features, including View Config, set `disableConfigurat
With basic auth, all logic is happening on the client-side, which could mean a skilled user could manipulate the code to view parts of your configuration, including the hash. If the SHA-256 hash is of a common password, it may be possible to determine it, using a lookup table, in order to find the original password. Which can be used to manually generate the auth token, that can then be inserted into session storage, to become a valid logged in user. Therefore, you should always use a long, strong and unique password, and if you instance contains security-critical info and/ or is exposed directly to the internet, and alternative authentication method may be better. The purpose of the login page is merely to prevent immediate unauthorized access to your homepage.
**[⬆️ Back to Top](#)**
**[⬆️ Back to Top](#authentication)**
---
@ -347,4 +365,4 @@ There are also authentication services, such as [Ory.sh](https://www.ory.sh/), [
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](https://docs.netlify.com/visitor-access/password-protection/), [Cloudflare Access](https://www.cloudflare.com/teams/access/), [AWS Cognito](https://aws.amazon.com/cognito/), [Azure Authentication](https://docs.microsoft.com/en-us/azure/app-service/scenario-secure-app-authentication-app-service) and [Vercel Password Protection](https://vercel.com/docs/platform/projects#password-protection).
**[⬆️ Back to Top](#)**
**[⬆️ Back to Top](#authentication)**

222
docs/backup-restore.md
View File

@ -1,111 +1,111 @@
# Cloud Backup and Restore
Dashy has a built-in feature for securely backing up your config to a hosted cloud service, and then restoring it on another instance. This feature is totally optional, and if you do not enable it, then Dashy will not make any external network requests.
This is useful not only for backing up your configuration off-site, but it also enables Dashy to be used without having write a YAML config file, and makes it possible to use a public hosted instance, without the need to self-host.
<p align="center">
<img src="https://i.ibb.co/p4pxSqX/dashy-backup-restore.png" width="600" />
</p>
## How it Works
All data is encrypted before being sent to the backend. In Dashy, this is done in [`CloudBackup.js`](https://github.com/Lissy93/dashy/blob/master/src/utils/CloudBackup.js), using [crypto.js](https://github.com/brix/crypto-js)'s AES method, using the users chosen password as the key. The data is then sent to a [Cloudflare worker](https://developers.cloudflare.com/workers/learning/how-workers-works) (a platform for running serverless functions), and stored in a [KV](https://developers.cloudflare.com/workers/learning/how-kv-works) data store.
## Creating a Backup
Once you've got Dashy configured to your preference, open the Backup & Restore menu (click the Cloud icon in the top-right corner). Here you will be prompted to choose a password, which will be used to encrypt your data. If you forget this password, there will be no way to recover your config. After clicking 'Backup' your data will be encrypted, compressed and sent to the hosted cloud service. A backup ID will be returned (in the format of xxxx-xxxx-xxxx-xxxx), this is what you use, along with your password to restore the backup on another system, so take note of it. To update a backup, return to this menu, enter your password, and click 'Update Backup'.
## Restoring a Backup
To restore a backup, navigate to the Backup & Restore menu, and under restore, enter your backup ID, and the password you chose. Your config file will be downloaded, decrypted and applied to local storage.
## Privacy & Security
Data is only ever sent to the cloud when the user actively triggers a backup. All transmitted data is first encrypted using [AES](https://en.wikipedia.org/wiki/Advanced_Encryption_Standard). Your selected password never leaves your device, and is hashed before being compared. It is only possible to restore a configuration if you have both the backup ID and decryption password.
Because the data is encrypted on the client-side (before being sent to the cloud), it is not possible for a man-in-the-middle, government entity, website owner, or even Cloudflare to be able read any of your data. The biggest risk to your data, would be a weak password, or a compromised system.
Having said that, although the code uses robust security libraries and is open source- it was never intended to be a security product, and has not been audited, and therefore cannot be considered totally secure - please keep that in mind.
## Fair Use Policy
Maximum of 24mb of storage per user. Please do not repeatedly hit the endpoint, as if the quota is exceeded the service may become less available to other users. Abuse may result in your IP being temporarily banned by Cloudflare.
---
## Self-Hosting the Backup Server
### Quick Start
- Install Wrangler CLI Tool: `npm i -g @cloudflare/wrangler`
- Log into Cloudflare account: `wrangler login`
- Create a new project: `wrangler generate my-project`
- Install dependencies: `cd my-project` && `npm i`
### Populate `wrangler.toml`
- Add your `account_id` (found on the right sidebar of the Workers or Overview Dashboard)
- Add your `zone_id` (found in the Overview tab of your desired domain on Cloudflare)
- Add your `route`, which should be a domain or host, supporting a wildcard
```toml
name = "dashy-worker"
type = "javascript"
workers_dev = true
route = "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:
```javascript
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](https://gist.github.com/Lissy93/d19b43d50f30e02fa25f349cf5cb5ed8#file-index-js)
### 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](https://documenter.getpostman.com/view/2142819/TzXumzce).
If you are using Postman, you may find this pre-made [collection](https://www.getpostman.com/collections/58f79ddb150223f67b35) helpful in getting things setup.
# Cloud Backup and Restore
Dashy has a built-in feature for securely backing up your config to a hosted cloud service, and then restoring it on another instance. This feature is totally optional, and if you do not enable it, then Dashy will not make any external network requests.
This is useful not only for backing up your configuration off-site, but it also enables Dashy to be used without having write a YAML config file, and makes it possible to use a public hosted instance, without the need to self-host.
<p align="center">
<img src="https://i.ibb.co/p4pxSqX/dashy-backup-restore.png" width="600" />
</p>
## How it Works
All data is encrypted before being sent to the backend. In Dashy, this is done in [`CloudBackup.js`](https://github.com/Lissy93/dashy/blob/master/src/utils/CloudBackup.js), using [crypto.js](https://github.com/brix/crypto-js)'s AES method, using the users chosen password as the key. The data is then sent to a [Cloudflare worker](https://developers.cloudflare.com/workers/learning/how-workers-works) (a platform for running serverless functions), and stored in a [KV](https://developers.cloudflare.com/workers/learning/how-kv-works) data store.
## Creating a Backup
Once you've got Dashy configured to your preference, open the Backup & Restore menu (click the Cloud icon in the top-right corner). Here you will be prompted to choose a password, which will be used to encrypt your data. If you forget this password, there will be no way to recover your config. After clicking 'Backup' your data will be encrypted, compressed and sent to the hosted cloud service. A backup ID will be returned (in the format of xxxx-xxxx-xxxx-xxxx), this is what you use, along with your password to restore the backup on another system, so take note of it. To update a backup, return to this menu, enter your password, and click 'Update Backup'.
## Restoring a Backup
To restore a backup, navigate to the Backup & Restore menu, and under restore, enter your backup ID, and the password you chose. Your config file will be downloaded, decrypted and applied to local storage.
## Privacy & Security
Data is only ever sent to the cloud when the user actively triggers a backup. All transmitted data is first encrypted using [AES](https://en.wikipedia.org/wiki/Advanced_Encryption_Standard). Your selected password never leaves your device, and is hashed before being compared. It is only possible to restore a configuration if you have both the backup ID and decryption password.
Because the data is encrypted on the client-side (before being sent to the cloud), it is not possible for a man-in-the-middle, government entity, website owner, or even Cloudflare to be able read any of your data. The biggest risk to your data, would be a weak password, or a compromised system.
Having said that, although the code uses robust security libraries and is open source- it was never intended to be a security product, and has not been audited, and therefore cannot be considered totally secure - please keep that in mind.
## Fair Use Policy
Maximum of 24mb of storage per user. Please do not repeatedly hit the endpoint, as if the quota is exceeded the service may become less available to other users. Abuse may result in your IP being temporarily banned by Cloudflare.
---
## Self-Hosting the Backup Server
### Quick Start
- Install Wrangler CLI Tool: `npm i -g @cloudflare/wrangler`
- Log into Cloudflare account: `wrangler login`
- Create a new project: `wrangler generate my-project`
- Install dependencies: `cd my-project` && `npm i`
### Populate `wrangler.toml`
- Add your `account_id` (found on the right sidebar of the Workers or Overview Dashboard)
- Add your `zone_id` (found in the Overview tab of your desired domain on Cloudflare)
- Add your `route`, which should be a domain or host, supporting a wildcard
```toml
name = "dashy-worker"
type = "javascript"
workers_dev = true
route = "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:
```javascript
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](https://gist.github.com/Lissy93/d19b43d50f30e02fa25f349cf5cb5ed8#file-index-js)
### 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](https://documenter.getpostman.com/view/2142819/TzXumzce).
If you are using Postman, you may find this pre-made [collection](https://www.getpostman.com/collections/58f79ddb150223f67b35) helpful in getting things setup.

342
docs/changelog.md
View File

@ -1,9 +1,6 @@
# Changelog
## ✨ 2.1.0 Adds AdGuard Widget [PR #685](https://github.com/Lissy93/dashy/pull/685)
# Changelog# ✨ 2.1.0 Adds AdGuard Widget [PR #685](https://github.com/Lissy93/dashy/pull/685)
- Adds Widgets for AdGuard
## 🐛 2.0.9 Bug Fixes [PR #663](https://github.com/Lissy93/dashy/pull/663)
# 🐛 2.0.9 Bug Fixes [PR #663](https://github.com/Lissy93/dashy/pull/663)
- Fix KeyCloak API URL (#564)
- Fix guest has config access (#590)
- Fix collapsible content in multi-page support (#626)
@ -20,21 +17,18 @@
- Add Font-Awesome displaying as square to troubleshooting guide (#659)
- Show expand / collapse in context menu (#660)
- Only deploy new release when relevant files have changed
## ✨ 2.0.8 Adds Multi-Page Support [PR #617](https://github.com/Lissy93/dashy/pull/617)
# ✨ 2.0.8 Adds Multi-Page Support [PR #617](https://github.com/Lissy93/dashy/pull/617)
- Adds support for multiple pages per-dashboard
- Adds new attribute at root of main config file: `pages`
- Updates router and nav-bar to automatically create paths for both local and remote configs
## ⚡️ 2.0.7 Improves handling of Sections and Items [PR #595](https://github.com/Lissy93/dashy/pull/595)
# ⚡️ 2.0.7 Improves handling of Sections and Items [PR #595](https://github.com/Lissy93/dashy/pull/595)
- Adds functionality for sub-items / item-groups
- Creates an item mixin, for reusing functionality
- Item width calculated based on parent section width
- Improved mobile support, long-press for right-click
- Adds 2 new themes (`lissy` and `charry-blossom`)
- Adds 2 new widgets (`mullvad-status`, and `blacklist-check`)
## 🐛 2.0.6 Fixes user requested issues [PR #557](https://github.com/Lissy93/dashy/pull/557)
# 🐛 2.0.6 Fixes user requested issues [PR #557](https://github.com/Lissy93/dashy/pull/557)
- Allows middle click open new tab, Re: #492
- Implements Max redirects for status checks, Re: #494
- Adds Gitpod config for cloud-ready IDE, Re: #497
@ -50,23 +44,17 @@
- Fixes local image path on sub-page, Re: #570
- Adds typecheck on edit item tags, Re: #575
- Fixes item size in config not honored, Re: #576
## ✨ 2.0.5 - Bug Fixes and a few New Features
#### Partially revert 2.0.4, fixing several issues caused by `conf.yml` not being loaded at startup.
# ✨ 2.0.5 - Bug Fixes and a few New Features# Partially revert 2.0.4, fixing several issues caused by `conf.yml` not being loaded at startup.
This change requires a rebuild of the application when several options under `appConfig` are changed.
Fixes #544 #555
#### Several other changes since 2.0.4, including:
# Several other changes since 2.0.4, including:
The `Add New Section` button on the UI editor now displays if no sections are present. #536
When using SSL, the server can now redirect from HTTP to HTTPS. This is enabled by default when using SSL. #538
Section context menus are now accessible on mobile, and will no longer clip off the screen. #541
Italian translations have been added. #556
## ✨ 2.0.4 - Dynamic Config Loading [PR #528](https://github.com/Lissy93/dashy/pull/528)
# ✨ 2.0.4 - Dynamic Config Loading [PR #528](https://github.com/Lissy93/dashy/pull/528)
- `conf.yml` is now loaded dynamically and the app now only needs a browser refresh on config change, not a full rebuild!
## 🐛 2.0.3 - Bug Fixes [PR #488](https://github.com/Lissy93/dashy/pull/488)
# 🐛 2.0.3 - Bug Fixes [PR #488](https://github.com/Lissy93/dashy/pull/488)
- Press enter to submit login form (Re: #483)
- Allow disabling write to local storage and disk (Re: #485)
- Fix malformed YAML from export config (Re: #482)
@ -77,19 +65,16 @@ Italian translations have been added. #556
- Create a CPU temp widget (Re: #452)
- Add to docs: Keycloak in Kubernetes (Re: #479)
- Add a widget for displaying images (Re: #487)
## ⬆️ 2.0.2 - Dependency Updates [PR #471](https://github.com/Lissy93/dashy/pull/471)
# ⬆️ 2.0.2 - Dependency Updates [PR #471](https://github.com/Lissy93/dashy/pull/471)
- Updates Alpine version for main Dockerfile
- Updates node_modules to latest stable versions
## 🐛 2.0.1 - Fixes Section Height [PR #462](https://github.com/Lissy93/dashy/pull/462)
# 🐛 2.0.1 - Fixes Section Height [PR #462](https://github.com/Lissy93/dashy/pull/462)
- Adds `cutToHeight` to config schema (Re: #461)
- Removes the full-height CSS from colorful theme
- Improved config validation warnings in JSON editor
- Removes empty Keycloak block from appConfig editor
- Adds typechecking to search and clear search for Safari
## ⚡️ 2.0.0 - Small Fixes and Docker Multi-Arch Build [PR #451](https://github.com/Lissy93/dashy/pull/451)
# ⚡️ 2.0.0 - Small Fixes and Docker Multi-Arch Build [PR #451](https://github.com/Lissy93/dashy/pull/451)
- Fixes full-height sections for mobile and Safari (Re: #432, #442)
- Fixes empty section visible in search (Re: #447)
- Fixes numbers omited from tag names (Re: #430)
@ -98,69 +83,57 @@ Italian translations have been added. #556
- Switches recover and death count in Covid widget (Re: #148)
- Improved contrast in light material theme
- Adds new script to lint, test, build and publish a multi-architecture Docker image to various registries
## 💄 1.9.9 - Minor UI + Docs Updates [PR #431](https://github.com/Lissy93/dashy/pull/431)
# 💄 1.9.9 - Minor UI + Docs Updates [PR #431](https://github.com/Lissy93/dashy/pull/431)
- Improved theme support for widgets
- Better widget layout in Workspace and Minimal views
- Updates lots of the docs
## ✨ 1.9.8 - More Widgets and Widget Improvements [PR #425](https://github.com/Lissy93/dashy/pull/425)
# ✨ 1.9.8 - More Widgets and Widget Improvements [PR #425](https://github.com/Lissy93/dashy/pull/425)
- Fixes several minor widget issues raised by users
- Adds several new widgets, for monitoring system
- Better widget data requests and error handling
- Implements widget support into Workspace view
## 🐛 1.9.7 - Minor UI Editor Bug fixes [PR #416](https://github.com/Lissy93/dashy/pull/416)
# 🐛 1.9.7 - Minor UI Editor Bug fixes [PR #416](https://github.com/Lissy93/dashy/pull/416)
- Fixes unable to edit item bug (#415)
- Fixes unable to add new app bug (#390)
- Fixes nav links visibility (#389)
## ⚡️ 1.9.6 - Adds Proxy Support for Widget Requests [PR #392](https://github.com/Lissy93/dashy/pull/392)
# ⚡️ 1.9.6 - Adds Proxy Support for Widget Requests [PR #392](https://github.com/Lissy93/dashy/pull/392)
- Refactors widget mixin to include data requests, so that code can be shared between widgets
- Adds a Node endpoint for proxying requests server-side, used for APIs that are not CORS enabled
- Adds option to config file for user to force proxying of requests
- Writes a Netlify cloud function to support proxying when the app is hosted on Netlify
## 🐛 1.9.5 - Bug fixes and Minor Improvements [PR #388](https://github.com/Lissy93/dashy/pull/388)
# 🐛 1.9.5 - Bug fixes and Minor Improvements [PR #388](https://github.com/Lissy93/dashy/pull/388)
- Adds icon.horse to supported favicon APIs
- Fixes tile move bug, Re: #366
- Fixes save items without title bug, Re: #377
## ✨ 1.9.4 - Widget Support [PR #382](https://github.com/Lissy93/dashy/pull/382)
# ✨ 1.9.4 - Widget Support [PR #382](https://github.com/Lissy93/dashy/pull/382)
- Adds support for dynamic content, through widgets
- Adds 30+ pre-built widgets for general info and self-hosted services
- Writes docs on widget usage
## ⚡️ 1.9.2 - Native SSL Support + Performance Improvements [PR #326](https://github.com/Lissy93/dashy/pull/326)
# ⚡️ 1.9.2 - Native SSL Support + Performance Improvements [PR #326](https://github.com/Lissy93/dashy/pull/326)
- Updates the server to use Express, removing serve-static, connect and body-parser
- Adds native support for passing in self-signed SSL certificates and updates docs
- Updates router to lazy-load additional pages (minimal, workspace, etc)
- Changes default favicon API to allesedv, since faviconkit is down, and adds basic fallback
- Updates GH action build scripts to fallback on context token when running on fork
## 💄 1.9.1 - Editor and Theming Fixes and Improvements [PR #319](https://github.com/Lissy93/dashy/pull/319)
# 💄 1.9.1 - Editor and Theming Fixes and Improvements [PR #319](https://github.com/Lissy93/dashy/pull/319)
- Bug fixes for interactive editor: #310, #311, #312
- Adds option to modify text font through the UI
- Adds two new themes: One Dark and Adventure
- Theming stylesheet refactor, better inheritance
## 🐳 1.9.0 - Alpha of Dashy-Lite Docker Container [PR #306](https://github.com/Lissy93/dashy/pull/306)
# 🐳 1.9.0 - Alpha of Dashy-Lite Docker Container [PR #306](https://github.com/Lissy93/dashy/pull/306)
- Create an Alpine-based container, that serves the built app up with plain NGINX, instead of Node.
- This is much lighter, but doesn't currently support any of the server-side actions (like status-checks, and writing changes to disk)
## ✨ 1.8.9 - All New Interactive Config Editor [PR #298](https://github.com/Lissy93/dashy/pull/298)
# ✨ 1.8.9 - All New Interactive Config Editor [PR #298](https://github.com/Lissy93/dashy/pull/298)
- Builds a new UI-based config editor
- Support for sections, items, app config and page info
- Live preview, and undoing of local changes
- Export config or write changes to disk through UI
## ✨ 1.8.8 - Improved Item Targets [PR #292](https://github.com/Lissy93/dashy/pull/292)
# ✨ 1.8.8 - Improved Item Targets [PR #292](https://github.com/Lissy93/dashy/pull/292)
- Adds support for `_top` and `_parent` anchor targets on items, Re: #289
- Adds `appConfig.defaultOpeningMethod` option to specify default target
- Adds new icons to show items opening method on hover
- Refactors target checking, updates item target docs and schema
## ⚡️ 1.8.7 - Bug Fixes and Improvements [PR #273](https://github.com/Lissy93/dashy/pull/273)
# ⚡️ 1.8.7 - Bug Fixes and Improvements [PR #273](https://github.com/Lissy93/dashy/pull/273)
- Clean URLs without the hash, now using history-mode routing
- New initial main example conf.yml
- Minor UI style updates and fixes
@ -168,11 +141,9 @@ Italian translations have been added. #556
- A new theme, soft-glow
- Container security in management docs, and other things
- Bug fixes, including missing Firefox favicon and fix custom icon paths with base_url
## ⚡️ 1.8.6 - Implementation of VueX [PR: #271](https://github.com/Lissy93/dashy/pull/271)
# ⚡️ 1.8.6 - Implementation of VueX [PR: #271](https://github.com/Lissy93/dashy/pull/271)
- New state management pattern, which should lead to a more organized code base long term, and will also make building out the new UI editor significantly easier to do in a clean and reliable way
## 💄 1.8.5 - Lots of Requested UI Improvements [PR #261](https://github.com/Lissy93/dashy/pull/261)
# 💄 1.8.5 - Lots of Requested UI Improvements [PR #261](https://github.com/Lissy93/dashy/pull/261)
- Adds an option for landing URL in workspace, Re: #255
- Switches to a new API for generative icons, Re: #163
- Adds new tab functionality to Workspace, Re: #254
@ -181,57 +152,46 @@ Italian translations have been added. #556
- Adds native support for common homelab icons, using dashboard-icons
- Improves general responsiveness of home page sections positioning
- Updates, fixes and adds a bunch of actions for easier repo management
## ✨ 1.8.4 - Custom Error Pages [PR #257](https://github.com/Lissy93/dashy/pull/257)
# ✨ 1.8.4 - Custom Error Pages [PR #257](https://github.com/Lissy93/dashy/pull/257)
- Creates a 404 Not Found page
- Routes any missing views to the 404 page
## ⚡️ 1.8.3 - Improved UX for Initial Load [PR #238](https://github.com/Lissy93/dashy/pull/238)
# ⚡️ 1.8.3 - Improved UX for Initial Load [PR #238](https://github.com/Lissy93/dashy/pull/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](https://github.com/Lissy93/dashy/pull/235)
# ✨ 1.8.2 - Serverless Functions for Netlify Instances [PR #235](https://github.com/Lissy93/dashy/pull/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](https://github.com/Lissy93/dashy/pull/234)
# 🩹 1.8.1 - Additional Languages, Bug Fix, and more [PR #234](https://github.com/Lissy93/dashy/pull/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](https://github.com/Lissy93/dashy/pull/226)
# ⚡️ 1.7.7 - Improved Error Handling [PR #226](https://github.com/Lissy93/dashy/pull/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](https://github.com/Lissy93/dashy/pull/224)
# ✨ 1.7.6 - Adds Multi-Search Support with Bangs [PR #224](https://github.com/Lissy93/dashy/pull/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](https://github.com/Lissy93/dashy/pull/223)
# 🎨 1.7.5 - Improved Language Detection & UI [PR #223](https://github.com/Lissy93/dashy/pull/223)
- Makes the auto language detection algo smarter
- Improves responsiveness for the language selector form
## 🌐 1.7.4 - Adds Spanish Translations [PR #222](https://github.com/Lissy93/dashy/pull/222)
# 🌐 1.7.4 - Adds Spanish Translations [PR #222](https://github.com/Lissy93/dashy/pull/222)
- Adds Spanish language file, contributed by @lu4t
## 👷 1.7.3 - CI with GH Actions [PR #212](https://github.com/Lissy93/dashy/pull/212)
# 👷 1.7.3 - CI with GH Actions [PR #212](https://github.com/Lissy93/dashy/pull/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](https://github.com/Lissy93/dashy/pull/203)
# ✨ 1.7.2 - Item Sort Options [PR #203](https://github.com/Lissy93/dashy/pull/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](https://github.com/Lissy93/dashy/pull/201)
# 🐛 1.7.1 - Lots of Tiny Fixes and Improvements [PR #200](https://github.com/Lissy93/dashy/pull/201)
- Removes background in console art
- Updates auto environmental variables
- Icon image assets max height Force same Icon/Item Height #200
@ -240,178 +200,142 @@ Italian translations have been added. #556
- 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](https://github.com/Lissy93/dashy/pull/190)
# 🍻 1.7.0 - Documentation Website [PR #190](https://github.com/Lissy93/dashy/pull/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](https://github.com/Lissy93/dashy/pull/185)
# ✨ 1.6.9 - Web Search Feature [PR #185](https://github.com/Lissy93/dashy/pull/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](https://github.com/Lissy93/dashy/pull/183)
# ⚡️ 1.6.8 - Improved Loading Experience [PR #183](https://github.com/Lissy93/dashy/pull/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](https://github.com/Lissy93/dashy/pull/182)
# ⚡️ 1.6.7 - Option for non-SSL status checks plus minor things [PR #182](https://github.com/Lissy93/dashy/pull/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](https://github.com/Lissy93/dashy/pull/175)
# ⚡️ 1.6.6 - Improved Search & Shortcuts [PR #175](https://github.com/Lissy93/dashy/pull/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](https://github.com/Lissy93/dashy/pull/174)
# ✨ 1.6.5 - Adds support for Secure Authentication using Keycloak [PR #174](https://github.com/Lissy93/dashy/pull/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](https://github.com/Lissy93/dashy/pull/171)
# ✨ 1.6.4 - Adds functionality for Granular Auth Control [PR #171](https://github.com/Lissy93/dashy/pull/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](https://github.com/Lissy93/dashy/pull/168)
# ⚡️ 1.6.3 - Dependency and Build File Updates [PR #168](https://github.com/Lissy93/dashy/pull/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](https://github.com/Lissy93/dashy/pull/167)
# ✨ 1.6.2 - Support for Guest Access [PR #167](https://github.com/Lissy93/dashy/pull/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](https://github.com/Lissy93/dashy/issues/166)
# 💄 1.6.1 - Adds new Theme [PR #166](https://github.com/Lissy93/dashy/issues/166)
- Adds Dashy theme, for use in the dev dashboard
## ✨ 1.5.9 - New Minimal/ Startpage View [PR #155](https://github.com/Lissy93/dashy/issues/155)
# ✨ 1.5.9 - New Minimal/ Startpage View [PR #155](https://github.com/Lissy93/dashy/issues/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](https://github.com/Lissy93/dashy/pull/146)
# ✨ 1.5.8 - Multi-Tasking Support in Workspace View [PR #146](https://github.com/Lissy93/dashy/pull/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](https://github.com/Lissy93/dashy/pull/141)
# ✨ 1.5.7 - Adds Support for Material Design Icons [PR #141](https://github.com/Lissy93/dashy/pull/141)
- Enables user to use any icon from [materialdesignicons.com](https://dev.materialdesignicons.com/icons), Re: #139
- Also adds support for [simpleicons.org](https://simpleicons.org/)
- Assets only loaded when needed
- Adds docs for using MDI icons
## ⚡️ 1.5.6 - Refactor + Couple of small things [PR #135](https://github.com/Lissy93/dashy/pull/135)
# ⚡️ 1.5.6 - Refactor + Couple of small things [PR #135](https://github.com/Lissy93/dashy/pull/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](https://github.com/Lissy93/dashy/pull/129)
# 🌐 1.5.5 - Adds Missing Translations + Small UI Issues [PR #129](https://github.com/Lissy93/dashy/pull/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](https://github.com/Lissy93/dashy/pull/122)
# 🐳 1.5.4 - Docker ARM Support [PR #122](https://github.com/Lissy93/dashy/pull/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](https://github.com/Lissy93/dashy/pull/121)
# 🩹 1.5.3 - UI Quick Fix [PR #121](https://github.com/Lissy93/dashy/pull/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](https://github.com/Lissy93/dashy/pull/120)
# 🌐 1.5.2 - Adds Dutch Translations [PR #120](https://github.com/Lissy93/dashy/pull/120)
- Dutch language support, contributed by @evroon
## 🩹 1.5.1 - UI Quick Fix [PR #116](https://github.com/Lissy93/dashy/pull/116)
# 🩹 1.5.1 - UI Quick Fix [PR #116](https://github.com/Lissy93/dashy/pull/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](https://github.com/Lissy93/dashy/pull/113)
# 🔒 1.5.0 - Improve Robustness of Auth [PR #113](https://github.com/Lissy93/dashy/pull/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](https://github.com/Lissy93/dashy/pull/112)
# ✨ 1.4.8 - Optional Crash Reports [PR #112](https://github.com/Lissy93/dashy/pull/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](https://github.com/Lissy93/dashy/pull/110)
# ♻️ 1.4.7 - Refactor [PR #110](https://github.com/Lissy93/dashy/pull/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](https://github.com/Lissy93/dashy/pull/108)
# 📝 1.4.6 - Documentation Updates [PR #108](https://github.com/Lissy93/dashy/pull/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](https://github.com/Lissy93/dashy/pull/107)
# 🌐 1.4.5 - Adds German Translations [PR #107](https://github.com/Lissy93/dashy/pull/107)
- German language support, contributed by @Niklashere
## ✨ 1.4.4 - Adds Support for Logo Image [PR #105](https://github.com/Lissy93/dashy/pull/105)
# ✨ 1.4.4 - Adds Support for Logo Image [PR #105](https://github.com/Lissy93/dashy/pull/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](https://github.com/Lissy93/dashy/pull/101) and [PR #102](https://github.com/Lissy93/dashy/pull/102)
# ✨ 1.4.3 - Auto-Checks for Updates [PR #101](https://github.com/Lissy93/dashy/pull/101) and [PR #102](https://github.com/Lissy93/dashy/pull/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](https://github.com/Lissy93/dashy/pull/99)
# ✨ 1.4.2 - Adds Multi-Language Support [PR #99](https://github.com/Lissy93/dashy/pull/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](https://github.com/Lissy93/dashy/pull/94)
# ✨ 1.4.1 - Adds Support for Custom Key Bindings [PR #94](https://github.com/Lissy93/dashy/pull/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
# ✨ 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](https://github.com/Lissy93/dashy/pull/92)
# 🔨 1.3.9 - Enable Custom Styesheet in Docker [PR #92](https://github.com/Lissy93/dashy/pull/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](https://github.com/Lissy93/dashy/pull/91)
# 🌟 1.3.8 - Showcase [#91](https://github.com/Lissy93/dashy/pull/91)
- Adds @Shadowking001's screenshot to showcase
## 🌟 1.3.7 - Showcase [PR #84](https://github.com/Lissy93/dashy/pull/84)
# 🌟 1.3.7 - Showcase [PR #84](https://github.com/Lissy93/dashy/pull/84)
- Adds @dtctek's screenshot to showcase
## ✨ 1.3.6 - Enables User to Hide Unwanted Components [PR #78](https://github.com/Lissy93/dashy/pull/78)
# ✨ 1.3.6 - Enables User to Hide Unwanted Components [PR #78](https://github.com/Lissy93/dashy/pull/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](https://github.com/Lissy93/dashy/pull/76)
# ✨ 1.3.5 - Adds Support for Emoji Icons [PR #76](https://github.com/Lissy93/dashy/pull/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](https://github.com/Lissy93/dashy/pull/75)
# 🌟 1.3.4 - Showcase Addition [PR #75](https://github.com/Lissy93/dashy/pull/75)
- Adds @cerealconyogurt's screenshot to the showcase
## 💄 1.3.3 - UI Improvements [PR #73](https://github.com/Lissy93/dashy/pull/73)
# 💄 1.3.3 - UI Improvements [PR #73](https://github.com/Lissy93/dashy/pull/73)
- New style of Large item
- 2 new color themes
- Added CSS variables for search label and footer background
@ -419,28 +343,22 @@ Italian translations have been added. #556
- 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](https://github.com/Lissy93/dashy/pull/72)
# ⚡️ 1.3.0 - Custom Headers for Status Check [PR #72](https://github.com/Lissy93/dashy/pull/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](https://github.com/Lissy93/dashy/pull/68)
# 🌟 1.2.9 - Creates a Showcase Page [PR #68](https://github.com/Lissy93/dashy/pull/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](https://github.com/Lissy93/dashy/pull/66)
# ✨ 1.2.8 - Adds Remember-Me Functionality into the Login Form [PR #66](https://github.com/Lissy93/dashy/pull/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](https://github.com/Lissy93/dashy/pull/62)
# ✨ 1.2.7 - Implements a Right-Click Context Menu [#62](https://github.com/Lissy93/dashy/pull/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](https://github.com/Lissy93/dashy/pull/60)
# ⚡️ 1.2.6 - Make Font Assets Local [PR #60](https://github.com/Lissy93/dashy/pull/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](https://github.com/Lissy93/dashy/pull/57)
# 🐛 1.2.5 - Small Fixes, and Efficiency Improvements [PR #57](https://github.com/Lissy93/dashy/pull/57)
- Adds correct license
- Improves service workers, and adds serviceWorkerStatus local storage item
- Adds missing statusCheck and statusCheckInterval docs into Configuring.md
@ -457,60 +375,48 @@ Italian translations have been added. #556
- 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](https://github.com/Lissy93/dashy/pull/52)
# ✨ 1.2.4 - Adds Support for Continuous Status Checking [#52](https://github.com/Lissy93/dashy/pull/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](https://github.com/Lissy93/dashy/pull/49)
# 🐛 1.2.3 - Bug Fix [PR #49](https://github.com/Lissy93/dashy/pull/49)
- Removes duplicate Docker env var, fixes #48
## ✨ 1.2.2 - Better Favicon Support
# ✨ 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](https://github.com/Lissy93/dashy/pull/44)
# 🐛 1.2.1 - Bugfix [#44](https://github.com/Lissy93/dashy/pull/44)
- Fixes footer positioning on mobile, makes sticky, fixes #42
## ✨ 1.2.0 - Adds Writing Config to Disk from UI Functionality [PR #43](https://github.com/Lissy93/dashy/pull/43)
# ✨ 1.2.0 - Adds Writing Config to Disk from UI Functionality [PR #43](https://github.com/Lissy93/dashy/pull/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](https://github.com/Lissy93/dashy/pull/40)
# 🐛 1.1.8 - Bugfix [#40](https://github.com/Lissy93/dashy/pull/40)
- Status check tooltip was not visible in Material themes, raised in issue #39
## ✨ 1.1.7 - Adds Workspace View [PR #38](https://github.com/Lissy93/dashy/pull/38)
# ✨ 1.1.7 - Adds Workspace View [PR #38](https://github.com/Lissy93/dashy/pull/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](https://github.com/Lissy93/dashy/pull/34)
# ✨ 1.1.6 - Implements Status Indicators, and Monitoring Functionality [PR #34](https://github.com/Lissy93/dashy/pull/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](https://github.com/Lissy93/dashy/pull/32)
# ✨ 1.1.5 - Adds Authentication / Login Functionality [PR #32](https://github.com/Lissy93/dashy/pull/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](https://github.com/Lissy93/dashy/pull/30)
# 💄 1.1.4 - Support for Custom HTML Footer [PR #30](https://github.com/Lissy93/dashy/pull/30)
- Enables user to insert structure for the footer defined as HTML
## 🚀 1.1.3 - Adds Support for 1-Click Cloud Deployments [PR #29](https://github.com/Lissy93/dashy/pull/29)
# 🚀 1.1.3 - Adds Support for 1-Click Cloud Deployments [PR #29](https://github.com/Lissy93/dashy/pull/29)
- Support for 1-Click Deploy to Netlify
- Support for 1-Click Deploy to Heroku
## 🔧 1.1.2 - Docker Efficiency Improvements [PR #26](https://github.com/Lissy93/dashy/pull/26)
# 🔧 1.1.2 - Docker Efficiency Improvements [PR #26](https://github.com/Lissy93/dashy/pull/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
@ -520,8 +426,7 @@ Italian translations have been added. #556
- 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](https://github.com/Lissy93/dashy/pull/20) + [PR #21](https://github.com/Lissy93/dashy/pull/21)
# 🐛 1.1.1 - Bug Fixes [PR #20](https://github.com/Lissy93/dashy/pull/20) + [PR #21](https://github.com/Lissy93/dashy/pull/21)
- Adds issue template
- Bug fixes
- Improves github PR and issue templates
@ -533,12 +438,10 @@ Italian translations have been added. #556
- Adds minimum dimensions to modalsShortens readme file
- Adds documentation in the docs folder
- Adds minimum dimensions to modals
## 🚑️ 1.1.0 - Hotfix [#18](https://github.com/Lissy93/dashy/pull/18)
# 🚑️ 1.1.0 - Hotfix [#18](https://github.com/Lissy93/dashy/pull/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](https://github.com/Lissy93/dashy/pull/16)
# 📝 1.0.5 - Documentation [PR #16](https://github.com/Lissy93/dashy/pull/16)
- Previously there was very little documentation, this release fixed that
- Wrote specific docs for:
- Getting Started
@ -546,36 +449,30 @@ Italian translations have been added. #556
- Backup & Restore
- Theming
- Developing
## ✨ 1.0.0 - Implements Config Validation [PR #13](https://github.com/Lissy93/dashy/pull/13)
# ✨ 1.0.0 - Implements Config Validation [PR #13](https://github.com/Lissy93/dashy/pull/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](https://github.com/Lissy93/dashy/pull/12)
# 🔧 0.9.5 - Brand New Docker Container [PR #12](https://github.com/Lissy93/dashy/pull/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](https://github.com/Lissy93/dashy/pull/11)
# ✨ 0.9.0 - Adds Hide Settings Functionality [PR #11](https://github.com/Lissy93/dashy/pull/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](https://github.com/Lissy93/dashy/pull/9)
# 💄 0.8.5 - Adds new Built-In Themes [PR #9](https://github.com/Lissy93/dashy/pull/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](https://github.com/Lissy93/dashy/pull/8)
# ✨ 0.8.0 - Implements Custom CSS Editor [PR: #8](https://github.com/Lissy93/dashy/pull/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](https://github.com/Lissy93/dashy/pull/6)
# ✨ 0.7.5 - Adds Cloud Backup and Restore Feature [PR #6](https://github.com/Lissy93/dashy/pull/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
@ -583,69 +480,56 @@ Italian translations have been added. #556
- 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](https://github.com/Lissy93/dashy/pull/4)
# ✨ 0.7.0 - Support for Custom Nav Links [PR #4](https://github.com/Lissy93/dashy/pull/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](https://github.com/Lissy93/dashy/pull/3)
# ✨ 0.6.5 - UI Config Editor [PR #3](https://github.com/Lissy93/dashy/pull/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
# ✨ 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
# ⚡️ 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
# ✨ 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
# ✨ 0.4.5 - Keyboard Navigation
- Implements arrow key navigation
## ✨ 0.4.0 - Font Awesome Support
# ✨ 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
# ✨ 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
# 🔨 0.3.0 - Docker
- Writes a Dockerfile
## 🎨 0.2.5 - Code Quality, Docs and UI
# 🎨 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
# ✨ 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
# ⚡️ 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
# 🎉 0.1.0 - Init
Project started. Forked from [Lissy93/Dash](https://github.com/Lissy93/dash)

45
docs/code-of-conduct.md
View File

@ -1,7 +1,4 @@
# Contributor Covenant Code of Conduct
## Our Pledge
# Contributor Covenant Code of Conduct# Our Pledge
We as members, contributors, and leaders pledge to make participation in our
community a harassment-free experience for everyone, regardless of age, body
size, visible or invisible disability, ethnicity, sex characteristics, gender
@ -11,9 +8,7 @@ and orientation.
We pledge to act and interact in ways that contribute to an open, welcoming,
diverse, inclusive, and healthy community.
## Our Standards
# Our Standards
Examples of behavior that contributes to a positive environment for our
community include:
@ -35,9 +30,7 @@ Examples of unacceptable behavior include:
address, without their explicit permission
* Other conduct which could reasonably be considered inappropriate in a
professional setting
## Enforcement Responsibilities
# Enforcement Responsibilities
Community leaders are responsible for clarifying and enforcing our standards of
acceptable behavior and will take appropriate and fair corrective action in
response to any behavior that they deem inappropriate, threatening, offensive,
@ -47,17 +40,13 @@ Community leaders have the right and responsibility to remove, edit, or reject
comments, commits, code, wiki edits, issues, and other contributions that are
not aligned to this Code of Conduct, and will communicate reasons for moderation
decisions when appropriate.
## Scope
# Scope
This Code of Conduct applies within all community spaces, and also applies when
an individual is officially representing the community in public spaces.
Examples of representing our community include using an official e-mail address,
posting via an official social media account, or acting as an appointed
representative at an online or offline event.
## Enforcement
# Enforcement
Instances of abusive, harassing, or otherwise unacceptable behavior may be
reported to the community leaders responsible for enforcement at
alicia@omg.lol.
@ -65,23 +54,17 @@ All complaints will be reviewed and investigated promptly and fairly.
All community leaders are obligated to respect the privacy and security of the
reporter of any incident.
## Enforcement Guidelines
# Enforcement Guidelines
Community leaders will follow these Community Impact Guidelines in determining
the consequences for any action they deem in violation of this Code of Conduct:
### 1. Correction
# 1. Correction
**Community Impact**: Use of inappropriate language or other behavior deemed
unprofessional or unwelcome in the community.
**Consequence**: A private, written warning from community leaders, providing
clarity around the nature of the violation and an explanation of why the
behavior was inappropriate. A public apology may be requested.
### 2. Warning
# 2. Warning
**Community Impact**: A violation through a single incident or series
of actions.
@ -91,9 +74,7 @@ those enforcing the Code of Conduct, for a specified period of time. This
includes avoiding interactions in community spaces as well as external channels
like social media. Violating these terms may lead to a temporary or
permanent ban.
### 3. Temporary Ban
# 3. Temporary Ban
**Community Impact**: A serious violation of community standards, including
sustained inappropriate behavior.
@ -102,18 +83,14 @@ communication with the community for a specified period of time. No public or
private interaction with the people involved, including unsolicited interaction
with those enforcing the Code of Conduct, is allowed during this period.
Violating these terms may lead to a permanent ban.
### 4. Permanent Ban
# 4. Permanent Ban
**Community Impact**: Demonstrating a pattern of violation of community
standards, including sustained inappropriate behavior, harassment of an
individual, or aggression toward or disparagement of classes of individuals.
**Consequence**: A permanent ban from any sort of public interaction within
the community.
## Attribution
# Attribution
This Code of Conduct is adapted from the [Contributor Covenant][homepage],
version 2.0, available at
https://www.contributor-covenant.org/version/2/0/code_of_conduct.html.

55
docs/configuring.md
View File

@ -63,7 +63,7 @@ The following file provides a reference of all supported configuration options.
**`sections`** | `array` | Required | An array of sections, each containing an array of items, which will be displayed as links. See [`section`](#section)
**`pages`** | `array` | _Optional_ | An array additional config files, used for multi-page dashboards. See [`pages`](#pages-optional)
**[⬆️ Back to Top](#)**
**[⬆️ Back to Top](#configuring)**
## `PageInfo`
@ -75,7 +75,7 @@ The following file provides a reference of all supported configuration options.
**`footerText`** | `string` | _Optional_ | Text to display in the footer (note that this will override the default footer content). This can also include HTML and inline CSS
**`logo`** | `string` | _Optional_ | The 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](#)**
**[⬆️ Back to Top](#configuring)**
## `pageInfo.navLinks` _(optional)_
@ -85,7 +85,7 @@ The following file provides a reference of all supported configuration options.
**`path`** | `string` | Required | The 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`)
**`target`** | `string` | _Optional_ | The opening method (external links only). Can be either `newtab`, `sametab`, `top` or `parent`. Defaults to `newtab`
**[⬆️ Back to Top](#)**
**[⬆️ Back to Top](#configuring)**
## `pages[]` _(optional)_
@ -94,7 +94,7 @@ The following file provides a reference of all supported configuration options.
**`name`** | `string` | Required | A unique name for that page
**`path`** | `string` | Required | The path (local or remote) to the config file to use.<br />For files located within `/public`, you only need to specify filename, for externally hosted files you must include the full URL
**[⬆️ Back to Top](#)**
**[⬆️ Back to Top](#configuring)**
## `appConfig` _(optional)_
@ -104,21 +104,21 @@ The following file provides a reference of all supported configuration options.
**`startingView`** | `enum` | _Optional_ | Which page to load by default, and on the base page or domain root. You can still switch to different views from within the UI. Can be either `default`, `minimal` or `workspace`. Defaults to `default`
**`defaultOpeningMethod`** | `enum` | _Optional_ | The 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`
**`statusCheck`** | `boolean` | _Optional_ | When set to `true`, Dashy will ping each of your services and display their status as a dot next to each item. This can be overridden by setting `statusCheck` under each item. Defaults to `false`
**`statusCheckInterval`** | `boolean` | _Optional_ | The number of seconds between checks. If set to `0` then service will only be checked on initial page load, which is usually the desired functionality. If value is less than `10` you may experience a hit in performance. Defaults to `0`
**`statusCheckInterval`** | `number` | _Optional_ | The number of seconds between checks. If set to `0` then service will only be checked on initial page load, which is usually the desired functionality. If value is less than `10` you may experience a hit in performance. Defaults to `0`
**`webSearch`** | `object` | _Optional_ | Configuration options for the web search feature, set your default search engine, opening method or disable web search. See [`webSearch`](#appconfigwebsearch-optional)
**`backgroundImg`** | `string` | _Optional_ | Path to an optional full-screen app background image. This can be either remote (http) or local (/). Note that this will slow down initial load
**`backgroundImg`** | `string` | _Optional_ | Path to an optional full-screen app background image. This can be either remote (http) or local (relative to /app/public/item-icons/ inside the container). Note that this will slow down initial load
**`enableFontAwesome`** | `boolean` | _Optional_ | If set to `true` font-awesome will be loaded, if set to `false` they will not be. if left blank font-awesome will be enabled only if required by 1 or more icons
**`enableMaterialDesignIcons`** | `boolean` | _Optional_ | If set to `true` mdi icons will be loaded, if set to `false` they will not be. Where `true` is enabled, if left blank material design icons will be enabled only if required by 1 or more icons
**`fontAwesomeKey`** | `string` | _Optional_ | If you have a font-awesome key, then you can use it here and make use of premium icons. It is a 10-digit alpha-numeric string from you're FA kit URL (e.g. `13014ae648`)
**`faviconApi`** | `enum` | _Optional_ | Only applicable if you are using favicons for item icons. Specifies which service to use to resolve favicons. Set to `local` to do this locally, without using an API. Services running locally will use this option always. Available options are: `local`, `faviconkit`, `iconhorse`, `google`, `clearbit`, `webmasterapi` and `allesedv`. Defaults to `faviconkit`. See [Icons](/docs/iconsfavicons) for more info
**`faviconApi`** | `enum` | _Optional_ | Only applicable if you are using favicons for item icons. Specifies which service to use to resolve favicons. Set to `local` to do this locally, without using an API. Services running locally will use this option always. Available options are: `local`, `faviconkit`, `iconhorse`, `google`, `clearbit`, `webmasterapi` and `allesedv`. Defaults to `faviconkit`. See [Icons](/docs/icons#favicons) for more info
**`auth`** | `object` | _Optional_ | All settings relating to user authentication. See [`auth`](#appconfigauth-optional)
**`defaultIcon`** | `string` | _Optional_ | An icon to be applied to any items, which don't already have an icon set. See [Icon Docs](/docs/iconsdefault-icon) for more info
**`defaultIcon`** | `string` | _Optional_ | An icon to be applied to any items, which don't already have an icon set. See [Icon Docs](/docs/icons#default-icon) for more info
**`layout`** | `enum` | _Optional_ | Layout 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.
**`iconSize`** | `enum` | _Optional_ | The size of link items / icons. Can be either `small`, `medium,` or `large`. Defaults to `medium`. This can also be set directly from the UI.
**`colCount`** | `number` | _Optional_ | The 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.
**`theme`** | `string` | _Optional_ | The default theme for first load (you can change this later from the UI)
**`cssThemes`** | `string[]` | _Optional_ | An array of custom theme names which can be used in the theme switcher dropdown
**`customColors`** | `object`| _Optional_ | Enables 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](/docs/themingmodifying-theme-colors) for more info
**`customColors`** | `object`| _Optional_ | Enables 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](/docs/theming#modifying-theme-colors) for more info
**`externalStyleSheet`** | `string` or `string[]` | _Optional_ | Either a URL to an external stylesheet or an array or URLs, which can be applied as themes within the UI
**`customCss`** | `string` | _Optional_ | Raw CSS that will be applied to the page. This can also be set from the UI. Please minify it first.
**`hideComponents`** | `object` | _Optional_ | A 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`](#appconfighideComponents-optional)
@ -138,20 +138,20 @@ The following file provides a reference of all supported configuration options.
**`enableServiceWorker`** | `boolean` | _Optional_ | Service workers cache web applications to improve load times and offer basic offline functionality, and are enabled by default in Dashy. The service worker can sometimes cause older content to be cached, requiring the app to be hard-refreshed. If you do not want SW functionality, or are having issues with caching, set this property to `false` to disable all service workers.
**`disableContextMenu`** | `boolean` | _Optional_ | If set to `true`, the custom right-click context menu will be disabled. Defaults to `false`.
**[⬆️ Back to Top](#)**
**[⬆️ Back to Top](#configuring)**
## `appConfig.auth` _(optional)_
**Field** | **Type** | **Required**| **Description**
--- | --- | --- | ---
**`users`** | `array` | _Optional_ | An array of objects containing usernames and hashed passwords. If this is not provided, then authentication will be off by default, and you will not need any credentials to access the app. See [`appConfig.auth.users`](#appconfigauthusers-optional). <br />**Note** this method of authentication is handled on the client side, so for security critical situations, it is recommended to use an [alternate authentication method](/docs/authenticationalternative-authentication-methods).
**`users`** | `array` | _Optional_ | An array of objects containing usernames and hashed passwords. If this is not provided, then authentication will be off by default, and you will not need any credentials to access the app. See [`appConfig.auth.users`](#appconfigauthusers-optional). <br />**Note** this method of authentication is handled on the client side, so for security critical situations, it is recommended to use an [alternate authentication method](/docs/authentication#alternative-authentication-methods).
**`enableKeycloak`** | `boolean` | _Optional_ | If set to `true`, then authentication using Keycloak will be enabled. Note that you need to have an instance running, and have also configured `auth.keycloak`. Defaults to `false`
**`keycloak`** | `object` | _Optional_ | Config options to point Dashy to your Keycloak server. Requires `enableKeycloak: true`. See [`auth.keycloak`](#appconfigauthkeycloak-optional) for more info
**`enableGuestAccess`** | `boolean` | _Optional_ | When set to `true`, an unauthenticated user will be able to access the dashboard, with read-only access, without having to login. Requires `auth.users` to be configured. Defaults to `false`.
For more info, see the **[Authentication Docs](/docs/authentication)**
**[⬆️ Back to Top](#)**
**[⬆️ Back to Top](#configuring)**
## `appConfig.auth.users` _(optional)_
@ -161,7 +161,7 @@ For more info, see the **[Authentication Docs](/docs/authentication)**
**`hash`** | `string` | Required | A SHA-256 hashed password
**`type`** | `string` | _Optional_ | The user type, either admin or normal
**[⬆️ Back to Top](#)**
**[⬆️ Back to Top](#configuring)**
## `appConfig.auth.keycloak` _(optional)_
@ -172,7 +172,7 @@ For more info, see the **[Authentication Docs](/docs/authentication)**
**`clientId`** | `string` | Required | The Client ID of the client you created for use with Dashy
**`legacySupport`** | `boolean` | _Optional_ | If using Keycloak 17 or older, then set this to `true`
**[⬆️ Back to Top](#)**
**[⬆️ Back to Top](#configuring)**
## `appConfig.webSearch` _(optional)_
@ -184,7 +184,7 @@ For more info, see the **[Authentication Docs](/docs/authentication)**
**`openingMethod`** | `string` | _Optional_ | Set your preferred opening method for search results: `newtab`, `sametab`, `workspace`. Defaults to `newtab`
**`searchBangs`** | `object` | _Optional_ | A key-value-pair set of custom search _bangs_ for redirecting query to a specific app or search engine. The key of each should be the bang you will type (typically starting with `/`, `!` or `:`), and value is the destination, either as a search engine key (e.g. `reddit`) or a URL with search parameters (e.g. `https://en.wikipedia.org/w/?search=`)
**[⬆️ Back to Top](#)**
**[⬆️ Back to Top](#configuring)**
## `appConfig.hideComponents` _(optional)_
@ -196,7 +196,7 @@ For more info, see the **[Authentication Docs](/docs/authentication)**
**`hideSettings`** | `boolean` | _Optional_ | If set to `true`, the settings menu will be initially collapsed. Defaults to `false`
**`hideFooter`** | `boolean` | _Optional_ | If set to `true`, the footer will not be visible. Defaults to `false`
**[⬆️ Back to Top](#)**
**[⬆️ Back to Top](#configuring)**
## `section`
@ -208,7 +208,7 @@ For more info, see the **[Authentication Docs](/docs/authentication)**
**`widgets`** | `array` | _Optional_ | An array of widgets to be displayed within the section. See [`widget`](#sectionwidget-optional)
**`displayData`** | `object` | _Optional_ | Meta-data to optionally override display settings for a given section. See [`displayData`](#sectiondisplaydata-optional)
**[⬆️ Back to Top](#)**
**[⬆️ Back to Top](#configuring)**
## `section.item`
@ -228,11 +228,12 @@ For more info, see the **[Authentication Docs](/docs/authentication)**
**`statusCheckAcceptCodes`** | `string` | _Optional_ | If your service's response code is anything other than 2xx, then you can opt to specify an alternative success code. E.g. if you expect your server to return 403, but still want the status indicator to be green, set this value to `403`
**`statusCheckMaxRedirects`** | `number` | _Optional_ | If your service redirects to another page, and you would like status checks to follow redirects, then specify the maximum number of redirects here. Defaults to `0` / will not follow redirects
**`color`** | `string` | _Optional_ | An optional color for the text and font-awesome icon to be displayed in. Note that this will override the current theme and so may not display well
**`rel`** | `string` | _Optional_ | The value of the `rel` attribute for the link. Useful for specifying the relationship between the target link/document and Dashy. Defaults to `noopener noreferrer`
**`backgroundColor`** | `string` | _Optional_ | An optional background fill color for the that given item. Again, this will override the current theme and so might not display well against the background
**`provider`** | `string` | _Optional_ | The name of the provider for a given service, useful for when including hosted apps. In some themes, this is visible under the item name
**`displayData`** | `object` | _Optional_ | Meta-data to optionally override display settings for a given item. See [`displayData`](#itemdisplaydata-optional)
**[⬆️ Back to Top](#)**
**[⬆️ Back to Top](#configuring)**
## `item.displayData` _(optional)_
@ -244,21 +245,21 @@ For more info, see the **[Authentication Docs](/docs/authentication)**
**`hideForKeycloakUsers`** | `object` | _Optional_ | Current item will be visible to all keycloak users, except for those configured via these groups and roles. See `hideForKeycloakUsers`
**`showForKeycloakUsers`** | `object` | _Optional_ | Current item will be hidden from all keycloak users, except for those configured via these groups and roles. See `showForKeycloakUsers`
**[⬆️ Back to Top](#)**
**[⬆️ Back to Top](#configuring)**
## `section.widget` _(optional)_
## `section.widgets` _(optional)_
**Field** | **Type** | **Required**| **Description**
--- | --- | --- | ---
**`type`** | `string` | Required | The widget type. See [Widget Docs](/docs/widgets) for full list of supported widgets
**`options`** | `object` | _Optional_ | Some widgets accept either optional or required additional options. Again, see the [Widget Docs](/docs/widgets) for full list of options
**`updateInterval`** | `number` | _Optional_ | You can keep a widget constantly updated by specifying an update interval, in seconds. See [Continuous Updates Docs](/docs/widgetscontinuous-updates) for more info
**`useProxy`** | `boolean` | _Optional_ | Some 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](/docs/widgetsproxying-requests) for more info
**`updateInterval`** | `number` | _Optional_ | You can keep a widget constantly updated by specifying an update interval, in seconds. See [Continuous Updates Docs](/docs/widgets#continuous-updates) for more info
**`useProxy`** | `boolean` | _Optional_ | Some 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](/docs/widgets#proxying-requests) for more info
**`timeout`** | `number` | _Optional_ | Request timeout in milliseconds, defaults to ½ a second (`500`)
**`ignoreErrors`** | `boolean` | _Optional_ | Prevent an error message being displayed, if a network request or something else fails. Useful for false-positives
**`label`** | `string` | _Optional_ | Add custom label to a given widget. Useful for identification, if there are multiple of the same type of widget in a single section
**[⬆️ Back to Top](#)**
**[⬆️ Back to Top](#configuring)**
## `section.displayData` _(optional)_
@ -281,7 +282,7 @@ For more info, see the **[Authentication Docs](/docs/authentication)**
**`hideForKeycloakUsers`** | `object` | _Optional_ | Current section will be visible to all keycloak users, except for those configured via these groups and roles. See `hideForKeycloakUsers`
**`showForKeycloakUsers`** | `object` | _Optional_ | Current section will be hidden from all keycloak users, except for those configured via these groups and roles. See `showForKeycloakUsers`
**[⬆️ Back to Top](#)**
**[⬆️ Back to Top](#configuring)**
## `section.icon` and `section.item.icon`
@ -289,7 +290,7 @@ For more info, see the **[Authentication Docs](/docs/authentication)**
--- | --- | --- | ---
**`icon`** | `string` | _Optional_ | The icon for a given item or section. <br />See [Icon Docs](/docs/icons) 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](#)**
**[⬆️ Back to Top](#configuring)**
## `section.displayData.hideForKeycloakUsers`, `section.displayData.showForKeycloakUsers`, `item.displayData.hideForKeycloakUsers` and `item.displayData.showForKeycloakUsers`
@ -298,7 +299,7 @@ For more info, see the **[Authentication Docs](/docs/authentication)**
**`groups`** | `string[]` | _Optional_ | Current Section or Item will be hidden or shown based on the user having any of the groups in this list
**`roles`** | `string[]` | _Optional_ | Current Section or Item will be hidden or shown based on the user having any of the roles in this list
**[⬆️ Back to Top](#)**
**[⬆️ Back to Top](#configuring)**
---
@ -376,4 +377,4 @@ If you need any help, feel free to [Raise an Issue](https://github.com/Lissy93/d
Happy Configuring 🤓🔧
**[⬆️ Back to Top](#)**
**[⬆️ Back to Top](#configuring)**

7
docs/contributing.md
View File

@ -26,6 +26,7 @@ Don't feel any pressure to donate anything, as Dashy and my other projects will
Sponsoring will give you several perks - for $1 / £0.75 per month, you'll get a sponsor badge on your profile, be credited on the Dashy's readme, with a link to your website/ profile/ socials, get priority support, have your feature ideas implemented, plus lots more. For more info, see [@Lissy93's Sponsor Page](https://github.com/sponsors/Lissy93).
## Enable Anonymous Bug Reports
Bug reports helps me to discover bugs I was unaware of, and then fix them, in order to make Dashy more reliable long term. This is a simple, yet really helpful step you can take to help improve Dashy. [Sentry](https://github.com/getsentry/sentry) is an open source error tracking and performance monitoring tool, which enables the identification any errors which occur in the production app (only if you enable it).
@ -41,7 +42,7 @@ All reporting is **disabled** by default, and no data will ever be sent to any e
## Add Translations
If you speak another language, then adding translations will help make Dashy available to non-native English speakers. This is a very quick and easy task, as all application text is located in [`locales/en.json`](https://github.com/Lissy93/dashy/blob/master/src/assets/locales/en.json), so adding a new language is as simple as copying this file and translating the values. You don't have to translate it all, as any missing attributes will just fallback to English. For a full tutorial, see the [Multi-Language Support Docs](https://github.com/Lissy93/dashy/blob/master/docs/multi-language-support).
If you speak another language, then adding translations will help make Dashy available to non-native English speakers. This is a very quick and easy task, as all application text is located in [`locales/en.json`](https://github.com/Lissy93/dashy/blob/master/src/assets/locales/en.json), so adding a new language is as simple as copying this file and translating the values. You don't have to translate it all, as any missing attributes will just fallback to English. For a full tutorial, see the [Multi-Language Support Docs](https://github.com/Lissy93/dashy/blob/master/docs/multi-language-support.md).
## Submit a PR
@ -115,7 +116,9 @@ If you like, you could also consider [subscribing to my mailing list](https://no
For a full list of Dashy's contributors, see the [Credits Page](/docs/credits)
[![Auto-generated contributors](https://raw.githubusercontent.com/Lissy93/dashy/master/docs/assets/CONTRIBUTORS.svg)](/docs/credits)
[
![Auto-generated contributors](https://raw.githubusercontent.com/Lissy93/dashy/master/docs/assets/CONTRIBUTORS.svg)
](credits.md)
### Star-Gazers Over Time

1168
docs/credits.md
View File

File diff suppressed because it is too large Load Diff

724
docs/deployment.md
View File

@ -1,344 +1,380 @@
# 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](/docs/quick-start), then you can spin up a new instance of Dashy by running:
```bash
docker run -p 8080:80 lissy93/dashy
```
See [Management Docs](/docs/management) 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](/docs/configuring).
## Deployment Methods
- [Deploy with Docker](#deploy-with-docker)
- [Using Docker Compose](#using-docker-compose)
- [Unraid](#unraid)
- [Synology NAS](#synology-nas)
- [Build from Source](#build-from-source)
- [Hosting with CDN](#hosting-with-cdn)
- [Run as executable](#run-as-executable)
- [Install with NPM](#install-with-npm)
- [Deploy to cloud service](#deploy-to-cloud-service)
- [Use managed instance](#use-managed-instance)
---
## Deploy with Docker
**Container Info**: [
![Docker Supported Architecture](https://img.shields.io/badge/Architectures-amd64%20|%20arm32v7%20|%20arm64v8-6ba6e5)
![Docker Base Image](https://img.shields.io/badge/Base_Image-Alpine_3.14-6ba6e5)
![Docker Hosted on](https://img.shields.io/badge/Hosted_on-DockerHub-6ba6e5)
](https://hub.docker.com/r/lissy93/dashy)<br />
**Status**: [
![Docker Build Status](https://img.shields.io/docker/cloud/build/lissy93/dashy?label=Docker%20Build)
![Docker Pulls](https://img.shields.io/docker/pulls/lissy93/dashy?color=ecb2f7)
![Docker Stars](https://img.shields.io/docker/stars/lissy93/dashy?color=f7f754&label=Docker%20Stars)
![Docker Image Size](https://img.shields.io/docker/image-size/lissy93/dashy/latest?color=1eea76)
![Docker Cloud Build](https://img.shields.io/docker/cloud/automated/lissy93/dashy?color=f4a966&label=Docker%20Build)
](https://hub.docker.com/r/lissy93/dashy)
Dashy has a built container image hosted on [Docker Hub](https://hub.docker.com/r/lissy93/dashy). You will need [Docker](https://docs.docker.com/get-docker/) installed on your system.
```bash
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](https://hub.docker.com/r/lissy93/dashy/tags)
For all available options, and to learn more, see the [Docker Run Docs](https://docs.docker.com/engine/reference/commandline/run/)
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`](https://github.com/Lissy93/dashy/blob/master/docker-compose.yml) for Dashy. Run it as is, or uncomment the additional options you need.
```yaml
---
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](https://github.com/Lissy93/dashy/tree/master/docker), 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
Installing dashy is really simply and fast:
1. Install Docker via Synology ```Package Center```.
2. Go to ```File Station``` and open the ```docker``` folder. Inside the docker folder, create one new folder and name it ```dashy```.
> Note: Be careful to enter only lowercase, not uppercase letters.
3. Go to Control Panel / Task Scheduler / Create / Scheduled Task / User-defined script.
4. Once you click on ```User-defined``` script a new window will open.
5. Follow the instructions below:
6. General: In the Task field type in Install dashy. Uncheck "Enabled" option. Select root User.
7. Schedule: Select Run on the following date then select "Do not repeat".
8. Task Settings: Check "Send run details by email", add your email then copy paste the code below in the Run command area. After that click OK.
```bash
docker run -d \
-p 4000:80 \
-v /volume1/docker/dashy/my-local-conf.yml:/app/public/conf.yml \
--name dashy \
--restart=always \
lissy93/dashy:latest
```
dashy should be up within 1-2min after you've started the install task procedure
---
## 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](https://git-scm.com/downloads) and the latest or LTS version of [Node.js](https://nodejs.org/) installed, and optionally [yarn](https://yarnpkg.com/)
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`](https://github.com/Lissy93/dashy/tree/deploy_cloudflare), [`deploy_digital-ocean`](https://github.com/Lissy93/dashy/tree/deploy_digital-ocean), [`deploy_platform-sh`](https://github.com/Lissy93/dashy/tree/deploy_platform-sh) and [`deploy_render`](https://github.com/Lissy93/dashy/tree/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 available. 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](https://i.ibb.co/GtKMysT/deploy-netlify-button.png)](https://app.netlify.com/start/deploy?repository=https://github.com/lissy93/dashy)
[Netlify](https://www.netlify.com/) 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
```text
https://app.netlify.com/start/deploy?repository=https://github.com/lissy93/dashy
```
### Heroku
[![Deploy to Heroku](https://i.ibb.co/GdMFzBP/deploy-heroku-button.png)](https://heroku.com/deploy?template=https://github.com/Lissy93/dashy)
[Heroku](https://www.heroku.com/) 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 costs a minimum of $5 for 1,000 dyno hours per month (there are around 720 hours in a month), 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
```text
https://heroku.com/deploy?template=https://github.com/Lissy93/dashy
```
### Cloudflare Workers
[![Deploy to Cloudflare Workers](https://i.ibb.co/jf9xVdm/deploy-cloudflare-button.png)](https://deploy.workers.cloudflare.com/?url=https://github.com/lissy93/dashy/tree/deploy_cloudflare)
[Cloudflare Workers](https://workers.cloudflare.com/) 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](https://developers.cloudflare.com/workers/platform/sites)
To deploy Dashy to Cloudflare, use the following link
```text
https://deploy.workers.cloudflare.com/?url=https://github.com/lissy93/dashy/tree/deploy_cloudflare
```
### Vercel
[![Deploy with Vercel](https://i.ibb.co/mJF3R7m/deploy-vercel-button.png)](https://vercel.com/new/project?template=https://github.com/lissy93/dashy)
[Vercel](https://vercel.com/) is a performance-focused platform for hosting static frontend apps. It comes bundled with some useful tools for monitoring and analyzing 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
```text
https://vercel.com/new/project?template=https://github.com/lissy93/dashy
```
### DigitalOcean
[![Deploy to DO](https://i.ibb.co/PFt0PkB/deploy-digital-ocean-button.png)](https://cloud.digitalocean.com/apps/new?repo=https://github.com/lissy93/dashy/tree/deploy_digital-ocean&refcode=3838338e7f79)
[DigitalOcean](https://www.digitalocean.com/) 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.
```text
https://cloud.digitalocean.com/apps/new?repo=https://github.com/lissy93/dashy/tree/deploy_digital-ocean
```
### Google Cloud Platform
[![Run on Google Cloud](https://i.ibb.co/LkvHttd/deploy-google-cloud-button.png)](https://deploy.cloud.run/?git_repo=https://github.com/lissy93/dashy.git)
[Cloud Run](https://cloud.google.com/run/) is a service offered by [Google Cloud](https://cloud.google.com/). 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](https://cloud.google.com/run/pricing) offering 180,000 vCPU-seconds, 360,000 GiB-seconds, and 2 million requests per month.
To deploy Dashy to GCP, use the following link
```text
https://deploy.cloud.run/?git_repo=https://github.com/lissy93/dashy.git
```
### Platform.sh
[![Deploy to Platform.sh](https://i.ibb.co/nPnJgJP/deploy-platform-sh-button.png)](https://console.platform.sh/projects/create-project/?template=https://github.com/lissy93/dashy&utm_campaign=deploy_on_platform?utm_medium=button&utm_source=affiliate_links&utm_content=https://github.com/lissy93/dashy)
[Platform.sh](https://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
```text
https://console.platform.sh/projects/create-project/?template=https://github.com/lissy93/dashy
```
### Render
[![Deploy to Render](https://i.ibb.co/QXNCbxT/deploy-render-button.png)](https://render.com/deploy?repo=https://github.com/lissy93/dashy/tree/deploy_render)
[Render](https://render.com) 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](https://render.com/docs)
To deploy Dashy to Render, use the following link
```text
https://render.com/deploy?repo=https://github.com/lissy93/dashy/tree/deploy_render
```
### Scalingo
[![Deploy on Scalingo](https://i.ibb.co/nj0KxyH/deploy-scalingo-button.png)](https://my.scalingo.com/deploy?source=https://github.com/lissy93/dashy#master)
[Scalingo](https://scalingo.com/) 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
```text
https://my.scalingo.com/deploy?source=https://github.com/lissy93/dashy#master
```
### Play-with-Docker
[![Try in PWD](https://i.ibb.co/SfbH7Zy/deploy-pwd-button.png)](https://labs.play-with-docker.com/?stack=https://raw.githubusercontent.com/Lissy93/dashy/master/docker-compose.yml)
[Play with Docker](https://labs.play-with-docker.com/) 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:
```text
https://labs.play-with-docker.com/?stack=https://raw.githubusercontent.com/Lissy93/dashy/master/docker-compose.yml
```
### Surge.sh
![Follow instructions below](https://i.ibb.co/XkcKzKz/deploy-surge-button.png)
[Surge.sh](http://surge.sh/) is quick and easy static web publishing platform for frontend-apps.
Surge supports [password-protected projects](https://surge.sh/help/adding-password-protection-to-a-project). You can also [add a custom domain](https://surge.sh/help/adding-a-custom-domain) and then [force HTTPS by default](https://surge.sh/help/using-https-by-default) and optionally [set a custom SSL certificate](https://surge.sh/help/securing-your-custom-domain-with-ssl)
To deploy Dashy to Surge.sh, first clone and cd into Dashy, install dependencies, and then use the following commands
```bash
yarn add -g surge
yarn build
surge ./dist
```
---
## Hosting with CDN
Once Dashy has been built, it is effectively 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 unavailable 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](/docs/deploymentdeploy-to-cloud-service) 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.
<p align="center"><img width="500" src="https://i.ibb.co/pjnmbw9/browser-compatibility.png" /></p>
# 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](/docs/quick-start), then you can spin up a new instance of Dashy by running:
```bash
docker run -p 8080:80 lissy93/dashy
```
See [Management Docs](/docs/management) 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](/docs/configuring).
## Deployment Methods
- [Deployment](#deployment)
- [Quick Start](#quick-start)
- [Deployment Methods](#deployment-methods)
- [Deploy with Docker](#deploy-with-docker)
- [Using Docker Compose](#using-docker-compose)
- [Kubernetes](#kubernetes)
- [Unraid](#unraid)
- [Synology NAS](#synology-nas)
- [Build from Source](#build-from-source)
- [Deploy to cloud service](#deploy-to-cloud-service)
- [Netlify](#netlify)
- [Heroku](#heroku)
- [Vercel](#vercel)
- [DigitalOcean](#digitalocean)
- [Google Cloud Platform](#google-cloud-platform)
- [Platform.sh](#platformsh)
- [Render](#render)
- [Railway](#railway)
- [Scalingo](#scalingo)
- [Play-with-Docker](#play-with-docker)
- [Surge.sh](#surgesh)
- [Easypanel](#easypanel)
- [Hosting with CDN](#hosting-with-cdn)
- [Requirements](#requirements)
- [System Requirements](#system-requirements)
- [Docker](#docker)
- [Bare Metal](#bare-metal)
- [CDN / Cloud Deploy](#cdn--cloud-deploy)
- [Browser Support](#browser-support)
---
## Deploy with Docker
**Container Info**: [
![Docker Supported Architecture](https://img.shields.io/badge/Architectures-amd64%20|%20arm32v7%20|%20arm64v8-6ba6e5)
![Docker Base Image](https://img.shields.io/badge/Base_Image-Alpine_3.14-6ba6e5)
![Docker Hosted on](https://img.shields.io/badge/Hosted_on-DockerHub-6ba6e5)
](https://hub.docker.com/r/lissy93/dashy)<br />
**Status**: [
![Docker Build Status](https://img.shields.io/docker/cloud/build/lissy93/dashy?label=Docker%20Build)
![Docker Pulls](https://img.shields.io/docker/pulls/lissy93/dashy?color=ecb2f7)
![Docker Stars](https://img.shields.io/docker/stars/lissy93/dashy?color=f7f754&label=Docker%20Stars)
![Docker Image Size](https://img.shields.io/docker/image-size/lissy93/dashy/latest?color=1eea76)
![Docker Cloud Build](https://img.shields.io/docker/cloud/automated/lissy93/dashy?color=f4a966&label=Docker%20Build)
](https://hub.docker.com/r/lissy93/dashy)
Dashy has a built container image hosted on [Docker Hub](https://hub.docker.com/r/lissy93/dashy). You will need [Docker](https://docs.docker.com/get-docker/) installed on your system.
```bash
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](https://hub.docker.com/r/lissy93/dashy/tags)
For all available options, and to learn more, see the [Docker Run Docs](https://docs.docker.com/engine/reference/commandline/run/)
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`](https://github.com/Lissy93/dashy/blob/master/docker-compose.yml) for Dashy. Run it as is, or uncomment the additional options you need.
```yaml
---
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](https://github.com/Lissy93/dashy/tree/master/docker), then under `services.dashy` first set `context: .`, then specify the the path to the dockerfile, e.g. `dockerfile: ./docker/Dockerfile-arm32v7`
---
## Kubernetes
@vyrtualsynthese has written a Helm Chart for deploying with Kubernetes, available [here](https://github.com/vyrtualsynthese/selfhosted-helmcharts/tree/main/charts/dashy)
---
## Unraid
// TODO
---
## Synology NAS
Installing dashy is really simply and fast:
1. Install Docker via Synology ```Package Center```.
2. Go to ```File Station``` and open the ```docker``` folder. Inside the docker folder, create one new folder and name it ```dashy```.
> Note: Be careful to enter only lowercase, not uppercase letters.
3. Go to Control Panel / Task Scheduler / Create / Scheduled Task / User-defined script.
4. Once you click on ```User-defined``` script a new window will open.
5. Follow the instructions below:
6. General: In the Task field type in Install dashy. Uncheck "Enabled" option. Select root User.
7. Schedule: Select Run on the following date then select "Do not repeat".
8. Task Settings: Check "Send run details by email", add your email then copy paste the code below in the Run command area. After that click OK.
```bash
docker run -d \
-p 4000:80 \
-v /volume1/docker/dashy/my-local-conf.yml:/app/public/conf.yml \
--name dashy \
--restart=always \
lissy93/dashy:latest
```
dashy should be up within 1-2min after you've started the install task procedure
---
## 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](https://git-scm.com/downloads) and the latest or LTS version of [Node.js](https://nodejs.org/) installed, and optionally [yarn](https://yarnpkg.com/)
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`](https://github.com/Lissy93/dashy/tree/deploy_cloudflare), [`deploy_digital-ocean`](https://github.com/Lissy93/dashy/tree/deploy_digital-ocean), [`deploy_platform-sh`](https://github.com/Lissy93/dashy/tree/deploy_platform-sh) and [`deploy_render`](https://github.com/Lissy93/dashy/tree/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 available. 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](https://i.ibb.co/GtKMysT/deploy-netlify-button.png)](https://app.netlify.com/start/deploy?repository=https://github.com/lissy93/dashy)
[Netlify](https://www.netlify.com/) 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
```text
https://app.netlify.com/start/deploy?repository=https://github.com/lissy93/dashy
```
### Heroku
[![Deploy to Heroku](https://i.ibb.co/GdMFzBP/deploy-heroku-button.png)](https://heroku.com/deploy?template=https://github.com/Lissy93/dashy)
[Heroku](https://www.heroku.com/) 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 costs a minimum of $5 for 1,000 dyno hours per month (there are around 720 hours in a month), 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
```text
https://heroku.com/deploy?template=https://github.com/Lissy93/dashy
```
### Vercel
[![Deploy with Vercel](https://i.ibb.co/mJF3R7m/deploy-vercel-button.png)](https://vercel.com/new/project?template=https://github.com/lissy93/dashy)
[Vercel](https://vercel.com/) is a performance-focused platform for hosting static frontend apps. It comes bundled with some useful tools for monitoring and analyzing 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
```text
https://vercel.com/new/project?template=https://github.com/lissy93/dashy
```
### DigitalOcean
[![Deploy to DO](https://i.ibb.co/PFt0PkB/deploy-digital-ocean-button.png)](https://cloud.digitalocean.com/apps/new?repo=https://github.com/lissy93/dashy/tree/deploy_digital-ocean&refcode=3838338e7f79)
[DigitalOcean](https://www.digitalocean.com/) 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.
```text
https://cloud.digitalocean.com/apps/new?repo=https://github.com/lissy93/dashy/tree/deploy_digital-ocean
```
### Google Cloud Platform
[![Run on Google Cloud](https://i.ibb.co/LkvHttd/deploy-google-cloud-button.png)](https://deploy.cloud.run/?git_repo=https://github.com/lissy93/dashy.git)
[Cloud Run](https://cloud.google.com/run/) is a service offered by [Google Cloud](https://cloud.google.com/). 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](https://cloud.google.com/run/pricing) offering 180,000 vCPU-seconds, 360,000 GiB-seconds, and 2 million requests per month.
To deploy Dashy to GCP, use the following link
```text
https://deploy.cloud.run/?git_repo=https://github.com/lissy93/dashy.git
```
### Platform.sh
[![Deploy to Platform.sh](https://i.ibb.co/nPnJgJP/deploy-platform-sh-button.png)](https://console.platform.sh/projects/create-project/?template=https://github.com/lissy93/dashy&utm_campaign=deploy_on_platform?utm_medium=button&utm_source=affiliate_links&utm_content=https://github.com/lissy93/dashy)
[Platform.sh](https://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
```text
https://console.platform.sh/projects/create-project/?template=https://github.com/lissy93/dashy
```
### Render
[![Deploy to Render](https://i.ibb.co/QXNCbxT/deploy-render-button.png)](https://render.com/deploy?repo=https://github.com/lissy93/dashy/tree/deploy_render)
[Render](https://render.com) 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](https://render.com/docs)
To deploy Dashy to Render, use the following link
```text
https://render.com/deploy?repo=https://github.com/lissy93/dashy/tree/deploy_render
```
### Railway
[![Deploy on Railway](https://railway.app/button.svg)](https://railway.app/template/MtdjAQ?referralCode=app)
[Railway](https://railway.app/) is a Platform as a Service (PaaS) that offers a complete platform for building and delivering programs to the backend of the cloud. You bring your code and Railway does the rest. Railway offers an extremely good developer experience and makes it effortless to deploy apps. Railway offers a free Trial Plan, and paid plans start at $5/month. Railway has 4 server locations: US-west, US-east, EU-west and ASIA-South-East.
```text
https://railway.app/template/MtdjAQ
```
### Scalingo
[![Deploy on Scalingo](https://i.ibb.co/nj0KxyH/deploy-scalingo-button.png)](https://my.scalingo.com/deploy?source=https://github.com/lissy93/dashy#master)
[Scalingo](https://scalingo.com/) 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
```text
https://my.scalingo.com/deploy?source=https://github.com/lissy93/dashy#master
```
### Play-with-Docker
[![Try in PWD](https://i.ibb.co/SfbH7Zy/deploy-pwd-button.png)](https://labs.play-with-docker.com/?stack=https://raw.githubusercontent.com/Lissy93/dashy/master/docker-compose.yml)
[Play with Docker](https://labs.play-with-docker.com/) 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:
```text
https://labs.play-with-docker.com/?stack=https://raw.githubusercontent.com/Lissy93/dashy/master/docker-compose.yml
```
### Surge.sh
![Follow instructions below](https://i.ibb.co/XkcKzKz/deploy-surge-button.png)
[Surge.sh](http://surge.sh/) is quick and easy static web publishing platform for frontend-apps.
Surge supports [password-protected projects](https://surge.sh/help/adding-password-protection-to-a-project). You can also [add a custom domain](https://surge.sh/help/adding-a-custom-domain) and then [force HTTPS by default](https://surge.sh/help/using-https-by-default) and optionally [set a custom SSL certificate](https://surge.sh/help/securing-your-custom-domain-with-ssl)
To deploy Dashy to Surge.sh, first clone and cd into Dashy, install dependencies, and then use the following commands
```bash
yarn add -g surge
yarn build
surge ./dist
```
### Easypanel
[![Deploy to Easypanel](https://i.ibb.co/ZNPwQX3/deploy-easypanel-button.png)](https://easypanel.io/docs/templates/dashy)
[Easypanel](https://easypanel.io) it's a modern server control panel. You can use it to deploy Dashy on your own server.
To deploy Dashy to Easypanel, use the following link
```text
https://easypanel.io/docs/templates/dashy
```
---
## Hosting with CDN
Once Dashy has been built, it is effectively 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 unavailable 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](/docs/deployment#deploy-to-cloud-service) 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.
<p align="center"><img width="500" src="https://i.ibb.co/pjnmbw9/browser-compatibility.png" /></p>

759
docs/developing.md
View File

@ -1,379 +1,380 @@
# Developing
This article outlines how to get Dashy running in a development environment, and outlines the basics of the architecture.
If you're adding new features, you may want to check out the [Development Guides](/docs/development-guides) docs, for tutorials covering basic tasks.
- [Setting up the Development Environment](#setting-up-the-dev-environment)
- [Prerequisites](#prerequisites)
- [Running the App](#running-the-project)
- [Project Commands](#project-commands)
- [Environmental Variables](#environmental-variables)
- [Git Strategy](#git-strategy)
- [Flow](#git-flow)
- [Branches](#git-branch-naming)
- [Commit emojis](#commit-emojis)
- [PR Guidelines](#pr-guidelines)
- [Resources for Beginners](#resources-for-beginners)
- [App Info](#app-info)
- [Code Style Guide](#style-guide)
- [Application Structure](#application-structure)
- [Development Tools](#development-tools)
- [Misc / Notes](#notes)
## Setting up the Dev Environment
### Prerequisites
You will need either the latest or LTS version of **[Node.js](https://nodejs.org/)** to build and serve the application and **[Git](https://git-scm.com/downloads)** to easily fetch the code, and push any changes. If you plan on running or deploying the container, you'll also need **[Docker](https://docs.docker.com/get-docker/)**. To avoid any unexpected issues, ensure you've got at least **[NPM](https://www.npmjs.com/get-npm)** V 7.5 or **[Yarn](https://classic.yarnpkg.com/en/docs/install/#windows-stable)** 1.22 (you may find [NVM](https://github.com/nvm-sh/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](https://github.com/Lissy93/dashy/blob/master/src/utils/ConfigSchema.js).
- **`yarn health-check`** - Checks that the application is up and running on it's specified port, and outputs current status and response times. Useful for integrating into your monitoring service, if you need to maintain high system availability
#### Alternate Start Commands
- **`yarn build-and-start`** - Builds the app, runs checks and starts the production server. Commands are run in parallel, and so is faster than running them in independently. Uses the `yarn build` and `yarn start` commands
- **`yarn build-watch`** - If you find yourself making frequent changes to your configuration, and do not want to have to keep manually rebuilding, then this option is for you. It will watch for changes to any files within the projects root, and then trigger a rebuild. Note that if you are developing new features, then `yarn dev` would be more appropriate, as it's significantly faster at recompiling (under 1 second), and has hot reloading, linting and testing integrated
- **`yarn pm2-start`** - Starts the Node server using [PM2](https://pm2.keymetrics.io/), a process manager for Node.js applications, that helps them stay alive. PM2 has some built-in basic monitoring features, and an optional [management solution](https://pm2.io/). If you are running the app on bare metal, it is recommended to use this start command
#### Notes
- If you are using NPM, replace `yarn` with `npm run`
- If you are using Docker, precede each command with `docker exec -it [container-id]`. Container ID can be found by running `docker ps`
- You can manage the app using the [Vue-CLI Service](https://cli.vuejs.org/guide/cli-service.html), with `npx vue-cli-service [command]`. Or to start the Vue Management UI, run `npx vue ui`, and open `http://localhost:8000`
### Environmental Variables
All environmental variables are optional. Currently there are not many environmental variables used, as most of the user preferences are stored under `appConfig` in the `conf.yml` file.
You can set variables either in your environment, or using the [`.env`](https://github.com/Lissy93/dashy/blob/master/.env) file.
- `NODE_ENV` - Current environment, can be either development, production or test
- `PORT` - The port to expose the running application on
- `HOST` - The host that Dashy is running on, domain or IP
- `BASE_URL` - The default base path for serving up static assets
- `VUE_APP_DOMAIN` - Usually the same as BASE_URL, but accessible in frontend
- `INTEGRITY` - Should enable SRI for build script and link resources
- `IS_DOCKER` - Computed automatically on build. Indicates if running in container
- `VUE_APP_VERSION` - Again, set automatically using package.json during build time
### Environment Modes
You can set the environment using the `NODE_ENV` variable. By default, the correct environment should be selected based on the script you run to start the app. The following environments are supported: `production`, `development` and `test`. For more info, see [Vue CLI Environment Modes](https://cli.vuejs.org/guide/mode-and-env.html#modes).
---
## Git Strategy
### Git Flow
Like most Git repos, we are following the [Github Flow](https://guides.github.com/introduction/flow) standard.
1. Create a branch (or fork if you don'd have write 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](https://gitmoji.dev/)
### PR Guidelines
Once you've made your changes, and pushed them to your fork or branch, you're ready to open a pull request!
For a pull request to be merged, it must:
- Must be backwards compatible
- The build, lint and tests (run by GH actions) must pass
- There must not be any merge conflicts
When you submit your PR, include the required info, by filling out the PR template. Including:
- A brief description of your changes
- The issue, ticket or discussion number (if applicable)
- For UI relate updates include a screenshot
- If any dependencies were added, explain why it was needed, state the cost associated, and confirm it does not introduce any security issues
- Finally, check the checkboxes, to confirm that the standards are met, and hit submit!
---
## 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:
- [Open Source for Beginners](https://opensource.guide/how-to-contribute/)
- [Introduction to Vue.js](https://v3.vuejs.org/guide/introduction.html)
- [Vue.js Walkthrough](https://www.taniarascia.com/getting-started-with-vue/)
- [ES6 Features](https://github.com/lukehoban/es6features)
- [Definitive guide to SCSS](https://blog.logrocket.com/the-definitive-guide-to-scss/)
- [Complete beginners guide to Docker](https://docker-curriculum.com/)
- [Docker Classroom - Interactive Tutorials](https://training.play-with-docker.com/)
- [Quick start TypeScript guide](https://www.freecodecamp.org/news/learn-typescript-in-5-minutes-13eda868daeb/)
- [Complete TypeScript tutorial series](https://www.typescripttutorial.net/)
- [Using TypeScript with Vue.js](https://blog.logrocket.com/vue-typescript-tutorial-examples/)
- [Git cheat sheet](http://git-cheatsheet.com/)
- [Basics of using NPM](https://www.freecodecamp.org/news/what-is-npm-a-node-package-manager-tutorial-for-beginners/)
As well as Node, Git and Docker- you'll also need an IDE (e.g. [VS Code](https://code.visualstudio.com/) or [Vim](https://www.vim.org/)) and a terminal (Windows users may find [WSL](https://docs.microsoft.com/en-us/windows/wsl/) more convenient).
---
## App Info
### Style Guide
Linting is done using [ESLint](https://eslint.org/), and using the [Vue.js Styleguide](https://github.com/vuejs/eslint-config-standard), which is very similar to the [AirBnB Styleguide](https://github.com/airbnb/javascript). You can run `yarn lint` to report and fix issues. While the dev server is running, issues will be reported to the console automatically, and any lint errors will trigger the build to fail. Note that all lint checks must pass before any PR can be merged. Linting is also run as a git pre-commit hook
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:
- Vue: [Vue styleguide](https://vuejs.org/v2/style-guide/)
- JavaScript: [github.com/airbnb/javascript](https://github.com/airbnb/javascript)
---
### Application Structure
#### Files in the Root: `./`
```text
╮
├── 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/`
```text
./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](https://raw.githubusercontent.com/Lissy93/dashy/master/docs/assets/repo-visualization.svg)
---
## 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](https://bundlephobia.com/) is a really useful app that lets you analyze the cost of adding any particular dependency to an application
---
## Notes
### Known Warnings
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.
# Developing
This article outlines how to get Dashy running in a development environment, and outlines the basics of the architecture.
If you're adding new features, you may want to check out the [Development Guides](/docs/development-guides) docs, for tutorials covering basic tasks.
- [Setting up the Development Environment](#setting-up-the-dev-environment)
- [Prerequisites](#prerequisites)
- [Running the App](#running-the-project)
- [Project Commands](#project-commands)
- [Environmental Variables](#environmental-variables)
- [Git Strategy](#git-strategy)
- [Flow](#git-flow)
- [Branches](#git-branch-naming)
- [Commit emojis](#commit-emojis)
- [PR Guidelines](#pr-guidelines)
- [Resources for Beginners](#resources-for-beginners)
- [App Info](#app-info)
- [Code Style Guide](#style-guide)
- [Application Structure](#application-structure)
- [Development Tools](#development-tools)
- [Misc / Notes](#notes)
## Setting up the Dev Environment
### Prerequisites
You will need either the latest or LTS version of **[Node.js](https://nodejs.org/)** to build and serve the application and **[Git](https://git-scm.com/downloads)** to easily fetch the code, and push any changes. If you plan on running or deploying the container, you'll also need **[Docker](https://docs.docker.com/get-docker/)**. To avoid any unexpected issues, ensure you've got at least **[NPM](https://www.npmjs.com/get-npm)** V 7.5 or **[Yarn](https://classic.yarnpkg.com/en/docs/install/#windows-stable)** 1.22 (you may find [NVM](https://github.com/nvm-sh/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](https://github.com/Lissy93/dashy/blob/master/src/utils/ConfigSchema.js).
- **`yarn health-check`** - Checks that the application is up and running on it's specified port, and outputs current status and response times. Useful for integrating into your monitoring service, if you need to maintain high system availability
#### Alternate Start Commands
- **`yarn build-and-start`** - Builds the app, runs checks and starts the production server. Commands are run in parallel, and so is faster than running them in independently. Uses the `yarn build` and `yarn start` commands
- **`yarn build-watch`** - If you find yourself making frequent changes to your configuration, and do not want to have to keep manually rebuilding, then this option is for you. It will watch for changes to any files within the projects root, and then trigger a rebuild. Note that if you are developing new features, then `yarn dev` would be more appropriate, as it's significantly faster at recompiling (under 1 second), and has hot reloading, linting and testing integrated
- **`yarn pm2-start`** - Starts the Node server using [PM2](https://pm2.keymetrics.io/), a process manager for Node.js applications, that helps them stay alive. PM2 has some built-in basic monitoring features, and an optional [management solution](https://pm2.io/). If you are running the app on bare metal, it is recommended to use this start command
#### Notes
- If you are using NPM, replace `yarn` with `npm run`
- If you are using Docker, precede each command with `docker exec -it [container-id]`. Container ID can be found by running `docker ps`
- You can manage the app using the [Vue-CLI Service](https://cli.vuejs.org/guide/cli-service.html), with `npx vue-cli-service [command]`. Or to start the Vue Management UI, run `npx vue ui`, and open `http://localhost:8000`
### Environmental Variables
All environmental variables are optional. Currently there are not many environmental variables used, as most of the user preferences are stored under `appConfig` in the `conf.yml` file.
You can set variables either in your environment, or using the [`.env`](https://github.com/Lissy93/dashy/blob/master/.env) file.
- `NODE_ENV` - Current environment, can be either development, production or test
- `PORT` - The port to expose the running application on
- `HOST` - The host that Dashy is running on, domain or IP
- `BASE_URL` - The default base path for serving up static assets
- `VUE_APP_DOMAIN` - Usually the same as BASE_URL, but accessible in frontend
- `INTEGRITY` - Should enable SRI for build script and link resources
- `IS_DOCKER` - Computed automatically on build. Indicates if running in container
- `VUE_APP_VERSION` - Again, set automatically using package.json during build time
- `BACKUP_DIR` - Directory for conf.yml backups
### 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](https://cli.vuejs.org/guide/mode-and-env.html#modes).
---
## Git Strategy
### Git Flow
Like most Git repos, we are following the [Github Flow](https://guides.github.com/introduction/flow) standard.
1. Create a branch (or fork if you don'd have write 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](https://gitmoji.dev/)
### PR Guidelines
Once you've made your changes, and pushed them to your fork or branch, you're ready to open a pull request!
For a pull request to be merged, it must:
- Must be backwards compatible
- The build, lint and tests (run by GH actions) must pass
- There must not be any merge conflicts
When you submit your PR, include the required info, by filling out the PR template. Including:
- A brief description of your changes
- The issue, ticket or discussion number (if applicable)
- For UI relate updates include a screenshot
- If any dependencies were added, explain why it was needed, state the cost associated, and confirm it does not introduce any security issues
- Finally, check the checkboxes, to confirm that the standards are met, and hit submit!
---
## 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:
- [Open Source for Beginners](https://opensource.guide/how-to-contribute/)
- [Introduction to Vue.js](https://v3.vuejs.org/guide/introduction.html)
- [Vue.js Walkthrough](https://www.taniarascia.com/getting-started-with-vue/)
- [ES6 Features](https://github.com/lukehoban/es6features)
- [Definitive guide to SCSS](https://blog.logrocket.com/the-definitive-guide-to-scss/)
- [Complete beginners guide to Docker](https://docker-curriculum.com/)
- [Docker Classroom - Interactive Tutorials](https://training.play-with-docker.com/)
- [Quick start TypeScript guide](https://www.freecodecamp.org/news/learn-typescript-in-5-minutes-13eda868daeb/)
- [Complete TypeScript tutorial series](https://www.typescripttutorial.net/)
- [Using TypeScript with Vue.js](https://blog.logrocket.com/vue-typescript-tutorial-examples/)
- [Git cheat sheet](http://git-cheatsheet.com/)
- [Basics of using NPM](https://www.freecodecamp.org/news/what-is-npm-a-node-package-manager-tutorial-for-beginners/)
As well as Node, Git and Docker- you'll also need an IDE (e.g. [VS Code](https://code.visualstudio.com/) or [Vim](https://www.vim.org/)) and a terminal (Windows users may find [WSL](https://docs.microsoft.com/en-us/windows/wsl/) more convenient).
---
## App Info
### Style Guide
Linting is done using [ESLint](https://eslint.org/), and using the [Vue.js Styleguide](https://github.com/vuejs/eslint-config-standard), which is very similar to the [AirBnB Styleguide](https://github.com/airbnb/javascript). You can run `yarn lint` to report and fix issues. While the dev server is running, issues will be reported to the console automatically, and any lint errors will trigger the build to fail. Note that all lint checks must pass before any PR can be merged. Linting is also run as a git pre-commit hook
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:
- Vue: [Vue styleguide](https://vuejs.org/v2/style-guide/)
- JavaScript: [github.com/airbnb/javascript](https://github.com/airbnb/javascript)
---
### Application Structure
#### Files in the Root: `./`
```text
╮
├── 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/`
```text
./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](https://raw.githubusercontent.com/Lissy93/dashy/master/docs/assets/repo-visualization.svg)
---
## 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](https://bundlephobia.com/) is a really useful app that lets you analyze the cost of adding any particular dependency to an application
---
## Notes
### Known Warnings
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.

28
docs/development-guides.md
View File

@ -16,15 +16,15 @@ Sections:
## Creating a new theme
Adding a new theme is really easy. There's two things you need to do: Pass the theme name to Dashy, so that it can be added to the theme selector dropdown menu, and then write some styles!
Adding a new theme is really easy. There're two things you need to do: Pass the theme name to Dashy, so that it can be added to the theme selector dropdown menu, and then write some styles!
### 1. Add Theme Name
Choose a snappy name for you're theme, and add it to the `builtInThemes` array inside [`defaults.js`](https://github.com/Lissy93/dashy/blob/master/src/utils/defaults.js#L27).
Choose a snappy name for your theme, and add it to the `builtInThemes` array inside [`defaults.js`](https://github.com/Lissy93/dashy/blob/master/src/utils/defaults.js#L27).
### 2. Write some Styles
Put your theme's styles inside [`color-themes.scss`](https://github.com/Lissy93/dashy/blob/master/src/styles/color-themes.scss).
Put your theme styles inside [`color-themes.scss`](https://github.com/Lissy93/dashy/blob/master/src/styles/color-themes.scss).
Create a new block, and make sure that `data-theme` matches the theme name you chose above. For example:
```css
@ -34,11 +34,11 @@ html[data-theme='tiger'] {
}
```
Then you can go ahead and write you're own custom CSS. Although all CSS is supported here, the best way to define you're theme is by setting the CSS variables. You can find a [list of all CSS variables, here](https://github.com/Lissy93/dashy/blob/master/docs/theming.md#css-variables).
Then you can go ahead and write your own custom CSS. Although all CSS is supported here, the best way to define your theme is by setting the CSS variables. You can find a [list of all CSS variables, here](https://github.com/Lissy93/dashy/blob/master/docs/theming.md#css-variables).
For a full guide on styling, see [Theming Docs](./theming).
Note that if you're theme is just for yourself, and you're not submitting a PR, then you can instead just pass it under `appConfig.cssThemes` inside your config file. And then put your theme in your own stylesheet, and pass it into the Docker container - [see how](https://github.com/Lissy93/dashy/blob/master/docs/theming.md#adding-your-own-theme).
Note that if your theme is just for yourself, and you're not submitting a PR, then you can instead just pass it under `appConfig.cssThemes` inside your config file. And then put your theme in your own stylesheet, and pass it into the Docker container - [see how](https://github.com/Lissy93/dashy/blob/master/docs/theming.md#adding-your-own-theme).
## Writing Translations
@ -96,7 +96,7 @@ export const languages = [
];
```
You can also add your new language to the readme, under the [Language Switching](https://github.com/Lissy93/dashy#language-switching-) section, and optionally include your name/ username if you'd like to be credited for your work. Done!
You can also add your new language to the readme file, under the [Language Switching](https://github.com/Lissy93/dashy#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.
@ -125,7 +125,7 @@ computed: {
},
```
Then, where you want get the users value within your component, use something like: `this.appConfig.myProperty`. Don't forget to have a fallback or default for then the user hasn't specified it.
Then, where you want to get the users value within your component, use something like: `this.appConfig.myProperty`. If the user hasn't specified the value, Don't forget to have a fallback or default for it.
If you have a default fallback value, then this would typically be specified in the [`defaults.js`](https://github.com/Lissy93/dashy/blob/master/src/utils/defaults.js) file.
@ -151,7 +151,7 @@ or
}
```
Finally, add your new property to the [`configuring.md`](./configuring) API docs. Put it under the relevant section, and be sure to include field name, data type, a description and mention that it is optional. If your new feature needs more explaining, then you can also document it under the relevant section elsewhere in the documentation.
Finally, add your new property to the [`configuring.md`](./configuring) API docs. Put it under the relevant section, and be sure to include field name, data type, a description and mention that it is optional. If your new feature needs more explanation, then you can also document it under the relevant section elsewhere in the documentation.
Checklist:
@ -176,12 +176,12 @@ When Dashy is deployed to Netlify, it is effectively running as a static app, an
### 1. Run Netlify Dev Server
First off, install the Netlify CLI: `npm install netlify-cli -g`
First off all, install the Netlify CLI: `npm install netlify-cli -g`
Then, from within the root of Dashy's directory, start the server, by running: `netlify dev`
### 2. Create a lambda function
This should be saved it in the [`./services/serverless-functions`](https://github.com/Lissy93/dashy/tree/master/services/serverless-functions) directory
This should be saved in the [`./services/serverless-functions`](https://github.com/Lissy93/dashy/tree/master/services/serverless-functions) directory
```javascript
exports.handler = async () => ({
@ -313,7 +313,7 @@ export default {
All widgets extend from the [Widget](https://github.com/Lissy93/dashy/blob/master/src/mixins/WidgetMixin.js) 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)
- Any user-specific config can be accessed with `this.options.something` (where something is the data key you're 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()`**
@ -341,7 +341,7 @@ computed: {
#### **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`](https://github.com/Lissy93/dashy/blob/master/src/utils/defaults.js#L207)
If your widget makes a data request, then add the URL for the API endpoint to the `widgetApiEndpoints` array in [`defaults.js`](https://github.com/Lissy93/dashy/blob/master/src/utils/defaults.js#L207)
```javascript
widgetApiEndpoints: {
@ -410,7 +410,7 @@ Now that the results are in the correct format, and stored as data variables, we
#### **Styling**
Styles can be written your your widget within the `<style>` block.
Styles can be written for your widget within the `<style>` block.
There are several color variables used by widgets, which extend from the base palette. 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`
@ -439,7 +439,7 @@ Here, the `example-widget` property name will be used to identify the widget whe
### Step 4 - Docs
Finally, add some documentation for your widget in the [Widget Docs](https://github.com/Lissy93/dashy/blob/master/docs/widgets.md), so that others know hoe to use it. Include the following information: Title, short description, screenshot, config options and some example YAML.
Finally, add some documentation for your widget in the [Widget Docs](https://github.com/Lissy93/dashy/blob/master/docs/widgets.md), so that others know how 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`](https://github.com/Lissy93/dashy/commit/3da76ce2999f57f76a97454c0276301e39957b8e)

2
docs/icons.md
View File

@ -89,7 +89,7 @@ sections:
## 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](https://avatars.dicebear.com/) (or [Evatar](https://evatar.io/) for fallback), and use a hash of the services domain/ ip for entropy, so each domain will have a unique icon.
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](https://api.dicebear.com/) (or [Evatar](https://evatar.io/) for fallback), and use a hash of the services domain/ ip for entropy, so each domain will have a unique icon.
<p align="center">
<img width="500" src="https://i.ibb.co/b2pC2CL/generative-icons-2.png" />

42
docs/management.md
View File

@ -39,7 +39,7 @@ In Dashy, commonly configured resources include:
- Also within `./public` you'll find standard website assets, including `favicon.ico`, `manifest.json`, `robots.txt`, etc. There's no need to pass these in, but you can do so if you wish
- `/src/styles/user-defined-themes.scss` - A stylesheet for applying custom CSS to your app. You can also write your own themes here.
**[⬆️ Back to Top](#)**
**[⬆️ Back to Top](#management)**
---
@ -47,9 +47,9 @@ In Dashy, commonly configured resources include:
If you're running an app in Docker, then commands will need to be passed to the container to be executed. This can be done by preceding each command with `docker exec -it [container-id]`, where container ID can be found by running `docker ps`. For example `docker exec -it 26c156c467b4 yarn build`. You can also enter the container, with `docker exec -it [container-id] /bin/ash`, and navigate around it with normal Linux commands.
Dashy has several commands that can be used for various tasks, you can find a list of these either in the [Developing Docs](/docs/developingproject-commands), or by looking at the [`package.json`](https://github.com/Lissy93/dashy/blob/master/package.json#L5). These can be used by running `yarn [command-name]`.
Dashy has several commands that can be used for various tasks, you can find a list of these either in the [Developing Docs](/docs/developing#project-commands), or by looking at the [`package.json`](https://github.com/Lissy93/dashy/blob/master/package.json#L5). These can be used by running `yarn [command-name]`.
**[⬆️ Back to Top](#)**
**[⬆️ Back to Top](#management)**
---
@ -68,7 +68,7 @@ docker run -d \
willfarrell/autoheal
```
**[⬆️ Back to Top](#)**
**[⬆️ Back to Top](#management)**
---
@ -90,7 +90,7 @@ You can also view logs, resource usage and other info as well as manage your ent
Docker supports using [Prometheus](https://prometheus.io/) to collect logs, which can then be visualized using a platform like [Grafana](https://grafana.com/). For more info, see [this guide](https://docs.docker.com/config/daemon/prometheus/). If you need to route your logs to a remote syslog, then consider using [logspout](https://github.com/gliderlabs/logspout). For enterprise-grade instances, there are managed services, that make monitoring container logs and metrics very easy, such as [Sematext](https://sematext.com/blog/docker-container-monitoring-with-sematext/) with [Logagent](https://github.com/sematext/logagent-js).
**[⬆️ Back to Top](#)**
**[⬆️ Back to Top](#management)**
---
@ -102,7 +102,7 @@ For Podman, you can use `systemd` to create a service that launches your contain
To restart the container after something within it has crashed, consider using [`docker-autoheal`](https://github.com/willfarrell/docker-autoheal) by @willfarrell, a service that monitors and restarts unhealthy containers. For more info, see the [Healthchecks](#healthchecks) section above.
**[⬆️ Back to Top](#)**
**[⬆️ Back to Top](#management)**
---
@ -139,7 +139,7 @@ For more information, see the [Watchtower Docs](https://containrrr.dev/watchtowe
Stop your current instance of Dashy, then navigate into the source directory. Pull down the latest code, with `git pull origin master`, then update dependencies with `yarn`, rebuild with `yarn build`, and start the server again with `yarn start`.
**[⬆️ Back to Top](#)**
**[⬆️ Back to Top](#management)**
---
@ -201,7 +201,7 @@ Since Dashy is open source, and freely available, providing you're configuration
Dashy also has a built-in cloud backup feature, which is free for personal users, and will let you make and restore fully encrypted backups of your config directly through the UI. To learn more, see the [Cloud Backup Docs](/docs/backup-restore)
**[⬆️ Back to Top](#)**
**[⬆️ Back to Top](#management)**
---
@ -210,7 +210,7 @@ Dashy also has a built-in cloud backup feature, which is free for personal users
If you need to periodically schedule the running of a given command on Dashy (or any other container), then a useful tool for doing so it [ofelia](https://github.com/mcuadros/ofelia). This runs as a Docker container and is really useful for things like backups, logging, updating, notifications, etc. Crons are specified using Go's crontab format, and a useful tool for visualizing this is [crontab.guru](https://crontab.guru/). This can also be done natively with Alpine: `docker run -it alpine ls /etc/periodic`.
I recommend combining this with [healthchecks](https://github.com/healthchecks/healthchecks) for easy monitoring of jobs, and failure notifications.
**[⬆️ Back to Top](#)**
**[⬆️ Back to Top](#management)**
---
@ -248,7 +248,7 @@ By default the SSL port is `443` within a Docker container, or `4001` if running
Once everything is setup, you can verify your site is secured using a tool like [SSL Checker](https://www.sslchecker.com/sslchecker).
**[⬆️ Back to Top](#)**
**[⬆️ Back to Top](#management)**
---
@ -256,7 +256,7 @@ Once everything is setup, you can verify your site is secured using a tool like
Dashy natively supports secure authentication using KeyCloak. There is also a Simple Auth feature that doesn't require any additional setup. Usage instructions for both, as well as alternative auth methods, has now moved to the **[Authentication Docs](/docs/authentication)** page.
**[⬆️ Back to Top](#)**
**[⬆️ Back to Top](#management)**
---
@ -290,13 +290,13 @@ services:
start_period: 40s
```
**[⬆️ Back to Top](#)**
**[⬆️ Back to Top](#management)**
---
## Passing in Environmental Variables
With Docker, you can define environmental variables under the `environment` section of your Docker compose file. Environmental variables are used to configure high-level settings, usually before the config file has been read. For a list of all supported env vars in Dashy, see [the developing docs](/docs/developingenvironmental-variables), or the default [`.env`](https://github.com/Lissy93/dashy/blob/master/.env) file.
With Docker, you can define environmental variables under the `environment` section of your Docker compose file. Environmental variables are used to configure high-level settings, usually before the config file has been read. For a list of all supported env vars in Dashy, see [the developing docs](/docs/developing#environmental-variables), or the default [`.env`](https://github.com/Lissy93/dashy/blob/master/.env) file.
A common use case, is to run Dashy under a sub-page, instead of at the root of a URL (e.g. `https://my-homelab.local/dashy` instead of `https://dashy.my-homelab.local`). In this use-case, you'd specify the `BASE_URL` variable in your compose file.
@ -308,7 +308,7 @@ environment:
You can also do the same thing with the docker run command, using the [`--env`](https://docs.docker.com/engine/reference/commandline/run/#set-environment-variables--e---env---env-file) flag.
If you've got many environmental variables, you might find it useful to put them in a [`.env` file](https://docs.docker.com/compose/env-file/). Similarly, for Docker run you can use [`--env-file`](https://docs.docker.com/engine/reference/commandline/run/#set-environment-variables--e---env---env-file) if you'd like to pass in a file containing all your environmental variables.
**[⬆️ Back to Top](#)**
**[⬆️ Back to Top](#management)**
---
@ -393,7 +393,7 @@ Header always set Access-Control-Allow-Origin "*"
request_header_access Authorization allow all
```
**[⬆️ Back to Top](#)**
**[⬆️ Back to Top](#management)**
---
@ -523,7 +523,7 @@ There's so much more you can do with Ngrok, such as exposing a directory as a fi
It's worth noting that Ngrok isn't the only option here, other options include: [FRP](https://github.com/fatedier/frp), [Inlets](https://inlets.dev), [Local Tunnel](https://localtunnel.me/), [TailScale](https://tailscale.com/), etc. Check out [Awesome Tunneling](https://github.com/anderspitman/awesome-tunneling) for a list of alternatives.
**[⬆️ Back to Top](#)**
**[⬆️ Back to Top](#management)**
---
@ -583,7 +583,7 @@ dashy.example.com {
For more info, [this guide](https://thehomelab.wiki/books/dns-reverse-proxy/page/create-domain-records-to-point-to-your-home-server-on-cloudflare-using-nginx-progy-manager) on Setting up Domains with NGINX Proxy Manager and CloudFlare may be useful.
**[⬆️ Back to Top](#)**
**[⬆️ Back to Top](#management)**
---
@ -744,7 +744,7 @@ Docker supports several modules that let you write your own security profiles.
[Seccomp](https://en.wikipedia.org/wiki/Seccomp) (Secure Computing Mode) is a sandboxing facility in the Linux kernel that acts like a firewall for system calls (syscalls). It uses Berkeley Packet Filter (BPF) rules to filter syscalls and control how they are handled. These filters can significantly limit a containers access to the Docker Host's Linux kernel - especially for simple containers/applications. It requires a Linux-based Docker host, with secomp enabled, and you can check for this by running `docker info | grep seccomp`. A great resource for learning more about this is [DockerLabs](https://training.play-with-docker.com/security-seccomp/).
**[⬆️ Back to Top](#)**
**[⬆️ Back to Top](#management)**
---
@ -878,7 +878,7 @@ Create a file names `firebase.json`, and populate it with something similar to:
8. If you need to change the port, click 'Add environmental variable', give it the name 'PORT', choose a port number and press 'Save'.
9. Dashy should now be running at your selected path an on a given port
**[⬆️ Back to Top](#)**
**[⬆️ Back to Top](#management)**
---
@ -888,7 +888,7 @@ If you'd like to make any code changes to the app, and deploy your modified vers
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](/docs/developing). To build your own Docker container from the modified app, see [Building your Own Container](#building-your-own-container)
**[⬆️ Back to Top](#)**
**[⬆️ Back to Top](#management)**
---
@ -905,6 +905,6 @@ Your container should now be running, and will appear in the list when you run `
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](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-container-registry).
**[⬆️ Back to Top](#)**
**[⬆️ Back to Top](#management)**
---

2
docs/multi-language-support.md
View File

@ -22,7 +22,7 @@ You can also set your language in the config file. Specify the ISO code of one o
```yaml
appConfig:
lang: de
language: de
```
### Available Languages

194
docs/pages-and-sections.md
View File

@ -1,97 +1,97 @@
# Pages and Sections
## Multi-Page Support
You can have additional pages within your dashboard, with each having it's own config file. The config files for sub-pages can either be stored locally, or hosted separately. A link to each additional page will be displayed in the navigation bar.
You can edit additional pages using the interactive editor, exactly the same was as your primary page (so long as it's local). But please save changes to one page, before you start editing the next.
### Using Local Sub-Pages
To get started, create a new `.yml` config file for your sub-page, placing it within `/app/public`. Then within your primary `conf.yml`, choose a name, and specify the path to the new file.
For example:
```yaml
pages:
- name: Networking Services
path: 'networking.yml'
- name: Work Stuff
path: 'work.yml'
```
If you're sub-page is located within `/app/public`, then you only need to specify the filename, but if it's anywhere else, then the full path is required.
### Using Remote Sub-Pages
Config files don't need to be local, you can store them anywhere, and data will be imported as sub-pages on page load.
For example:
```yaml
pages:
- name: Getting Started
path: 'https://snippet.host/tvcw/raw'
- name: Homelab
path: 'https://snippet.host/tetp/raw'
- name: Browser Startpage
path: 'https://snippet.host/zcom/raw'
```
There are many options of how this can be used. You could store your config within a Git repository, in order to easily track and rollback changes. Or host your config on your NAS, to have it backed up with the rest of your files. Or use a hosted paste service, for example [snippet.host](https://snippet.host/), which supports never-expiring CORS-enabled pastes, which can also be edited later.
You will obviously not be able to write updates to remote configs directly through the UI editor, but you can still make and preview changes, then use the export menu to get a copy of the new config, which can then be pasted to the remote source manually.
The config file must, of course be accessible from within Dashy. If your config contains sensitive info (like API keys, credentials, secret URLs, etc), take care not to expose it to the internet.
The following example shows creating a config, publishing it as a [Gist](https://gist.github.com/), copying the URL to the raw file, and using it within your dashboard.
<p align="center">
<img width="700" alt="Public config in a gist demo"
src="https://i.ibb.co/55jm3LG/how-to-use-remote-config-sub-page.gif"
/>
</p>
### Restrictions
Only top-level fields supported by sub-pages are `pageInfo` and `sections`. The `appConfig` and `pages` will always be inherited from your main `conf.yml` file. Other than that, sub-pages behave exactly the same as your default view, and can contain sections, items, widgets and page info like nav links, title and logo.
Note that since page paths are required by the router, they are set at build-time, not run-time, and so a rebuild (happens automatically) is required for changes to page paths to take effect (this only applies to changes to the `pages` array, rebuild isn't required for editing page content).
## Sub-Items
A normal section will contain zero or more items, for example:
```yaml
- name: Coding
icon: far fa-code
items:
- title: GitHub
url: https://github.com/
- title: StackOverflow
url: http://stackoverflow.com/
```
But items can also be grouped together, referred to as sub-items. This is useful for a group of less frequently used items, which you don't want to take up too much space, or for action buttons (_coming soon_).
Item groups may also have an optional title.
```yaml
- name: Coding
icon: far fa-code
items:
- title: Normal Item 1
- title: Normal Item 2
- subItems:
- title: JavaScript
url: https://developer.mozilla.org
icon: si-javascript
- title: TypeScript
url: https://www.typescriptlang.org/docs
icon: si-typescript
- title: Svelt
url: https://svelte.dev/docs
icon: si-svelte
- title: Go
url: https://go.dev/doc
icon: si-go
```
# Pages and Sections
## Multi-Page Support
You can have additional pages within your dashboard, with each having it's own config file. The config files for sub-pages can either be stored locally, or hosted separately. A link to each additional page will be displayed in the navigation bar.
You can edit additional pages using the interactive editor, exactly the same was as your primary page (so long as it's local). But please save changes to one page, before you start editing the next.
### Using Local Sub-Pages
To get started, create a new `.yml` config file for your sub-page, placing it within `/app/public`. Then within your primary `conf.yml`, choose a name, and specify the path to the new file.
For example:
```yaml
pages:
- name: Networking Services
path: 'networking.yml'
- name: Work Stuff
path: 'work.yml'
```
If you're sub-page is located within `/app/public`, then you only need to specify the filename, but if it's anywhere else, then the full path is required.
### Using Remote Sub-Pages
Config files don't need to be local, you can store them anywhere, and data will be imported as sub-pages on page load.
For example:
```yaml
pages:
- name: Getting Started
path: 'https://snippet.host/tvcw/raw'
- name: Homelab
path: 'https://snippet.host/tetp/raw'
- name: Browser Startpage
path: 'https://snippet.host/zcom/raw'
```
There are many options of how this can be used. You could store your config within a Git repository, in order to easily track and rollback changes. Or host your config on your NAS, to have it backed up with the rest of your files. Or use a hosted paste service, for example [snippet.host](https://snippet.host/), which supports never-expiring CORS-enabled pastes, which can also be edited later.
You will obviously not be able to write updates to remote configs directly through the UI editor, but you can still make and preview changes, then use the export menu to get a copy of the new config, which can then be pasted to the remote source manually.
The config file must, of course be accessible from within Dashy. If your config contains sensitive info (like API keys, credentials, secret URLs, etc), take care not to expose it to the internet.
The following example shows creating a config, publishing it as a [Gist](https://gist.github.com/), copying the URL to the raw file, and using it within your dashboard.
<p align="center">
<img width="700" alt="Public config in a gist demo"
src="https://i.ibb.co/55jm3LG/how-to-use-remote-config-sub-page.gif"
/>
</p>
### Restrictions
Only top-level fields supported by sub-pages are `pageInfo` and `sections`. The `appConfig` and `pages` will always be inherited from your main `conf.yml` file. Other than that, sub-pages behave exactly the same as your default view, and can contain sections, items, widgets and page info like nav links, title and logo.
Note that since page paths are required by the router, they are set at build-time, not run-time, and so a rebuild (happens automatically) is required for changes to page paths to take effect (this only applies to changes to the `pages` array, rebuild isn't required for editing page content).
## Sub-Items
A normal section will contain zero or more items, for example:
```yaml
- name: Coding
icon: far fa-code
items:
- title: GitHub
url: https://github.com/
- title: StackOverflow
url: http://stackoverflow.com/
```
But items can also be grouped together, referred to as sub-items. This is useful for a group of less frequently used items, which you don't want to take up too much space, or for action buttons (_coming soon_).
Item groups may also have an optional title.
```yaml
- name: Coding
icon: far fa-code
items:
- title: Normal Item 1
- title: Normal Item 2
- subItems:
- title: JavaScript
url: https://developer.mozilla.org
icon: si-javascript
- title: TypeScript
url: https://www.typescriptlang.org/docs
icon: si-typescript
- title: Svelt
url: https://svelte.dev/docs
icon: si-svelte
- title: Go
url: https://go.dev/doc
icon: si-go
```

54
docs/privacy.md
View File

@ -114,54 +114,54 @@ Certain themes may use external assets (such as fonts or images). Currently, thi
Dashy supports [Widgets](/docs/widgets) for displaying dynamic content. Below is a list of all widgets that make external data requests, along with the endpoint they call and a link to the Privacy Policy of that service.
- **[Weather](/docs/widgetsweather)** and **[Weather Forecast](/docs/widgetsweather-forecast)**: `https://api.openweathermap.org`
- **[Weather](/docs/widgets#weather)** and **[Weather Forecast](/docs/widgets#weather-forecast)**: `https://api.openweathermap.org`
- [OWM Privacy Policy](https://openweather.co.uk/privacy-policy)
- **[RSS Feed](/docs/widgetsrss-feed)**: `https://api.rss2json.com/v1/api.json`
- **[RSS Feed](/docs/widgets#rss-feed)**: `https://api.rss2json.com/v1/api.json`
- [Rss2Json Privacy Policy](https://rss2json.com/privacy-policy)
- **[IP Address](/docs/widgetspublic-ip)**: `https://ipapi.co/json` or `http://ip-api.com/json`
- **[IP Address](/docs/widgets#public-ip)**: `https://ipapi.co/json` or `http://ip-api.com/json`
- [IPGeoLocation Privacy Policy](https://ipgeolocation.io/privacy.html)
- [IP-API Privacy Policy](https://ip-api.com/docs/legal)
- **[IP Blacklist](/docs/widgetsip-blacklist)**: `https://api.blacklistchecker.com`
- **[IP Blacklist](/docs/widgets#ip-blacklist)**: `https://api.blacklistchecker.com`
- [Blacklist Checker Privacy Policy](https://blacklistchecker.com/privacy)
- **[Domain Monitor](/docs/widgetsdomain-monitor)**: `http://api.whoapi.com`
- **[Domain Monitor](/docs/widgets#domain-monitor)**: `http://api.whoapi.com`
- [WhoAPI Privacy Policy](https://whoapi.com/privacy-policy/)
- **[Crypto Watch List](/docs/widgetscrypto-watch-list)** and **[Token Price History](/docs/widgetscrypto-token-price-history)**: `https://api.coingecko.com`
- **[Crypto Watch List](/docs/widgets#crypto-watch-list)** and **[Token Price History](/docs/widgets#crypto-token-price-history)**: `https://api.coingecko.com`
- [CoinGecko Privacy Policy](https://www.coingecko.com/en/privacy)
- **[Wallet Balance](/docs/widgetswallet-balance)**: `https://api.blockcypher.com/`
- **[Wallet Balance](/docs/widgets#wallet-balance)**: `https://api.blockcypher.com/`
- [BlockCypher Privacy Policy](https://www.blockcypher.com/privacy.html)
- **[Code::Stats](/docs/widgetscode-stats)**: `https://codestats.net`
- **[Code::Stats](/docs/widgets#code-stats)**: `https://codestats.net`
- [Code::Stats Privacy Policy](https://codestats.net/tos#privacy)
- **[AnonAddy](/docs/widgetsanonaddy)**: `https://app.anonaddy.com`
- **[AnonAddy](/docs/widgets#anonaddy)**: `https://app.anonaddy.com`
- [AnonAddy Privacy Policy](https://anonaddy.com/privacy/)
- **[Vulnerability Feed](/docs/widgetsvulnerability-feed)**: `https://www.cvedetails.com`
- **[Vulnerability Feed](/docs/widgets#vulnerability-feed)**: `https://www.cvedetails.com`
- [CVE Details Privacy Policy](https://www.cvedetails.com/privacy.php)
- **[Exchange Rate](/docs/widgetsexchange-rates)**: `https://v6.exchangerate-api.com`
- **[Exchange Rate](/docs/widgets#exchange-rates)**: `https://v6.exchangerate-api.com`
- [ExchangeRateAPI Privacy Policy](https://www.exchangerate-api.com/terms)
- **[Public Holidays](/docs/widgetspublic-holidays)**: `https://kayaposoft.com`
- **[Public Holidays](/docs/widgets#public-holidays)**: `https://kayaposoft.com`
- [jurajmajer/enrico](https://github.com/jurajmajer/enrico)
- **[Covid-19 Status](/docs/widgetscovid-19-status)**: `https://codestats.net`
- **[Covid-19 Status](/docs/widgets#covid-19-status)**: `https://codestats.net`
- [disease-sh/api](https://github.com/disease-sh/api)
- **[Sports Scores](/docs/widgetssports-scores)**: `https://thesportsdb.com`
- **[Sports Scores](/docs/widgets#sports-scores)**: `https://thesportsdb.com`
- No Policy Available
- **[News Headlines](/docs/widgetsnews-headlines)**: `https://api.currentsapi.services`
- **[News Headlines](/docs/widgets#news-headlines)**: `https://api.currentsapi.services`
- [CurrentsAPI Privacy Policy](https://currentsapi.services/privacy)
- **[Mullvad Status](/docs/widgetsmullvad-status)**: `https://am.i.mullvad.net`
- **[Mullvad Status](/docs/widgets#mullvad-status)**: `https://am.i.mullvad.net`
- [Mullvad Privacy Policy](https://mullvad.net/en/help/privacy-policy/)
- **[TFL Status](/docs/widgetstfl-status)**: `https://api.tfl.gov.uk`
- **[TFL Status](/docs/widgets#tfl-status)**: `https://api.tfl.gov.uk`
- [TFL Privacy Policy](https://tfl.gov.uk/corporate/privacy-and-cookies/)
- **[Stock Price History](/docs/widgetsstock-price-history)**: `https://alphavantage.co`
- **[Stock Price History](/docs/widgets#stock-price-history)**: `https://alphavantage.co`
- [AlphaVantage Privacy Policy](https://www.alphavantage.co/privacy/)
- **[ETH Gas Prices](/docs/widgetseth-gas-prices)**: `https://ethgas.watch`
- **[ETH Gas Prices](/docs/widgets#eth-gas-prices)**: `https://ethgas.watch`
- [wslyvh/ethgaswatch](https://github.com/wslyvh/ethgaswatch)
- **[Joke](/docs/widgetsjoke)**: `https://v2.jokeapi.dev`
- **[Joke](/docs/widgets#joke)**: `https://v2.jokeapi.dev`
- [SV443's Privacy Policy](https://sv443.net/privacypolicy/en)
- **[Flight Data](/docs/widgetsflight-data)**: `https://aerodatabox.p.rapidapi.com`
- **[Flight Data](/docs/widgets#flight-data)**: `https://aerodatabox.p.rapidapi.com`
- [AeroDataBox Privacy Policy](https://www.aerodatabox.com/#h.p_CXtIYZWF_WQd)
- **[Astronomy Picture of the Day](/docs/widgetsastronomy-picture-of-the-day)**: `https://apodapi.herokuapp.com`
- **[Astronomy Picture of the Day](/docs/widgets#astronomy-picture-of-the-day)**: `https://apodapi.herokuapp.com`
- [NASA's Privacy Policy](https://www.nasa.gov/about/highlights/HP_Privacy.html)
- **[GitHub Trending](/docs/widgetsgithub-trending)** and **[GitHub Profile Stats](/docs/widgetsgithub-profile-stats)**: `https://api.github.com`
- **[GitHub Trending](/docs/widgets#github-trending)** and **[GitHub Profile Stats](/docs/widgets#github-profile-stats)**: `https://api.github.com`
- [GitHub's Privacy Policy](https://docs.github.com/en/github/site-policy/github-privacy-statement)
- **[Cron Monitoring (Health Checks)](/docs/widgetscron-monitoring-health-checks)**: `https://healthchecks.io`
- **[Cron Monitoring (Health Checks)](/docs/widgets#cron-monitoring-health-checks)**: `https://healthchecks.io`
- [Health-Checks Privacy Policy](https://healthchecks.io/privacy/)
---
@ -210,7 +210,7 @@ The following section outlines all data that is stored in the browsers, as cooki
### Deleting Stored Data
You can manually view and delete session storage, local storage and cookies at anytime. Fist [open](/docs/troubleshootinghow-to-open-browser-console) your browsers developer tools (usually <kbd>F12</kbd>), then under the Application tab select the storage category. Here you will see a list of stored data, and you can select any item and delete it.
You can manually view and delete session storage, local storage and cookies at anytime. Fist [open](/docs/troubleshooting#how-to-open-browser-console) your browsers developer tools (usually <kbd>F12</kbd>), then under the Application tab select the storage category. Here you will see a list of stored data, and you can select any item and delete it.
---
@ -233,7 +233,7 @@ If you're running Dashy in a container, see [Management Docs --> Container Secur
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](/docs/authenticationalternative-authentication-methods) to prevent unauthorized access
- Configure [authentication](/docs/authentication#alternative-authentication-methods) to prevent unauthorized access
- Keep your system, software and Dashy up-to-date
- Ensure your server is appropriately secured
- Manage users and SSH correctly
@ -256,7 +256,7 @@ Dashy supports SRI, and it is recommended to enable this if you are hosting your
### SSL
Native SSL support is enabled, for setup instructions, see the [Management Docs](/docs/managementssl-certificates)
Native SSL support is enabled, for setup instructions, see the [Management Docs](/docs/management#ssl-certificates)
### Authentication

3
docs/quick-start.md
View File

@ -124,7 +124,7 @@ Then edit `./public/conf.yml` and rebuild the app with `yarn build`
## Alternative Deployment Method 2 - Netlify
Don't have a server? No problem! You can run Dashy for free on Netlify (as well as many [other cloud providers](/docs/deployment.md#deploy-to-cloud-service)). All you need it a GitHub account.
Don't have a server? No problem! You can run Dashy for free on Netlify (as well as many [other cloud providers](/docs/deployment#deploy-to-cloud-service)). All you need it a GitHub account.
1. Fork Dashy's repository on GitHub
2. [Log in](app.netlify.com/login/) to Netlify with GitHub
@ -143,3 +143,4 @@ Dashy supports 1-Click deployments on several popular cloud platforms. To spin u
- [<img src="https://i.ibb.co/xCHtzgh/render.png" width="18"/> Deploy to Render](https://render.com/deploy?repo=https://github.com/lissy93/dashy/tree/deploy_render)
- [<img src="https://i.ibb.co/J7MGymY/googlecloud.png" width="18"/> Deploy to GCP](https://deploy.cloud.run/?git_repo=https://github.com/lissy93/dashy.git)
- [<img src="https://i.ibb.co/HVWVYF7/docker.png" width="18"/> Deploy to PWD](https://labs.play-with-docker.com/?stack=https://raw.githubusercontent.com/Lissy93/dashy/master/docker-compose.yml)
- [<img src="https://i.ibb.co/7NxnM2P/easypanel.png" width="18"/> Deploy to Easypanel](https://easypanel.io/docs/templates/dashy)

78
docs/readme.md
View File

@ -1,39 +1,39 @@
# ![Dashy Docs](https://i.ibb.co/4mdNf7M/heading-docs.png)
## Running Dashy
- [Quick Start](/docs/quick-start) - TLDR guide on getting Dashy up and running
- [Deployment](/docs/deployment) - Full guide on deploying Dashy either locally or online
- [Configuring](/docs/configuring) - Complete list of all available options in the config file
- [App Management](/docs/management) - Managing your app, updating, security, web server configuration, etc
- [Troubleshooting](/docs/troubleshooting) - Common errors and problems, and how to fix them
## Development and Contributing
- [Developing](/docs/developing) - Running Dashy development server locally, and general workflow
- [Development Guides](/docs/development-guides) - Common development tasks, to help new contributors
- [Contributing](/docs/contributing) - How you can help keep Dashy alive
- [Showcase](/docs/showcase) - See how others are using Dashy, and share your dashboard
- [Credits](/docs/credits) - List of people and projects that have made Dashy possible
- [Release Workflow](/docs/release-workflow) - Info about releases, CI and automated tasks
## Feature Docs
- [Authentication](/docs/authentication) - Guide to setting up authentication to protect your dashboard
- [Alternate Views](/docs/alternate-views) - Outline of available pages / views and item opening methods
- [Backup & Restore](/docs/backup-restore) - Guide to backing up config with Dashy's cloud sync feature
- [Icons](/docs/icons) - Outline of all available icon types for sections and items, with examples
- [Language Switching](/docs/multi-language-support) - Details on how to switch language, or add a new locale
- [Pages and Sections](/docs/pages-and-sections) - Multi-page support, sections, items and sub-items
- [Status Indicators](/docs/status-indicators) - Using Dashy to monitor uptime and status of your apps
- [Searching & Shortcuts](/docs/searching) - Searching, launching methods + keyboard shortcuts
- [Theming](/docs/theming) - Complete guide to applying, writing and modifying themes + styles
- [Widgets](/docs/widgets) - List of all dynamic content widgets, with usage guides and examples
## Misc
- [Privacy & Security](/docs/privacy) - List of requests, potential issues, and security resources
- [License](/LICENSE) - Copy of the MIT License
- [Legal](/.github/LEGAL) - Licenses of direct dependencies
- [Code of Conduct](/.github/CODE_OF_CONDUCT) - Contributor Covenant Code of Conduct
- [Changelog](/.github/CHANGELOG) - Details of recent changes, and historical versions
# ![Dashy Docs](https://i.ibb.co/4mdNf7M/heading-docs.png)
## Running Dashy
- [Quick Start](/docs/quick-start) - TLDR guide on getting Dashy up and running
- [Deployment](/docs/deployment) - Full guide on deploying Dashy either locally or online
- [Configuring](/docs/configuring) - Complete list of all available options in the config file
- [App Management](/docs/management) - Managing your app, updating, security, web server configuration, etc
- [Troubleshooting](/docs/troubleshooting) - Common errors and problems, and how to fix them
## Development and Contributing
- [Developing](/docs/developing) - Running Dashy development server locally, and general workflow
- [Development Guides](/docs/development-guides) - Common development tasks, to help new contributors
- [Contributing](/docs/contributing) - How you can help keep Dashy alive
- [Showcase](/docs/showcase) - See how others are using Dashy, and share your dashboard
- [Credits](/docs/credits) - List of people and projects that have made Dashy possible
- [Release Workflow](/docs/release-workflow) - Info about releases, CI and automated tasks
## Feature Docs
- [Authentication](/docs/authentication) - Guide to setting up authentication to protect your dashboard
- [Alternate Views](/docs/alternate-views) - Outline of available pages / views and item opening methods
- [Backup & Restore](/docs/backup-restore) - Guide to backing up config with Dashy's cloud sync feature
- [Icons](/docs/icons) - Outline of all available icon types for sections and items, with examples
- [Language Switching](/docs/multi-language-support) - Details on how to switch language, or add a new locale
- [Pages and Sections](/docs/pages-and-sections) - Multi-page support, sections, items and sub-items
- [Status Indicators](/docs/status-indicators) - Using Dashy to monitor uptime and status of your apps
- [Searching & Shortcuts](/docs/searching) - Searching, launching methods + keyboard shortcuts
- [Theming](/docs/theming) - Complete guide to applying, writing and modifying themes + styles
- [Widgets](/docs/widgets) - List of all dynamic content widgets, with usage guides and examples
## Misc
- [Privacy & Security](/docs/privacy) - List of requests, potential issues, and security resources
- [License](/LICENSE) - Copy of the MIT License
- [Legal](/.github/LEGAL) - Licenses of direct dependencies
- [Code of Conduct](/.github/CODE_OF_CONDUCT) - Contributor Covenant Code of Conduct
- [Changelog](/.github/CHANGELOG) - Details of recent changes, and historical versions

332
docs/release-workflow.md
View File

@ -1,166 +1,166 @@
# Releases and Workflows
- [Release Schedule](#release-schedule)
- [Deployment Process](#deployment-process)
- [Git Strategy](#git-strategy)
- [Automated Workflows](#automated-workflows)
## Release Schedule
We're using [Semantic Versioning](https://semver.org/), to indicate major, minor and patch versions. You can find the current version number in the readme, and check your apps version under the config menu. The version number is pulled from the [package.json](https://github.com/Lissy93/dashy/blob/master/package.json#L3) file.
Typically there is a new major release every 2 weeks, usually on Sunday, and you can view these under the [Releases Page](https://github.com/Lissy93/dashy/releases). Each new version will also have a corresponding [tag on GitHub](https://github.com/Lissy93/dashy/tags), and each major release will also result in the creation of a new [tag on DockerHub](https://hub.docker.com/r/lissy93/dashy/tags), so that you can fix your container to a certain version.
For a full breakdown of each change, you can view the [Changelog](https://github.com/Lissy93/dashy/blob/master/.github/CHANGELOG). Each new feature or significant change needs to be submitted through a pull request, which makes it easy to review and track these changes, and roll back if needed.
---
## Deployment Process
All changes and new features are submitted as pull requests, which can then be tested, reviewed and (hopefully) merged into the master branch. Every time there is a change in the major version number, a new release is published. This usually happens every 2 weeks, on a Sunday.
When a PR is opened:
- The feature branch is built, and deployed as a Netlify instance. This can be accessed at: `https://deploy-preview-[pr-number]--dashy-dev.netlify.app`, and this URL as well as a link to the build logs are added as a comment on the PR by Netlify bot
- Depending on what files were modified, the bot may also add a comment to remind the author of useful info
- A series of checks will run on the new code, using GH Actions, and prevent merging if they fail. This includes: linting, testing, code quality and complexity checking, security scanning and a spell check
- If a new dependency was added, liss-bot will comment with a summary of those changes, as well as the cost of the module, version, and any security concerns. If the bundle size has increased, this will also be added as a comment
After the PR is merged:
- The app is build, and deployed to: <https://dev.dashy.to>
- A new tag in GitHub is created, using the apps version number (from the package.json)
- The Docker container is built, and published under the `:latest` tag on DockerHub and GHCR
When a new major version is released:
- A new GitHub release is created and published, under new versions tag, with info from the changelog
- The container is built and published under a new tag will be created on DockerHub, called `:release-[version]`
- An announcement is opened in GitHub discussions, outlining the main changes, where users can comment and ask questions
[![Netlify Status](https://api.netlify.com/api/v1/badges/3a0216c3-1ed0-40f5-ad90-ff68b1c96c09/deploy-status)](https://app.netlify.com/sites/dashy-dev/deploys)
---
## Git Strategy
### Git Flow
Like most Git repos, we are following the [Github Flow](https://guides.github.com/introduction/flow) standard.
1. Create a branch (or fork if you don'd have write access)
2. Code some awesome stuff, then add and commit your changes
3. Create a Pull Request, complete the checklist and ensure the build succeeds
4. Follow up with any reviews on your code
5. Merge 🎉
### Git Branch Naming
The format of your branch name should be something similar to: `[TYPE]/[TICKET]_[TITLE]`
For example, `FEATURE/420_Awesome-feature` or `FIX/690_login-server-error`
### Commit Emojis
Using a single emoji at the start of each commit message, to indicate the type task, makes the commit ledger easier to understand, plus it looks cool.
- 🎨 `:art:` - Improve structure / format of the code.
- ⚡️ `:zap:` - Improve performance.
- 🔥 `:fire:` - Remove code or files.
- 🐛 `:bug:` - Fix a bug.
- 🚑️ `:ambulance:` - Critical hotfix
- ✨ `:sparkles:` - Introduce new features.
- 📝 `:memo:` - Add or update documentation.
- 🚀 `:rocket:` - Deploy stuff.
- 💄 `:lipstick:` - Add or update the UI and style files.
- 🎉 `:tada:` - Begin a project.
- ✅ `:white_check_mark:` - Add, update, or pass tests.
- 🔒️ `:lock:` - Fix security issues.
- 🔖 `:bookmark:` - Make a Release or Version tag.
- 🚨 `:rotating_light:` - Fix compiler / linter warnings.
- 🚧 `:construction:` - Work in progress.
- ⬆️ `:arrow_up:` - Upgrade dependencies.
- 👷 `:construction_worker:` - Add or update CI build system.
- ♻️ `:recycle:` - Refactor code.
- 🩹 `:adhesive_bandage:` - Simple fix for a non-critical issue.
- 🔧 `:wrench:` - Add or update configuration files.
- 🍱 `:bento:` - Add or update assets.
- 🗃️ `:card_file_box:` - Perform database schema related changes.
- ✏️ `:pencil2:` - Fix typos.
- 🌐 `:globe_with_meridians:` - Internationalization and translations.
For a full list of options, see [gitmoji.dev](https://gitmoji.dev/)
### PR Guidelines
Once you've made your changes, and pushed them to your fork or branch, you're ready to open a pull request!
For a pull request to be merged, it must:
- Must be backwards compatible
- The build, lint and tests (run by GH actions) must pass
- There must not be any merge conflicts
When you submit your PR, include the required info, by filling out the PR template. Including:
- A brief description of your changes
- The issue, ticket or discussion number (if applicable)
- For UI relate updates include a screenshot
- If any dependencies were added, explain why it was needed, state the cost associated, and confirm it does not introduce any security issues
- Finally, check the checkboxes, to confirm that the standards are met, and hit submit!
---
## Automated Workflows
Dashy makes heavy use of [GitHub Actions](https://github.com/features/actions) to fully automate the checking, testing, building, deploying of the project, as well as administration tasks like management of issues, tags, releases and documentation. The following section outlines each workflow, along with a link the the action file, current status and short description. A lot of these automations were made possible using community actions contributed to GH marketplace by some amazing people.
### Code Processing
Action | Description
--- | ---
**Code Linter**<br/>[![code-linter.yml](https://github.com/Lissy93/dashy/actions/workflows/code-linter.yml/badge.svg)](https://github.com/Lissy93/dashy/actions/workflows/code-linter.yml) | After a pull request is created, all new code changes will be linted, and the CI will fail with a helpful message if the code has any formatting inconsistencies
**Code Spell Check**<br/>[![code-spell-check.yml](https://github.com/Lissy93/dashy/actions/workflows/code-spell-check.yml/badge.svg)](https://github.com/Lissy93/dashy/actions/workflows/code-spell-check.yml) | After a PR submitted, all auto-fixable spelling errors will be detected, then Liss-Bot will create a separate PR to propose the fixes
**Dependency Update Summary** <br/>[![dependency-updates-summary.yml](https://github.com/Lissy93/dashy/actions/workflows/dependency-updates-summary.yml/badge.svg)](https://github.com/Lissy93/dashy/actions/workflows/dependency-updates-summary.yml) | After a PR is submitted, if any of the dependencies are modified, then Liss-Bot will add a comment, explaining which packages have been added, removed, updated or downgraded, as well as other helpful info
**Get Size** <br/>[![get-size.yml](https://github.com/Lissy93/dashy/actions/workflows/get-size.yml/badge.svg)](https://github.com/Lissy93/dashy/actions/workflows/get-size.yml) | Adds comment to PR if the size of the built + bundled application has changed compared to the previous version
**Security Scan** <br/>[![security-scanning.yml](https://github.com/Lissy93/dashy/actions/workflows/security-scanning.yml/badge.svg)](https://github.com/Lissy93/dashy/actions/workflows/security-scanning.yml) | Uses Snyk to scan the code and dependencies after a PR. Will add a comment and cause the build to fail if a new vulnerability or potential issue is present
### Releases
Action | Description
--- | ---
**Create Tag** <br/>[![auto-tag-pr.yml](https://github.com/Lissy93/dashy/actions/workflows/auto-tag-pr.yml/badge.svg)](https://github.com/Lissy93/dashy/actions/workflows/auto-tag-pr.yml) | Whenever the version indicated in package.json is updates, a new GitHub tag will be created for that point in time
**Build App** <br/>[![build-app.yml](https://github.com/Lissy93/dashy/actions/workflows/build-app.yml/badge.svg)](https://github.com/Lissy93/dashy/actions/workflows/build-app.yml) | After changes are merged into the master branch, the app will be build, with output pushed to the `dev-demo` branch
**Cache Artifacts** <br/>[![cache-artifacts.yml](https://github.com/Lissy93/dashy/actions/workflows/cache-artifacts.yml/badge.svg)](https://github.com/Lissy93/dashy/actions/workflows/cache-artifacts.yml) | After build, returned files will be cached for future actions for that commit
**Docker Publish** <br/>[![docker-publish.yml](https://github.com/Lissy93/dashy/actions/workflows/docker-publish.yml/badge.svg)](https://github.com/Lissy93/dashy/actions/workflows/docker-publish.yml) | After PR is merged, the multi-architecture Docker container will be built, and then published to GHCR
### Issue Management
Action | Description
--- | ---
**Close Incomplete Issues** <br/>[![close-incomplete-issues.yml](https://github.com/Lissy93/dashy/actions/workflows/close-incomplete-issues.yml/badge.svg)](https://github.com/Lissy93/dashy/actions/workflows/close-incomplete-issues.yml) | Issues which do not match any of the issue templates will be closed, and a comment posted explaining why
**Close Stale Issues** <br/>[![close-stale-issues.yml](https://github.com/Lissy93/dashy/actions/workflows/close-stale-issues.yml/badge.svg)](https://github.com/Lissy93/dashy/actions/workflows/close-stale-issues.yml) | Issues which have not been updated for 6 weeks will have a comment posted to them. If the author does not reply within the next week, then the issue will be marked as stale and closed. The original author may still reopen the issue at any time
**Close Potential Spam Issues** <br/>[![issue-spam-control.yml](https://github.com/Lissy93/dashy/actions/workflows/issue-spam-control.yml/badge.svg)](https://github.com/Lissy93/dashy/actions/workflows/issue-spam-control.yml) | Auto-closes issues, and adds a comment if it was submitted by a user who hasn't yet interacted with the repo, is new to GitHub and has not starred the repository. The comment will advise them to check their issue is complete, and then allow them to reopen it
**Issue Translator** <br/>[![issue-translator.yml](https://github.com/Lissy93/dashy/actions/workflows/issue-translator.yml/badge.svg)](https://github.com/Lissy93/dashy/actions/workflows/issue-translator.yml) | Auto-translates any comments and issues that were written in any language other than English, and posts the translation as a comment below
**Label Sponsors** <br/>[![label-sponsors.yml](https://github.com/Lissy93/dashy/actions/workflows/label-sponsors.yml/badge.svg)](https://github.com/Lissy93/dashy/actions/workflows/label-sponsors.yml) | Adds a special label to any issues or pull requests raised by users who are sponsoring the project via GitHub, so that they can get priority support
**LGTM Comment**<br/>[![lgtm-comment.yml](https://github.com/Lissy93/dashy/actions/workflows/lgtm-comment.yml/badge.svg)](https://github.com/Lissy93/dashy/actions/workflows/lgtm-comment.yml) | When a PR review contains the words LGTM (looks good to me), the Liss-Bot will reply with a random celebratory or thumbs up GIF, just as a bit of fun
**Mind your Language** <br/>[![mind-your-language.yml](https://github.com/Lissy93/dashy/actions/workflows/mind-your-language.yml/badge.svg)](https://github.com/Lissy93/dashy/actions/workflows/mind-your-language.yml) | Replies to any comment (on issue or PR) that contains profanities, offensive or inappropriate language with a polite note reminding the user of the code of conduct
**Release Notifier** <br/>[![release-commenter.yml](https://github.com/Lissy93/dashy/actions/workflows/release-commenter.yml/badge.svg)](https://github.com/Lissy93/dashy/actions/workflows/release-commenter.yml) | Once a release has been published which fixes an issue, a comment will be added to the relevant issues informing the user who raised it that it was fixed in the current release
**Update Issue after Merge** <br/>[![update-issue-after-pr.yml](https://github.com/Lissy93/dashy/actions/workflows/update-issue-after-pr.yml/badge.svg)](https://github.com/Lissy93/dashy/actions/workflows/update-issue-after-pr.yml) | After a PR which fixes an issue is merged, Liss-Bot will add a comment to said issue based on the git commit message
**Auto Add Comment Based on Tag** <br/>[![add-comment-from-tag.yml](https://github.com/Lissy93/dashy/actions/workflows/add-comment-from-tag.yml/badge.svg)](https://github.com/Lissy93/dashy/actions/workflows/add-comment-from-tag.yml) | Will add comment with useful info to certain issues, based on the tag applied
### PR Management
Action | Description
--- | ---
**PR Commenter** <br/>[![pr-commenter.yml](https://github.com/Lissy93/dashy/actions/workflows/pr-commenter.yml/badge.svg)](https://github.com/Lissy93/dashy/actions/workflows/pr-commenter.yml) | Adds comment with helpful info to pull requests, based on which files have been changes
**Issue from Todo Code** <br/>[![raise-issue-from-todo.yml](https://github.com/Lissy93/dashy/actions/workflows/raise-issue-from-todo.yml/badge.svg)](https://github.com/Lissy93/dashy/actions/workflows/raise-issue-from-todo.yml) | When a `todo` note is found in the code after a PR, then Liss-Bot will automatically raise an issue, so that the todo can be addressed/ implemented. The issue will be closed once the todo has been implemented or removed
### Documentation & Reports
Action | Description
--- | ---
**Generate Credits** <br/>[![generate-credits.yml](https://github.com/Lissy93/dashy/actions/workflows/generate-credits.yml/badge.svg)](https://github.com/Lissy93/dashy/actions/workflows/generate-credits.yml) | Generates a report, including contributors, collaborators, sponsors, bots and helpful users. Will then insert a markdown table with thanks to these GitHub users and links to their profiles into the Credits page, as well as a summary of sponsors and top contributors into the main readme
**Wiki Sync** <br/>[![wiki-sync.yml](https://github.com/Lissy93/dashy/actions/workflows/wiki-sync.yml/badge.svg)](https://github.com/Lissy93/dashy/actions/workflows/wiki-sync.yml) | Generates and publishes the repositories wiki page using the markdown files within the docs directory
---
# Releases and Workflows
- [Release Schedule](#release-schedule)
- [Deployment Process](#deployment-process)
- [Git Strategy](#git-strategy)
- [Automated Workflows](#automated-workflows)
## Release Schedule
We're using [Semantic Versioning](https://semver.org/), to indicate major, minor and patch versions. You can find the current version number in the readme, and check your apps version under the config menu. The version number is pulled from the [package.json](https://github.com/Lissy93/dashy/blob/master/package.json#L3) file.
Typically there is a new major release every 2 weeks, usually on Sunday, and you can view these under the [Releases Page](https://github.com/Lissy93/dashy/releases). Each new version will also have a corresponding [tag on GitHub](https://github.com/Lissy93/dashy/tags), and each major release will also result in the creation of a new [tag on DockerHub](https://hub.docker.com/r/lissy93/dashy/tags), so that you can fix your container to a certain version.
For a full breakdown of each change, you can view the [Changelog](https://github.com/Lissy93/dashy/blob/master/.github/CHANGELOG.md). Each new feature or significant change needs to be submitted through a pull request, which makes it easy to review and track these changes, and roll back if needed.
---
## 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](https://api.netlify.com/api/v1/badges/3a0216c3-1ed0-40f5-ad90-ff68b1c96c09/deploy-status)](https://app.netlify.com/sites/dashy-dev/deploys)
---
## Git Strategy
### Git Flow
Like most Git repos, we are following the [Github Flow](https://guides.github.com/introduction/flow) standard.
1. Create a branch (or fork if you don'd have write access)
2. Code some awesome stuff, then add and commit your changes
3. Create a Pull Request, complete the checklist and ensure the build succeeds
4. Follow up with any reviews on your code
5. Merge 🎉
### Git Branch Naming
The format of your branch name should be something similar to: `[TYPE]/[TICKET]_[TITLE]`
For example, `FEATURE/420_Awesome-feature` or `FIX/690_login-server-error`
### Commit Emojis
Using a single emoji at the start of each commit message, to indicate the type task, makes the commit ledger easier to understand, plus it looks cool.
- 🎨 `:art:` - Improve structure / format of the code.
- ⚡️ `:zap:` - Improve performance.
- 🔥 `:fire:` - Remove code or files.
- 🐛 `:bug:` - Fix a bug.
- 🚑️ `:ambulance:` - Critical hotfix
- ✨ `:sparkles:` - Introduce new features.
- 📝 `:memo:` - Add or update documentation.
- 🚀 `:rocket:` - Deploy stuff.
- 💄 `:lipstick:` - Add or update the UI and style files.
- 🎉 `:tada:` - Begin a project.
- ✅ `:white_check_mark:` - Add, update, or pass tests.
- 🔒️ `:lock:` - Fix security issues.
- 🔖 `:bookmark:` - Make a Release or Version tag.
- 🚨 `:rotating_light:` - Fix compiler / linter warnings.
- 🚧 `:construction:` - Work in progress.
- ⬆️ `:arrow_up:` - Upgrade dependencies.
- 👷 `:construction_worker:` - Add or update CI build system.
- ♻️ `:recycle:` - Refactor code.
- 🩹 `:adhesive_bandage:` - Simple fix for a non-critical issue.
- 🔧 `:wrench:` - Add or update configuration files.
- 🍱 `:bento:` - Add or update assets.
- 🗃️ `:card_file_box:` - Perform database schema related changes.
- ✏️ `:pencil2:` - Fix typos.
- 🌐 `:globe_with_meridians:` - Internationalization and translations.
For a full list of options, see [gitmoji.dev](https://gitmoji.dev/)
### PR Guidelines
Once you've made your changes, and pushed them to your fork or branch, you're ready to open a pull request!
For a pull request to be merged, it must:
- Must be backwards compatible
- The build, lint and tests (run by GH actions) must pass
- There must not be any merge conflicts
When you submit your PR, include the required info, by filling out the PR template. Including:
- A brief description of your changes
- The issue, ticket or discussion number (if applicable)
- For UI relate updates include a screenshot
- If any dependencies were added, explain why it was needed, state the cost associated, and confirm it does not introduce any security issues
- Finally, check the checkboxes, to confirm that the standards are met, and hit submit!
---
## Automated Workflows
Dashy makes heavy use of [GitHub Actions](https://github.com/features/actions) to fully automate the checking, testing, building, deploying of the project, as well as administration tasks like management of issues, tags, releases and documentation. The following section outlines each workflow, along with a link the the action file, current status and short description. A lot of these automations were made possible using community actions contributed to GH marketplace by some amazing people.
### Code Processing
Action | Description
--- | ---
**Code Linter**<br/>[![code-linter.yml](https://github.com/Lissy93/dashy/actions/workflows/code-linter.yml/badge.svg)](https://github.com/Lissy93/dashy/actions/workflows/code-linter.yml) | After a pull request is created, all new code changes will be linted, and the CI will fail with a helpful message if the code has any formatting inconsistencies
**Code Spell Check**<br/>[![code-spell-check.yml](https://github.com/Lissy93/dashy/actions/workflows/code-spell-check.yml/badge.svg)](https://github.com/Lissy93/dashy/actions/workflows/code-spell-check.yml) | After a PR submitted, all auto-fixable spelling errors will be detected, then Liss-Bot will create a separate PR to propose the fixes
**Dependency Update Summary** <br/>[![dependency-updates-summary.yml](https://github.com/Lissy93/dashy/actions/workflows/dependency-updates-summary.yml/badge.svg)](https://github.com/Lissy93/dashy/actions/workflows/dependency-updates-summary.yml) | After a PR is submitted, if any of the dependencies are modified, then Liss-Bot will add a comment, explaining which packages have been added, removed, updated or downgraded, as well as other helpful info
**Get Size** <br/>[![get-size.yml](https://github.com/Lissy93/dashy/actions/workflows/get-size.yml/badge.svg)](https://github.com/Lissy93/dashy/actions/workflows/get-size.yml) | Adds comment to PR if the size of the built + bundled application has changed compared to the previous version
**Security Scan** <br/>[![security-scanning.yml](https://github.com/Lissy93/dashy/actions/workflows/security-scanning.yml/badge.svg)](https://github.com/Lissy93/dashy/actions/workflows/security-scanning.yml) | Uses Snyk to scan the code and dependencies after a PR. Will add a comment and cause the build to fail if a new vulnerability or potential issue is present
### Releases
Action | Description
--- | ---
**Create Tag** <br/>[![auto-tag-pr.yml](https://github.com/Lissy93/dashy/actions/workflows/auto-tag-pr.yml/badge.svg)](https://github.com/Lissy93/dashy/actions/workflows/auto-tag-pr.yml) | Whenever the version indicated in package.json is updates, a new GitHub tag will be created for that point in time
**Build App** <br/>[![build-app.yml](https://github.com/Lissy93/dashy/actions/workflows/build-app.yml/badge.svg)](https://github.com/Lissy93/dashy/actions/workflows/build-app.yml) | After changes are merged into the master branch, the app will be build, with output pushed to the `dev-demo` branch
**Cache Artifacts** <br/>[![cache-artifacts.yml](https://github.com/Lissy93/dashy/actions/workflows/cache-artifacts.yml/badge.svg)](https://github.com/Lissy93/dashy/actions/workflows/cache-artifacts.yml) | After build, returned files will be cached for future actions for that commit
**Docker Publish** <br/>[![docker-publish.yml](https://github.com/Lissy93/dashy/actions/workflows/docker-publish.yml/badge.svg)](https://github.com/Lissy93/dashy/actions/workflows/docker-publish.yml) | After PR is merged, the multi-architecture Docker container will be built, and then published to GHCR
### Issue Management
Action | Description
--- | ---
**Close Incomplete Issues** <br/>[![close-incomplete-issues.yml](https://github.com/Lissy93/dashy/actions/workflows/close-incomplete-issues.yml/badge.svg)](https://github.com/Lissy93/dashy/actions/workflows/close-incomplete-issues.yml) | Issues which do not match any of the issue templates will be closed, and a comment posted explaining why
**Close Stale Issues** <br/>[![close-stale-issues.yml](https://github.com/Lissy93/dashy/actions/workflows/close-stale-issues.yml/badge.svg)](https://github.com/Lissy93/dashy/actions/workflows/close-stale-issues.yml) | Issues which have not been updated for 6 weeks will have a comment posted to them. If the author does not reply within the next week, then the issue will be marked as stale and closed. The original author may still reopen the issue at any time
**Close Potential Spam Issues** <br/>[![issue-spam-control.yml](https://github.com/Lissy93/dashy/actions/workflows/issue-spam-control.yml/badge.svg)](https://github.com/Lissy93/dashy/actions/workflows/issue-spam-control.yml) | Auto-closes issues, and adds a comment if it was submitted by a user who hasn't yet interacted with the repo, is new to GitHub and has not starred the repository. The comment will advise them to check their issue is complete, and then allow them to reopen it
**Issue Translator** <br/>[![issue-translator.yml](https://github.com/Lissy93/dashy/actions/workflows/issue-translator.yml/badge.svg)](https://github.com/Lissy93/dashy/actions/workflows/issue-translator.yml) | Auto-translates any comments and issues that were written in any language other than English, and posts the translation as a comment below
**Label Sponsors** <br/>[![label-sponsors.yml](https://github.com/Lissy93/dashy/actions/workflows/label-sponsors.yml/badge.svg)](https://github.com/Lissy93/dashy/actions/workflows/label-sponsors.yml) | Adds a special label to any issues or pull requests raised by users who are sponsoring the project via GitHub, so that they can get priority support
**LGTM Comment**<br/>[![lgtm-comment.yml](https://github.com/Lissy93/dashy/actions/workflows/lgtm-comment.yml/badge.svg)](https://github.com/Lissy93/dashy/actions/workflows/lgtm-comment.yml) | When a PR review contains the words LGTM (looks good to me), the Liss-Bot will reply with a random celebratory or thumbs up GIF, just as a bit of fun
**Mind your Language** <br/>[![mind-your-language.yml](https://github.com/Lissy93/dashy/actions/workflows/mind-your-language.yml/badge.svg)](https://github.com/Lissy93/dashy/actions/workflows/mind-your-language.yml) | Replies to any comment (on issue or PR) that contains profanities, offensive or inappropriate language with a polite note reminding the user of the code of conduct
**Release Notifier** <br/>[![release-commenter.yml](https://github.com/Lissy93/dashy/actions/workflows/release-commenter.yml/badge.svg)](https://github.com/Lissy93/dashy/actions/workflows/release-commenter.yml) | Once a release has been published which fixes an issue, a comment will be added to the relevant issues informing the user who raised it that it was fixed in the current release
**Update Issue after Merge** <br/>[![update-issue-after-pr.yml](https://github.com/Lissy93/dashy/actions/workflows/update-issue-after-pr.yml/badge.svg)](https://github.com/Lissy93/dashy/actions/workflows/update-issue-after-pr.yml) | After a PR which fixes an issue is merged, Liss-Bot will add a comment to said issue based on the git commit message
**Auto Add Comment Based on Tag** <br/>[![add-comment-from-tag.yml](https://github.com/Lissy93/dashy/actions/workflows/add-comment-from-tag.yml/badge.svg)](https://github.com/Lissy93/dashy/actions/workflows/add-comment-from-tag.yml) | Will add comment with useful info to certain issues, based on the tag applied
### PR Management
Action | Description
--- | ---
**PR Commenter** <br/>[![pr-commenter.yml](https://github.com/Lissy93/dashy/actions/workflows/pr-commenter.yml/badge.svg)](https://github.com/Lissy93/dashy/actions/workflows/pr-commenter.yml) | Adds comment with helpful info to pull requests, based on which files have been changes
**Issue from Todo Code** <br/>[![raise-issue-from-todo.yml](https://github.com/Lissy93/dashy/actions/workflows/raise-issue-from-todo.yml/badge.svg)](https://github.com/Lissy93/dashy/actions/workflows/raise-issue-from-todo.yml) | When a `todo` note is found in the code after a PR, then Liss-Bot will automatically raise an issue, so that the todo can be addressed/ implemented. The issue will be closed once the todo has been implemented or removed
### Documentation & Reports
Action | Description
--- | ---
**Generate Credits** <br/>[![generate-credits.yml](https://github.com/Lissy93/dashy/actions/workflows/generate-credits.yml/badge.svg)](https://github.com/Lissy93/dashy/actions/workflows/generate-credits.yml) | Generates a report, including contributors, collaborators, sponsors, bots and helpful users. Will then insert a markdown table with thanks to these GitHub users and links to their profiles into the Credits page, as well as a summary of sponsors and top contributors into the main readme
**Wiki Sync** <br/>[![wiki-sync.yml](https://github.com/Lissy93/dashy/actions/workflows/wiki-sync.yml/badge.svg)](https://github.com/Lissy93/dashy/actions/workflows/wiki-sync.yml) | Generates and publishes the repositories wiki page using the markdown files within the docs directory
---

4
docs/showcase/readme.md
View File

@ -1,2 +1,2 @@
See: [Showcase](/docs/showcase).
See: [Showcase](/docs/showcase).

218
docs/status-indicators.md
View File

@ -1,109 +1,109 @@
# Status Indicators
Dashy has an optional feature that can display a small icon next to each of your running services, indicating it's current status. This can be useful if you are using Dashy as your homelab's start page, as it gives you an overview of the health of each of your running services. The status feature will show response time, response code, online/ offline check and if applicable, a relevant error message.
<p align="center">
<img width="800" src="/docs/assets/status-check-demo.gif" />
</p>
## Enabling Status Indicators
By default, this feature is off. If you do not want this feature, just don't add the `statusCheck` to your conf.yml file, then no requests will be made.
To enable status checks, you can either turn it on for all items, by setting `appConfig.statusCheck: true`, like:
```yaml
appConfig:
statusCheck: true
```
Or you can enable/ disable it on a per-item basis, with the `item[n].statusCheck` attribute
```yaml
sections:
- name: Firewall
items:
- title: OPNsense
description: Firewall Central Management
icon: networking/opnsense.png
url: https://192.168.1.1
statusCheck: false
- title: MalTrail
description: Malicious traffic detection system
icon: networking/maltrail.png
url: http://192.168.1.1:8338
statusCheck: true
- title: Ntopng
description: Network traffic probe and network use monitor
icon: networking/ntop.png
url: http://192.168.1.1:3001
statusCheck: true
```
## Continuous Checking
By default, with status indicators enabled Dashy will check an applications status on page load, and will not keep indicators updated. This is usually desirable behavior. However, if you do want the status indicators to continue to poll your running services, this can be enabled by setting the `statusCheckInterval` attribute. Here you define an interval as an integer in seconds, and Dashy will poll your apps every x seconds. Note that if this number is very low (below 5 seconds), you may notice the app running slightly slower.
The following example, will instruct Dashy to continuously check the status of your services every 20 seconds.
```text
appConfig:
statusCheck: true
statusCheckInterval: 20
```
## Using a Different Endpoint
By default, the status checker will use the URL of each application being checked. In some situations, you may want to use a different endpoint for status checking. Similarly, some services provide a dedicated path for uptime monitoring.
You can set the `statusCheckUrl` property on any given item in order to do this. The status checker will then ping that endpoint, instead of the apps main `url` property.
## Setting Custom Headers
If your service is responding with an error, despite being up and running, it is most likely because custom headers for authentication, authorization or encoding are required. You can define these headers under the `statusCheckHeaders` property for any service. It should be defined as an object format, with the name of header as the key, and header content as the value.
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`
## Allowing Alternative Status Codes
If you expect your service to return a status code that is not in the 2XX range, and still want the indicator to be green, then you can specify an expected status code under `statusCheckAcceptCodes` for a given item. For example, `statusCheckAcceptCodes: '403,418'`
## Troubleshooting Failing Status Checks
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 [above](#setting-custom-headers).
If you are still having issues, it may be because your target application is blocking requests from Dashy's IP. This is a [CORS error](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS), and can be fixed by setting the headers on your target app, to include:
```text
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 your service is online, but responds with a status code that is not in the 2xx range, then you can use `statusCheckAcceptCodes` to set an accepted status code.
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.
Running Dashy in HOST network mode, instead of BRIDGE will allow status check access to other services in HOST mode. For more info, see [#445](https://github.com/Lissy93/dashy/discussions/445).
If you have firewall rules configured, then ensure that they don't prevent Dashy from making requests to the other services you are trying to access.
Currently, the status check needs a page to be rendered, so if this URL in your browser does not return anything, then status checks will not work. This may be modified in the future, but in the meantime, a fix would be to make your own status service, which just checks if your app responds with whatever code you'd like, and then return a 200 plus renders an arbitrary message. Then just point `statusCheckUrl` to your custom page.
For further troubleshooting, use an application like [Postman](https://postman.com) to diagnose the issue. Set the parameter to `GET`, and then make a call to: `https://[url-of-dashy]/status-check/?&url=[service-url]`. Where the service URL must have first been encoded (e.g. with `encodeURIComponent()` or [urlencoder.io](https://www.urlencoder.io/))
If you're serving Dashy though a CDN, instead of using the Node server or Docker image, then the Node endpoint that makes requests will not be available to you, and all requests will fail. A workaround for this may be implemented in the future, but in the meantime, your only option is to use the Docker or Node deployment method.
## How it Works
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.
# Status Indicators
Dashy has an optional feature that can display a small icon next to each of your running services, indicating it's current status. This can be useful if you are using Dashy as your homelab's start page, as it gives you an overview of the health of each of your running services. The status feature will show response time, response code, online/ offline check and if applicable, a relevant error message.
<p align="center">
<img width="800" src="/docs/assets/status-check-demo.gif" />
</p>
## Enabling Status Indicators
By default, this feature is off. If you do not want this feature, just don't add the `statusCheck` to your conf.yml file, then no requests will be made.
To enable status checks, you can either turn it on for all items, by setting `appConfig.statusCheck: true`, like:
```yaml
appConfig:
statusCheck: true
```
Or you can enable/ disable it on a per-item basis, with the `item[n].statusCheck` attribute
```yaml
sections:
- name: Firewall
items:
- title: OPNsense
description: Firewall Central Management
icon: networking/opnsense.png
url: https://192.168.1.1
statusCheck: false
- title: MalTrail
description: Malicious traffic detection system
icon: networking/maltrail.png
url: http://192.168.1.1:8338
statusCheck: true
- title: Ntopng
description: Network traffic probe and network use monitor
icon: networking/ntop.png
url: http://192.168.1.1:3001
statusCheck: true
```
## Continuous Checking
By default, with status indicators enabled Dashy will check an applications status on page load, and will not keep indicators updated. This is usually desirable behavior. However, if you do want the status indicators to continue to poll your running services, this can be enabled by setting the `statusCheckInterval` attribute. Here you define an interval as an integer in seconds, and Dashy will poll your apps every x seconds. Note that if this number is very low (below 5 seconds), you may notice the app running slightly slower.
The following example, will instruct Dashy to continuously check the status of your services every 20 seconds.
```text
appConfig:
statusCheck: true
statusCheckInterval: 20
```
## Using a Different Endpoint
By default, the status checker will use the URL of each application being checked. In some situations, you may want to use a different endpoint for status checking. Similarly, some services provide a dedicated path for uptime monitoring.
You can set the `statusCheckUrl` property on any given item in order to do this. The status checker will then ping that endpoint, instead of the apps main `url` property.
## Setting Custom Headers
If your service is responding with an error, despite being up and running, it is most likely because custom headers for authentication, authorization or encoding are required. You can define these headers under the `statusCheckHeaders` property for any service. It should be defined as an object format, with the name of header as the key, and header content as the value.
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`
## Allowing Alternative Status Codes
If you expect your service to return a status code that is not in the 2XX range, and still want the indicator to be green, then you can specify an expected status code under `statusCheckAcceptCodes` for a given item. For example, `statusCheckAcceptCodes: '403,418'`
## Troubleshooting Failing Status Checks
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 [above](#setting-custom-headers).
If you are still having issues, it may be because your target application is blocking requests from Dashy's IP. This is a [CORS error](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS), and can be fixed by setting the headers on your target app, to include:
```text
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 your service is online, but responds with a status code that is not in the 2xx range, then you can use `statusCheckAcceptCodes` to set an accepted status code.
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.
Running Dashy in HOST network mode, instead of BRIDGE will allow status check access to other services in HOST mode. For more info, see [#445](https://github.com/Lissy93/dashy/discussions/445).
If you have firewall rules configured, then ensure that they don't prevent Dashy from making requests to the other services you are trying to access.
Currently, the status check needs a page to be rendered, so if this URL in your browser does not return anything, then status checks will not work. This may be modified in the future, but in the meantime, a fix would be to make your own status service, which just checks if your app responds with whatever code you'd like, and then return a 200 plus renders an arbitrary message. Then just point `statusCheckUrl` to your custom page.
For further troubleshooting, use an application like [Postman](https://postman.com) to diagnose the issue. Set the parameter to `GET`, and then make a call to: `https://[url-of-dashy]/status-check/?&url=[service-url]`. Where the service URL must have first been encoded (e.g. with `encodeURIComponent()` or [urlencoder.io](https://www.urlencoder.io/))
If you're serving Dashy though a CDN, instead of using the Node server or Docker image, then the Node endpoint that makes requests will not be available to you, and all requests will fail. A workaround for this may be implemented in the future, but in the meantime, your only option is to use the Docker or Node deployment method.
## How it Works
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.

398
docs/theming.md
View File

@ -1,199 +1,199 @@
# Theming
By default Dashy comes with 25+ built-in themes, which can be applied from the dropdown menu in the UI.
![Built-in Themes](https://i.ibb.co/GV3wRss/Dashy-Themes.png)
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](https://developer.mozilla.org/en-US/docs/Learn/CSS/First_steps) 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:
```yaml
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](https://github.com/Lissy93/dashy/blob/master/src/styles/color-themes.scss).
```css
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](#css-variables).
<p align="center">
<a href="https://i.ibb.co/cLDXj1R/dashy-theme-configurator.gif">
<img alt="Example Themes" src="https://raw.githubusercontent.com/Lissy93/dashy/master/docs/assets/theme-config-demo.gif" width="400" />
</a>
</p>
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.
```yaml
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.
## Page-Specific Styles
If you've got multiple pages within your dashboard, you can choose to target certain styles to specific pages. The top-most element within `<body>` will have a class name specific to the current sub-page. This is usually the page's name, all lowercase, with dashes instead of spaces, but you can easily check this yourself within the dev tools.
For example, if the pages name was "CFT Toolbox", and you wanted to target `.item`s, you would do:
```css
.cft-toolbox .item { border: 4px solid yellow; }
```
## Loading External Stylesheets
The URI of a stylesheet, either local or hosted on a remote CDN can be passed into the config file. The attribute `appConfig.externalStyleSheet` accepts either a string, or an array of strings. You can also pass custom font stylesheets here, they must be in a CSS format (for example, `https://fonts.googleapis.com/css2?family=Cutive+Mono`).
This is handled in [`ThemeHelper.js`](https://github.com/Lissy93/dashy/blob/master/src/utils/ThemeHelper.js).
For example:
```yaml
appConfig:
externalStyleSheet: 'https://example.com/my-stylesheet.css'
```
```yaml
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`](https://github.com/Lissy93/dashy/blob/master/src/styles/color-palette.scss) and the themes which make use of these color variables are specified in [`color-themes.scss`](https://github.com/Lissy93/dashy/blob/master/src/styles/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](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties).
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](https://developer.mozilla.org/en-US/docs/Learn/Common_questions/What_are_browser_developer_tools), and these articles on [selecting elements](https://developer.mozilla.org/en-US/docs/Tools/Page_Inspector/How_to/Select_an_element) and [inspecting and modifying colors](https://developer.mozilla.org/en-US/docs/Tools/Page_Inspector/How_to/Inspect_and_select_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](https://developer.mozilla.org/en-US/docs/Web/CSS/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`
# Theming
By default Dashy comes with 25+ built-in themes, which can be applied from the dropdown menu in the UI.
![Built-in Themes](https://i.ibb.co/GV3wRss/Dashy-Themes.png)
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](https://developer.mozilla.org/en-US/docs/Learn/CSS/First_steps) 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:
```yaml
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](https://github.com/Lissy93/dashy/blob/master/src/styles/color-themes.scss).
```css
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](#css-variables).
<p align="center">
<a href="https://i.ibb.co/cLDXj1R/dashy-theme-configurator.gif">
<img alt="Example Themes" src="https://raw.githubusercontent.com/Lissy93/dashy/master/docs/assets/theme-config-demo.gif" width="400" />
</a>
</p>
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.
```yaml
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.
## Page-Specific Styles
If you've got multiple pages within your dashboard, you can choose to target certain styles to specific pages. The top-most element within `<body>` will have a class name specific to the current sub-page. This is usually the page's name, all lowercase, with dashes instead of spaces, but you can easily check this yourself within the dev tools.
For example, if the pages name was "CFT Toolbox", and you wanted to target `.item`s, you would do:
```css
.cft-toolbox .item { border: 4px solid yellow; }
```
## Loading External Stylesheets
The URI of a stylesheet, either local or hosted on a remote CDN can be passed into the config file. The attribute `appConfig.externalStyleSheet` accepts either a string, or an array of strings. You can also pass custom font stylesheets here, they must be in a CSS format (for example, `https://fonts.googleapis.com/css2?family=Cutive+Mono`).
This is handled in [`ThemeHelper.js`](https://github.com/Lissy93/dashy/blob/master/src/utils/ThemeHelper.js).
For example:
```yaml
appConfig:
externalStyleSheet: 'https://example.com/my-stylesheet.css'
```
```yaml
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`](https://github.com/Lissy93/dashy/blob/master/src/styles/color-palette.scss) and the themes which make use of these color variables are specified in [`color-themes.scss`](https://github.com/Lissy93/dashy/blob/master/src/styles/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](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties).
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](https://developer.mozilla.org/en-US/docs/Learn/Common_questions/What_are_browser_developer_tools), and these articles on [selecting elements](https://developer.mozilla.org/en-US/docs/Tools/Page_Inspector/How_to/Select_an_element) and [inspecting and modifying colors](https://developer.mozilla.org/en-US/docs/Tools/Page_Inspector/How_to/Inspect_and_select_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](https://developer.mozilla.org/en-US/docs/Web/CSS/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`

1274
docs/troubleshooting.md
View File

File diff suppressed because it is too large Load Diff

142
docs/widgets.md
View File

@ -35,9 +35,11 @@ Dashy has support for displaying dynamic content in the form of widgets. There a
- [GitHub Trending](#github-trending)
- [GitHub Profile Stats](#github-profile-stats)
- [Healthchecks Status](#healthchecks-status)
- [Hackernews Trending](#hackernews-trending)
- [Mvg Departure](#mvg-departure)
- [Mvg Connection](#mvg-connection)
- [Custom search](#custom-search)
- [Rescuetime overview](#rescuetime-overview)
- **[Self-Hosted Services Widgets](#self-hosted-services-widgets)**
- [System Info](#system-info)
- [Cron Monitoring](#cron-monitoring-health-checks)
@ -149,6 +151,8 @@ A simple, live-updating local weather component, showing temperature, conditions
**`city`** | `string` | Required | A city name to use for fetching weather. This can also be a state code or country code, following the ISO-3166 format
**`units`** | `string` | _Optional_ | The units to use for displaying data, can be either `metric` or `imperial`. Defaults to `metric`
**`hideDetails`** | `boolean` | _Optional_ | If set to `true`, the additional details (wind, humidity, pressure, etc) will not be shown. Defaults to `false`
**`lat`** | `number` | _Optional_ | To show weather for a specific location, you can provide the latitude and longitude coordinates. If provided, this will override the `city` option
**`lon`** | `number` | _Optional_ | To show weather for a specific location, you can provide the latitude and longitude coordinates. If provided, this will override the `city` option
#### Example
@ -158,7 +162,7 @@ A simple, live-updating local weather component, showing temperature, conditions
apiKey: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
city: London
units: metric
hideDetails: false
hideDetails: true
```
#### Info
@ -699,6 +703,8 @@ Display current FX rates in your native currency. Hover over a row to view more
Counting down to the next day off work? This widget displays upcoming public holidays for your country. Data is fetched from [Enrico](http://kayaposoft.com/enrico/)
Note, config for this widget is case-sensetive (see [#1268](https://github.com/Lissy93/dashy/issues/1268))
<p align="center"><img width="400" src="https://i.ibb.co/VC6fZqn/public-holidays.png" /></p>
#### Options
@ -709,6 +715,7 @@ Counting down to the next day off work? This widget displays upcoming public hol
**`state`** | `string` | **Optional** | restrict a country to a specific state defined by [ISO_3166-2](https://en.wikipedia.org/wiki/ISO_3166-2), e.g. `LND`.
**`holidayType`** | `string` | **Optional** | The type of holidays to fetch. Can be: `all`, `public_holiday`, `observance`, `school_holiday`, `other_day` or `extra_working_day`. Defaults to `public_holiday`
**`monthsToShow`** | `number` | **Optional** | The number of months in advance to show. Min: `1`, max: `24`. Defaults to `12`
**`lang`** | `string` | **Optional** | The language in which the events should be. Usually local languages and english are available. Default to first available in the country. e.g. `en` or `fr`.
#### Example
@ -719,6 +726,7 @@ Counting down to the next day off work? This widget displays upcoming public hol
region: LND
holidayType: all
monthsToShow: 12
lang: en
```
#### Info
@ -1150,7 +1158,7 @@ Display stats from your GitHub profile, using embedded cards from [anuraghazra/g
### HealthChecks Status
Display status of one or more HealthChecks project(s). Works with healthcheck.io and your selfhosted instance.
Display status of one or more HealthChecks project(s). Works with healthchecks.io and your selfhosted instance.
<p align="center"><img width="380" src="https://i.ibb.co/W5dP6VN/Bildschirm-foto-2023-01-07-um-11-07-11.png" /></p>
@ -1180,6 +1188,27 @@ Display status of one or more HealthChecks project(s). Works with healthcheck.io
---
### Hackernews Trending
Display new and trending Posts from Hackernews
#### Options
**Field** | **Type** | **Required** | **Description**
--- | --- | --- | ---
**`stories`** | `string` | _Optional_ | HN Stories to display defaults to `topstories`. Options are: `beststories`, `topstories` or `newstories`
**`limit`** | `int` | _Optional_ | The size of the list of Posts to show.
##### Example
```yaml
- type: hackernews-trending
options:
stories: newstories
limit: 10
```
---
### MVG Departure
Display departure time of a MVG (Münchner Verkehrs Gesellschaft) station.
@ -1315,6 +1344,38 @@ This widget allows searching multiple search engines from dashy.
---
### RescueTime Overview
Show an overview of how you have spent your time for the current day.
<p align="center"><img width="400" src="https://i.ibb.co/bvx3PQM/rescuetime.png" /></p>
#### Options
**Field** | **Type** | **Required** | **Description**
--- | --- | --- | ---
**`apiKey`** | `string` | required | The API-Key generated in the RescueTime UI.
#### Example
```yaml
- type: rescue-time
useProxy: true
options:
apiKey: abcdefghijkl_mnop
```
#### Info
- **CORS**: 🟢 Required
- **Auth**: 🔴 Required
- **Price**: 🟠 Depends on user subscription
- **Host**: [RescueTime](https://www.rescuetime.com)
- **Privacy**: _See [RescueTime Privacy](https://www.rescuetime.com/privacy)_
---
## Self-Hosted Services Widgets
@ -1897,7 +1958,7 @@ Displays your notifications and allows deleting them.
#### Example
```yaml
- type: nextcloud-userstatus
- type: nextcloud-notifications
useProxy: true
options:
hostname: https://nextcloud.example.com
@ -2003,7 +2064,7 @@ Shows statistics about PHP OPcache performance on your Nextcloud server.
#### Example
```yaml
- type: nextcloud-stats
- type: nextcloud-php-opcache
useProxy: true
options:
hostname: https://nextcloud.example.com
@ -2069,6 +2130,11 @@ This will show the list of VMs, with a title and a linked fotter, hiding VM temp
footer_as_link: true
hide_templates: 1
```
#### Troubleshooting
- **404 Error in development mode**: The error might disappear in production mode `yarn start`
- **500 Error in production mode**: Try adding the certificate authority (CA) certificate of your Proxmox host to Node.js.
- Download the Proxmox CA certificate to your Dashy host.
- Export environment variable `NODE_EXTRA_CA_CERTS` and set its value to the path of the downloaded CA certificate. Example: `export NODE_EXTRA_CA_CERTS=/usr/local/share/ca-certificates/devlab_ca.pem`
#### Info
- **CORS**: 🟠 Proxied
@ -2193,7 +2259,7 @@ Linkding is a self-hosted bookmarking service, which has a clean interface and i
**Field** | **Type** | **Required** | **Description**
--- | --- | --- | ---
**`host`** | `string` | Required | The hostname of the Drone CI instance.
**`apiKey`** | `string` | Required | The API key (https://[your-linkding-instance]/settings/integrations).
**`apiKey`** | `string` | Required | The API key (https://your-linkding-instance/settings/integrations).
**`tags`** | `list of string` | _Optional_ | Filter the links by tag.
#### Example
@ -2228,8 +2294,28 @@ Glances is a cross-platform monitoring tool developed by [@nicolargo](https://gi
If you don't already have it installed, either follow the [Installation Guide](https://github.com/nicolargo/glances/blob/master/README.rst) for your system, or setup [with Docker](https://glances.readthedocs.io/en/latest/docker.html), or use the one-line install script: `curl -L https://bit.ly/glances | /bin/bash`.
If you are using Docker to run glances make sure to add the enviroment variable `-e TZ = {YourTimeZone}`. You can get a list of valid timezones by running `timedatectl list-timezones` on any linux system. This is needed so the graphs show the currect time.
Here an example for Docker
```
docker run -d \
--name glances \
--restart unless-stopped \
-v /var/run/docker.sock:/var/run/docker.sock:ro \
-p 61208:61208 \
--pid host \
--privileged \
-e GLANCES_OPT=-w \
-e PUID=1000 \
-e PGID=1000 \
-e TZ=Europe/Zurich \
nicolargo/glances:latest
```
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](https://glances.readthedocs.io/en/latest/cmds.html) for more info.
If Glaces is running on a Windows system it is recommanded to add the following arguments ```--disable-plugin all --enable-plugin cpu,mem,diskio,ip,network,containers,quicklook,load,fs,alert -w``` This is due to Glances not being that stable on windows, so disabling all plugins that aren't used by Dashy widgets can save on ressources.
#### Options
All Glance's based widgets require a `hostname`. All other parameters are optional.
@ -2274,6 +2360,22 @@ Live-updating current CPU usage, as a combined average across all cores
---
### Current CPU Usage Speedometer
Speedometer styled version of the Current CPU Usage widget
<p align="center"><img width="400" src="https://i.ibb.co/7RHTRNq/gl-cpu-speedometer.png" /></p>
#### Example
```yaml
- type: gl-cpu-speedometer
options:
hostname: http://192.168.130.2:61208
```
---
### CPU Usage Per Core
Live-updating CPU usage breakdown per core
@ -2329,6 +2431,22 @@ Real-time memory usage gauge, with more info visible on click
---
### Current Memory Usage Speedometer
Speedometer styled version of the Current Memory Usage widget
<p align="center"><img width="400" src="https://i.ibb.co/wsNW7Xr/gl-mem-speedometer.png" /></p>
#### Example
```yaml
- type: gl-mem-speedometer
options:
hostname: http://192.168.130.2:61208
```
---
### Memory Usage History
Recent memory usage chart
@ -2755,7 +2873,7 @@ Widgets use the following color variables, which can be overridden if desired:
- `--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](/docs/themingsetting-custom-css-in-the-ui)
For more info on how to apply custom variables, see the [Theming Docs](/docs/theming#setting-custom-css-in-the-ui)
---
@ -2791,7 +2909,7 @@ Widgets can be opened in full-page view, by clicking the Arrow icon (top-right).
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](/docs/configuringsection) 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.
All [config options](/docs/configuring#section) 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](https://github.com/coder/code-server), or just SSH into your box and edit the conf.yml file directly.
@ -2801,7 +2919,7 @@ Widgets cannot currently be edited through the UI. This feature is in developmen
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](/docs/development-guidesbuilding-a-widget), or take a look at [here](https://github.com/Lissy93/dashy/commit/3da76ce2999f57f76a97454c0276301e39957b8e) for a code example.
For a full tutorial on creating your own widget, you can follow [this guide](/docs/development-guides/#building-a-widget), or take a look at [here](https://github.com/Lissy93/dashy/commit/3da76ce2999f57f76a97454c0276301e39957b8e) for a code example.
Alternatively, for displaying simple data, you could also just use the either the [iframe](#iframe-widget), [embed](#html-embedded-widget), [data feed](#data-feed) or [API response](#api-response) widgets.
@ -2819,15 +2937,15 @@ Please only request widgets for services that:
- Allow for use in their Terms of Service
- Would be useful for other users
You can suggest a widget [here](https://git.io/Jygo3), please star the repo before submitting a ticket. If you are a monthly GitHub sponsor, I will happily build out a custom widget for any service that meets the above criteria, usually 2 within weeks of initial request.
You can suggest a widget [here](https://git.io/Jygo3), please star the repo before submitting a ticket. If you are a monthly GitHub sponsor, I will happily build out a custom widget for any service that meets the above criteria, usually within 2 weeks of initial request.
For services that are not officially supported, it is likely still possible to display data using either the [iframe](#iframe-widget), [embed](#html-embedded-widget) or [API response](#api-response) widgets. For more advanced features, like charts and action buttons, you could also build your own widget, using [this tutorial](/docs/development-guidesbuilding-a-widget), it's fairly straight forward, and you can use an [existing widget](https://github.com/Lissy93/dashy/tree/master/src/components/Widgets) (or [this example](https://git.io/JygKI)) as a template.
For services that are not officially supported, it is likely still possible to display data using either the [iframe](#iframe-widget), [embed](#html-embedded-widget) or [API response](#api-response) widgets. For more advanced features, like charts and action buttons, you could also build your own widget, using [this tutorial](/docs/development-guides/#building-a-widget), it's fairly straight forward, and you can use an [existing widget](https://github.com/Lissy93/dashy/tree/master/src/components/Widgets) (or [this example](https://git.io/JygKI)) 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 adequately explain the problem, then you can [open the browser console](/docs/troubleshootinghow-to-open-browser-console) to see more details.
If an error occurs when fetching or rendering results, you will see a short message in the UI. If that message doesn't adequately explain the problem, then you can [open the browser console](/docs/troubleshooting#how-to-open-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.
@ -2872,4 +2990,4 @@ For testing purposes, you can use an addon, which will disable the CORS checks.
### Raising an Issue
If you need to submit a bug report for a failing widget, then please include the full console output (see [how](/docs/troubleshootinghow-to-open-browser-console)) 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.
If you need to submit a bug report for a failing widget, then please include the full console output (see [how](/docs/troubleshooting#how-to-open-browser-console)) 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.