mirror of
https://github.com/Lissy93/dashy.git
synced 2024-11-26 12:55:42 +03:00
📝 Refactors loads of docs
⚰️ Death by Documentation
This commit is contained in:
Alicia Sykes
parent
6cc711ae23
commit
4278764101
@ -1,10 +1,16 @@
|
||||
# Alternate Views & Opening Methods
|
||||
|
||||
## Views
|
||||
As well as the default start view, Dashy has several other start pages, for different tasks. You can switch views with the view-switcher button in the top-right, or set a default starting view using the `appConfig.startingView` attribute (can be `default`, `minimal` or `workspace`).
|
||||
|
||||
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 and items will be visible, you can modify settings and search + launch your applications.
|
||||
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>
|
||||
@ -12,11 +18,11 @@ This is the main page that you will land on when you first launch the applicatio
|
||||
</p>
|
||||
|
||||
### Workspace
|
||||
The workspace view displays your links in a sidebar on the left-hand side, and apps are launched within Dashy. This enables you to use all of your self-hosted apps from one place, and makes multi-tasking easy.
|
||||
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.
|
||||
|
||||
In the workspace view, you can 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 your apps.
|
||||
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 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>
|
||||
@ -24,7 +30,7 @@ You can also specify a default app to be opened when you land on the workspace,
|
||||
</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.
|
||||
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>
|
||||
@ -33,7 +39,7 @@ The minimal view aims to be super fast and simple, and can be used as a browser
|
||||
|
||||
## Opening Methods
|
||||
|
||||
Dashy supports several different ways to launch your apps. The default opening method for each app can be specified using the `target` attribute, with a value of one of the following:
|
||||
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
|
||||
@ -41,12 +47,14 @@ Dashy supports several different ways to launch your apps. The default opening m
|
||||
- `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 the 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.
|
||||
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: Alt + Click will open the modal, and Ctrl + Click will open in a new tab. You can also right-click on any item to see all options (as seen in the screenshot below). This custom context menu can be disabled by setting `appConfig.disableContextMenu: true`.
|
||||
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.md#refused-to-connect-in-modal-or-workspace-view).
|
||||
|
||||
@ -161,7 +161,7 @@ For more info, see the **[Authentication Docs](/docs/authentication.md)**
|
||||
**`hideHeading`** | `boolean` | _Optional_ | If set to `true`, the page title & sub-title will not be visible. Defaults to `false`
|
||||
**`hideNav`** | `boolean` | _Optional_ | If set to `true`, the navigation menu will not be visible. Defaults to `false`
|
||||
**`hideSearch`** | `boolean` | _Optional_ | If set to `true`, the search bar will not be visible. Defaults to `false`
|
||||
**`hideSettings`** | `boolean` | _Optional_ | If set to `true`, the settings menu will not be visible. Defaults to `false`
|
||||
**`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](#configuring)**
|
||||
@ -216,7 +216,8 @@ For more info, see the **[Authentication Docs](/docs/authentication.md)**
|
||||
**Field** | **Type** | **Required**| **Description**
|
||||
--- | --- | --- | ---
|
||||
**`sortBy`** | `string` | _Optional_ | The sort order for items within the current section. By default items are displayed in the order in which they are listed in within the config. The following sort options are supported: `most-used` (most opened apps first), `last-used` (the most recently used apps), `alphabetical`, `reverse-alphabetical`, `random` and `default`
|
||||
**`collapsed`** | `boolean` | _Optional_ | If true, the section will be collapsed initially, and will need to be clicked to open. Useful for less regularly used, or very long sections. Defaults to `false`
|
||||
**`collapsed`** | `boolean` | _Optional_ | If true, the section will be collapsed initially, and will need to be clicked to open. Useful for less regularly used, or very long sections. Defaults to `false`
|
||||
**`cutToHeight`** | `boolean` | _Optional_ | By default, sections will fill available space. Set this option to true to match section height with content height
|
||||
**`rows`** | `number` | _Optional_ | Height of the section, specified as the number of rows it should span vertically, e.g. `2`. Defaults to `1`. Max is `5`.
|
||||
**`cols`** | `number` | _Optional_ | Width of the section, specified as the number of columns the section should span horizontally, e.g. `2`. Defaults to `1`. Max is `5`.
|
||||
**`itemSize`** | `string` | _Optional_ | Specify the size for items within this group, either `small`, `medium` or `large`. Note that this will overide any settings specified through the UI
|
||||
@ -237,7 +238,7 @@ For more info, see the **[Authentication Docs](/docs/authentication.md)**
|
||||
|
||||
**Field** | **Type** | **Required**| **Description**
|
||||
--- | --- | --- | ---
|
||||
**`icon`** | `string` | _Optional_ | The icon for a given item or section. See [Icon Docs](/docs/icons.md) for all available supported icon types. To auto-fetch icon from a services URL, aet to `favicon`. To use font-awesome, specify the category, followed by the icon name, e.g. `fas fa-rocket`, `fab fa-monero` or `fal fa-duck`. Similarly, for branded icons, you can use [simple-icons](https://simpleicons.org/) by setting icon to `si-[icon-name]` or [material-design-icons](https://dev.materialdesignicons.com/icons) by setting icon to `mdi-[icon-name]`. If set to `generative`, then a unique icon is generated from the apps URL or IP. You can also use hosted any by specifying it's URL, e.g. `https://i.ibb.co/710B3Yc/space-invader-x256.png`. To use a local image, first store it in `./public/item-icons/` (or `-v /app/public/item-icons/` in Docker) , and reference it by name and extension - e.g. set `image.png` to use `./public/item-icon/image.png`, you can also use sub-folders if you have a lot of icons, to keep them organised.
|
||||
**`icon`** | `string` | _Optional_ | The icon for a given item or section. <br>See [Icon Docs](/docs/icons.md) 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](#configuring)**
|
||||
|
||||
@ -265,7 +266,7 @@ Config can be modified directly through the UI, and then written to disk, or app
|
||||
</a>
|
||||
<br>
|
||||
<a href="https://ibb.co/zRv542H">
|
||||
<b>Raw Editor</b><br>
|
||||
<b>JSON Editor</b><br>
|
||||
<img alt="Config Editor demo" src="https://raw.githubusercontent.com/Lissy93/dashy/master/docs/assets/config-editor-demo.gif" width="600" />
|
||||
</a>
|
||||
</p>
|
||||
|
||||
@ -1,14 +1,8 @@
|
||||
# Contributing
|
||||
|
||||
First off, thank you for considering contributing towards Dashy! 🙌
|
||||
There are several ways that you can help out (but don't feel you have to).
|
||||
Any contributions, however small will always be very much appreciated, and you will be appropriately credited in the readme - huge thank you to [everyone who has helped](/docs/credits.md) so far 💞
|
||||
|
||||
## Submit a PR
|
||||
Contributing to the code or documentation is super helpful. You can fix a bug, add a new feature or improve an existing one. I've written [several guides](https://github.com/Lissy93/dashy/blob/master/docs/development-guides.md) to help you get started. For setting up the development environment, outline of the standards, and understanding the PR flow, see the [Development Docs](https://github.com/Lissy93/dashy/blob/master/docs/development.md). I've tried to keep the code neat and documentation thorough, so understanding what everything does should be fairly straight forward, but feel free to ask if you have any questions.
|
||||
|
||||
## Add Translations
|
||||
If you speak another language, then adding translations would be really helpful, and you will be credited in the readme for your work. Multi-language support makes Dashy accessible for non-English speakers, which I feel is important. 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).
|
||||
There are several ways that you can help out, and any contributions, however small will always be very much appreciated.
|
||||
You will be appropriately credited in the readme - huge thank you to [everyone who has helped](/docs/credits.md) so far 💞
|
||||
|
||||
## Take a 2-minute survey
|
||||
Help improve Dashy by taking a very short, 6-question survey. This will give me a better understanding of what is important to you, so that I can make Dashy better in the future :)
|
||||
@ -16,51 +10,18 @@ Help improve Dashy by taking a very short, 6-question survey. This will give me
|
||||
[](https://survey.typeform.com/to/gl0L68ou)
|
||||
|
||||
## Share your dashboard
|
||||
Dashy now has a [Showcase](https://github.com/Lissy93/dashy/blob/master/docs/showcase.md#dashy-showcase-) where you can show off a screenshot of your dashboard, and get inspiration from other users. I also really enjoy seeing how people are using Dashy. To [submit your dashboard](https://github.com/Lissy93/dashy/blob/master/docs/showcase.md#submitting-your-dashboard), please either open a PR or raise an issue.
|
||||
Dashy now has a [Showcase](https://github.com/Lissy93/dashy/blob/master/docs/showcase.md#dashy-showcase-) where you can show off a screenshot of your dashboard, and get inspiration from other users (and I really love seeing how people are using Dashy). To [submit your dashboard](https://github.com/Lissy93/dashy/blob/master/docs/showcase.md#submitting-your-dashboard), either open a PR or raise an issue.
|
||||
|
||||
## Improve the Docs
|
||||
Found a typo, or something that isn't as clear as it could be? Maybe I've missed something off altogether, or you hit a roadblock that took you a while to figure out. Submitting a pull request to add to or improve the documentation will help future users get Dashy up and running more easily.
|
||||
All content is located either in the [`./README.md`](/README.md) or [`/docs/`](/docs) directory, and synced to the Wiki and website using a GH [action](/actions/workflows/wiki-sync.yml).
|
||||
|
||||
## Raise a bug
|
||||
If you've found a bug, then please do raise it as an issue. This will help me know if there's something that needs fixing. Try and include as much detail as possible, such as your environment, steps to reproduce, any console output and maybe an example screenshot or recording if necessary.
|
||||
|
||||
[](https://github.com/Lissy93/dashy/issues/new?assignees=lissy93&labels=%F0%9F%90%9B+Bug&template=bug.yml&title=%5BBUG%5D+%3Ctitle%3E)
|
||||
|
||||
## Join the discussion
|
||||
I've enabled the discussion feature on GitHub, here you can share tips and tricks, useful information, or your dashboard. You can also ask questions, and offer basic support to other users.
|
||||
|
||||
[](https://github.com/Lissy93/dashy/discussions)
|
||||
|
||||
## Spread the word
|
||||
Dashy is still a relatively young project, and as such not many people know of it. It would be great to see more users, and so it would be awesome if you could consider sharing on social platforms.
|
||||
|
||||
[](https://mastodon.social/?text=Check%20out%20Dashy%2C%20the%20privacy-friendly%2C%20self-hosted%20startpage%20for%20organizing%20your%20life%3A%20https%3A%2F%2Fgithub.com%2FLissy93%2Fdashy%20-%20By%20%40lissy93%40mastodon.social)
|
||||
[](http://www.reddit.com/submit?url=https://github.com/Lissy93/dashy&title=Dashy%20-%20The%20self-hosted%20dashboard%20for%20your%20homelab%20%F0%9F%9A%80)
|
||||
[](https://twitter.com/intent/tweet?url=https://github.com/lissy93/dashy&text=Check%20out%20Dashy%20by%20@Lissy_Sykes,%20the%20self-hosted%20dashboard%20for%20your%20homelab%20%F0%9F%9A%80)
|
||||
[](https://www.facebook.com/sharer/sharer.php?u=https://github.com/lissy93/dashy)
|
||||
[](https://www.linkedin.com/shareArticle?mini=true&url=https://github.com/lissy93/dashy)
|
||||
[](https://pinterest.com/pin/create/button/?url=https://github.com/lissy93/dashy&media=https://raw.githubusercontent.com/Lissy93/dashy/master/docs/showcase/1-home-lab-material.png&description=Check%20out%20Dashy,%20the%20self-hosted%20dashboard%20for%20your%20homelab%20%F0%9F%9A%80)
|
||||
[](https://vk.com/share.php?url=https%3A%2F%2Fgithub.com%2Flissy93%2Fdashy%2F&title=Check%20out%20Dashy%20-%20The%20Self-Hosted%20Dashboard%20for%20your%20Homelab%20%F0%9F%9A%80)
|
||||
[](viber://forward?text=https%3A%2F%2Fgithub.com%2Flissy93%2Fdashy%0ACheck%20out%20Dashy%2C%20the%20self-hosted%20dashboard%20for%20your%20homelab%20%F0%9F%9A%80)
|
||||
[](https://t.me/share/url?url=https%3A%2F%2Fgithub.com%2Flissy93%2Fdashy&text=Check%20out%20Dashy%2C%20the%20self-hosted%20dashboard%20for%20your%20homelab%20%F0%9F%9A%80)
|
||||
[](mailto:info@example.com?&subject=Check%20out%20Dashy%20-%20The%20self-hosted%20dashboard%20for%20your%20homelab%20%F0%9F%9A%80&cc=&bcc=&body=https://github.com/lissy93/dashy)
|
||||
|
||||
## Star, Upvote or Leave a Review
|
||||
Dashy is on the following platforms, and if you could spare a few seconds to give it an upvote or review, this will also help new users find it.
|
||||
|
||||
[](https://www.producthunt.com/posts/dashy)
|
||||
[](https://alternativeto.net/software/dashy/about/)
|
||||
[](https://www.slant.co/improve/topics/27783/viewpoints/1/~self-hosted-homelab-startpage~dashy)
|
||||
[](https://github.com/Lissy93/dashy/stargazers)
|
||||
[](https://hub.docker.com/r/lissy93/dashy)
|
||||
[](https://github.com/Lissy93/dashy/issues/new?assignees=&labels=%F0%9F%92%AF+Showcase&template=showcase-addition.yml&title=%5BSHOWCASE%5D+%3Ctitle%3E)
|
||||
|
||||
## Make a small donation
|
||||
Please only do this is you can definitely afford to. Don't feel any pressure to donate anything, as Dashy and my other projects will always be 100% free, for everyone, for ever.
|
||||
|
||||
[](https://github.com/sponsors/Lissy93)
|
||||
Donations help to cover server costs, development time and caffeine ;)
|
||||
Don't feel any pressure to donate anything, as Dashy and my other projects will always be 100% free, for everyone, for ever.
|
||||
|
||||
Sponsoring will give you several perks, from $1 / £0.70 per month, as well as a sponsor badge on your profile, you can also be credited on the 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).
|
||||
[](https://github.com/sponsors/Lissy93)
|
||||
|
||||
Sponsoring will give you several perks - for $1 / £0.75 per month, you'll get a sponsor badge on your profile, be credited on the Dashy's readme, with a link to your website/ profile/ socials, get priority support, have your feature ideas implemented, plus lots more. For more info, see [@Lissy93's Sponsor Page](https://github.com/sponsors/Lissy93).
|
||||
|
||||
<details>
|
||||
<summary>You can also send a one-off small contribution using crypto</summary>
|
||||
@ -77,13 +38,9 @@ Sponsoring will give you several perks, from $1 / £0.70 per month, as well as a
|
||||
</p>
|
||||
</details>
|
||||
|
||||
## Request a feature via BountySource
|
||||
BountySource is a platform for sponsoring the development of certain features on open source projects. If there is a feature you'd like implemented into Dashy, but either isn't high enough priority or is deemed to be more work than it's worth, then you can instead contribute a bounty towards it's development. You won't pay a penny until your proposal is fully built, and you are satisfied with the result. This helps support the developers, and makes Dashy better for everyone.
|
||||
|
||||
[](https://www.bountysource.com/teams/dashy)
|
||||
|
||||
## Enable Anonymous Bug Reports
|
||||
[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). It 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.
|
||||
|
||||
Bug reports helps me to discover bugs I was unaware of, and then fix them, in order to make Dashy more reliable long term. This is a simple, yet really helpful step you can take to help improve Dashy. [Sentry](https://github.com/getsentry/sentry) is an open source error tracking and performance monitoring tool, which enables the identification any errors which occur in the production app (only if you enable it).
|
||||
|
||||
To enable error reporting:
|
||||
```yaml
|
||||
@ -91,7 +48,55 @@ appConfig:
|
||||
enableErrorReporting: true
|
||||
```
|
||||
|
||||
All reporting is **disabled** by default, and no data will ever be sent to any external endpoint without your explicit consent. In fact, the error tracking package will not even be imported unless you have actively enabled it. All statistics are anonomized and stored securely. For more about privacy and security, see the [Sentry Docs](https://sentry.io/security/).
|
||||
All reporting is **disabled** by default, and no data will ever be sent to any external endpoint without your explicit consent. All statistics are anonomized and stored securely. For more about privacy and security, see the [Sentry Security Docs](https://sentry.io/security/).
|
||||
|
||||
## Add Translations
|
||||
If you speak another language, then adding translations will help make Dashy available to non-native English speakers. This is a very quick and easy task, as all application text is located in [`locales/en.json`](https://github.com/Lissy93/dashy/blob/master/src/assets/locales/en.json), so adding a new language is as simple as copying this file and translating the values. You don't have to translate it all, as any missing attributes will just fallback to English. For a full tutorial, see the [Multi-Language Support Docs](https://github.com/Lissy93/dashy/blob/master/docs/multi-language-support.md).
|
||||
|
||||
## Submit a PR
|
||||
Contributing to the code or docs is super helpful. You can fix a bug, add a new feature or improve an existing one. If you've built your own custom widget, theme or view, consider sharing it in a PR. I've written [several guides](/docs/development-guides.md) to help you get started, and the steps for setting up the development environment are outlined in the [Development Docs](/docs/development.md). Feel free to ask if you have any questions.
|
||||
|
||||
## Improve the Docs
|
||||
Found a typo, or something that isn't as clear as it could be? Maybe I've missed something off altogether, or you hit a roadblock that took you a while to figure out. Submitting a pull request to add to or improve the documentation will help future users get Dashy up and running more easily.
|
||||
All content is located either in the [`./README.md`](/README.md) or [`/docs/`](/docs) directory, and synced to the Wiki and website using a GH [action](/actions/workflows/wiki-sync.yml).
|
||||
|
||||
## Raise a bug
|
||||
If you've found a bug, then please do raise it as an issue. This will help me know if there's something that needs fixing. Try and include as much detail as possible, such as your environment, steps to reproduce, any console output and maybe an example screenshot or recording if necessary.
|
||||
|
||||
[](https://github.com/Lissy93/dashy/issues/new?assignees=lissy93&labels=%F0%9F%90%9B+Bug&template=bug.yml&title=%5BBUG%5D+%3Ctitle%3E)
|
||||
|
||||
## Join the discussion
|
||||
I've enabled the discussion feature on GitHub, here you can share tips and tricks, useful information, or your dashboard. You can also ask questions, and offer basic support to other users.
|
||||
|
||||
[](https://github.com/Lissy93/dashy/discussions)
|
||||
|
||||
## Request a feature via BountySource
|
||||
BountySource is a platform for sponsoring the development of certain features on open source projects. If there is a feature you'd like implemented into Dashy, but either isn't high enough priority or is deemed to be more work than it's worth, then you can instead contribute a bounty towards it's development. You won't pay a penny until your proposal is fully built, and you are satisfied with the result. This helps support the developers, and makes Dashy better for everyone.
|
||||
|
||||
[](https://www.bountysource.com/teams/dashy)
|
||||
|
||||
## Spread the word
|
||||
Dashy is still a relatively young project, and as such not many people know of it. It would be great to see more users, and so it would be awesome if you could consider sharing with your friends or on social platforms.
|
||||
|
||||
[](https://mastodon.social/?text=Check%20out%20Dashy%2C%20the%20privacy-friendly%2C%20self-hosted%20startpage%20for%20organizing%20your%20life%3A%20https%3A%2F%2Fgithub.com%2FLissy93%2Fdashy%20-%20By%20%40lissy93%40mastodon.social)
|
||||
[](http://www.reddit.com/submit?url=https://github.com/Lissy93/dashy&title=Dashy%20-%20The%20self-hosted%20dashboard%20for%20your%20homelab%20%F0%9F%9A%80)
|
||||
[](https://twitter.com/intent/tweet?url=https://github.com/lissy93/dashy&text=Check%20out%20Dashy%20by%20@Lissy_Sykes,%20the%20self-hosted%20dashboard%20for%20your%20homelab%20%F0%9F%9A%80)
|
||||
[](https://www.facebook.com/sharer/sharer.php?u=https://github.com/lissy93/dashy)
|
||||
[](https://www.linkedin.com/shareArticle?mini=true&url=https://github.com/lissy93/dashy)
|
||||
[](https://pinterest.com/pin/create/button/?url=https://github.com/lissy93/dashy&media=https://raw.githubusercontent.com/Lissy93/dashy/master/docs/showcase/1-home-lab-material.png&description=Check%20out%20Dashy,%20the%20self-hosted%20dashboard%20for%20your%20homelab%20%F0%9F%9A%80)
|
||||
[](https://vk.com/share.php?url=https%3A%2F%2Fgithub.com%2Flissy93%2Fdashy%2F&title=Check%20out%20Dashy%20-%20The%20Self-Hosted%20Dashboard%20for%20your%20Homelab%20%F0%9F%9A%80)
|
||||
[](viber://forward?text=https%3A%2F%2Fgithub.com%2Flissy93%2Fdashy%0ACheck%20out%20Dashy%2C%20the%20self-hosted%20dashboard%20for%20your%20homelab%20%F0%9F%9A%80)
|
||||
[](https://t.me/share/url?url=https%3A%2F%2Fgithub.com%2Flissy93%2Fdashy&text=Check%20out%20Dashy%2C%20the%20self-hosted%20dashboard%20for%20your%20homelab%20%F0%9F%9A%80)
|
||||
[](mailto:info@example.com?&subject=Check%20out%20Dashy%20-%20The%20self-hosted%20dashboard%20for%20your%20homelab%20%F0%9F%9A%80&cc=&bcc=&body=https://github.com/lissy93/dashy)
|
||||
|
||||
## Star, Upvote or Leave a Review
|
||||
Dashy is on the following platforms, and if you could spare a few seconds to give it an upvote or review, this will also help new users discover Dashy
|
||||
|
||||
[](https://www.producthunt.com/posts/dashy)
|
||||
[](https://alternativeto.net/software/dashy/about/)
|
||||
[](https://www.slant.co/improve/topics/27783/viewpoints/1/~self-hosted-homelab-startpage~dashy)
|
||||
[](https://github.com/Lissy93/dashy/stargazers)
|
||||
[](https://hub.docker.com/r/lissy93/dashy)
|
||||
|
||||
## Follow for More
|
||||
If you've enjoyed Dashy, you can follow the me to get updates about other projects that I am working on.
|
||||
@ -100,11 +105,11 @@ If you've enjoyed Dashy, you can follow the me to get updates about other projec
|
||||
[](https://github.com/Lissy93)
|
||||
[](https://mastodon.social/web/accounts/1032965)
|
||||
[](https://keybase.io/aliciasykes)
|
||||
[](https://keybase.io/aliciasykes/pgp_keys.asc)
|
||||
[](https://aliciasykes.com)
|
||||
[](https://notes.aliciasykes.com/)
|
||||
[](https://keybase.io/aliciasykes/pgp_keys.asc)
|
||||
|
||||
If you like, you could also consider [subscribing to my mailing list](https://notes.aliciasykes.com/subscribe) for very occasional blog post updates.
|
||||
If you like, you could also consider [subscribing to my mailing list](https://notes.aliciasykes.com/subscribe) for occasional blog post updates.
|
||||
|
||||
---
|
||||
|
||||
|
||||
@ -320,6 +320,7 @@ At it's core, the application uses [**Vue.js**](https://github.com/vuejs/vue), a
|
||||
- [`axios`](https://github.com/axios/axios) - Promise based HTTP client by @mzabriskie and community `MIT`
|
||||
- [`ajv`](https://github.com/ajv-validator/ajv) - JSON schema Validator by @epoberezkin and community `MIT`
|
||||
- [`i18n`](https://github.com/kazupon/vue-i18n) - Internationalization plugin by @kazupon and community `MIT`
|
||||
- [`frappe-charts`](https://github.com/frappe/charts) - Lightweight charting library by @frappe `MIT`
|
||||
|
||||
#### Frontend Components
|
||||
- [`vue-select`](https://github.com/sagalbot/vue-select) - Dropdown component by @sagalbot `MIT`
|
||||
|
||||
@ -193,6 +193,7 @@ Styleguides:
|
||||
├── 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
|
||||
@ -214,6 +215,9 @@ Styleguides:
|
||||
│ ├── 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
|
||||
@ -225,15 +229,30 @@ Styleguides:
|
||||
│ │ ╰── 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
|
||||
│ │ ╰── Input.vue # Standard text field input 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
|
||||
│ │ ├── ContextMenu.vue # The right-click menu, for showing Item opening methods and info
|
||||
│ │ ├── 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
|
||||
@ -250,7 +269,10 @@ Styleguides:
|
||||
│ │ ├── 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
|
||||
│ │ ├── 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
|
||||
@ -266,6 +288,19 @@ Styleguides:
|
||||
├── 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
|
||||
|
||||
@ -257,12 +257,22 @@ import { widgetApiEndpoints } from '@/utils/defaults';
|
||||
export default {
|
||||
mixins: [WidgetMixin],
|
||||
data() {
|
||||
return {};
|
||||
return {
|
||||
results: null,
|
||||
};
|
||||
},
|
||||
computed: {
|
||||
endpoint() {
|
||||
return `${widgetApiEndpoints.myApi}/something`;
|
||||
},
|
||||
},
|
||||
computed: {},
|
||||
methods: {
|
||||
fetchData() {
|
||||
// TODO: Make Data Request
|
||||
this.makeRequest(this.endpoint).then(this.processData);
|
||||
},
|
||||
processData(data) {
|
||||
// Do processing any here, and set component data
|
||||
this.results = data;
|
||||
},
|
||||
},
|
||||
};
|
||||
@ -333,16 +343,7 @@ Under the `methods` block, we'll create a function called `fetchData`, here we c
|
||||
|
||||
```javascript
|
||||
fetchData() {
|
||||
axios.get(this.endpoint)
|
||||
.then((response) => {
|
||||
this.processData(response.data);
|
||||
})
|
||||
.catch((dataFetchError) => {
|
||||
this.error('Unable to fetch data', dataFetchError);
|
||||
})
|
||||
.finally(() => {
|
||||
this.finishLoading();
|
||||
});
|
||||
this.makeRequest(this.endpoint, this.headers).then(this.processData);
|
||||
},
|
||||
```
|
||||
|
||||
|
||||
@ -1,5 +1,7 @@
|
||||
# Privacy & Security
|
||||
Dashy was built with privacy in mind. Self-hosting your own apps and services is a great way to protect yourself from the mass data collection employed by big tech companies, and Dashy was designed to keep your local services organized and accessible from a single place.
|
||||
|
||||
Dashy was built with privacy in mind.
|
||||
Self-hosting your own apps and services is a great way to protect yourself from the mass data collection employed by big tech companies, and Dashy was designed to keep your local services organized and accessible from a single place.
|
||||
|
||||
It's fully open source, and I've tried to keep to code as clear and thoroughly documented as possible, which will make it easy for you to understand exactly how it works, and what goes on behind the scenes.
|
||||
|
||||
@ -8,7 +10,7 @@ For privacy and security tips, check out another project of mine: **[Personal Se
|
||||
---
|
||||
|
||||
## External Requests
|
||||
By default, Dashy will not make any external requests, unless you configure it to. Some features (which are all off by default) do require internat access, and this section outlines those features, the services used, and links to their privacy policies.
|
||||
By default, Dashy will not make any external requests, unless you configure it to. Some features (which are off by default) do require internat access, and this section outlines those features, the services used, and links to their privacy policies.
|
||||
|
||||
### Font Awesome
|
||||
If either any of your sections or items are using font-awesome icons, then these will be fetched directly from font-awesome on page load. See the [Font Awesome Privacy Policy](https://fontawesome.com/privacy) for more info.
|
||||
@ -43,6 +45,8 @@ Enabling anonymous error reporting helps me to discover bugs I was unaware of, a
|
||||
|
||||
If you need to monitor bugs yourself, then you can [self-host your own Sentry Server](https://develop.sentry.dev/self-hosted/), and use it by setting `appConfig.sentryDsn` to your Sentry instances [Data Source Name](https://docs.sentry.io/product/sentry-basics/dsn-explainer/), then just enable error reporting in Dashy.
|
||||
|
||||
### Widgets
|
||||
|
||||
---
|
||||
|
||||
## Local Storage
|
||||
@ -79,7 +83,7 @@ As with most web projects, Dashy relies on several [dependencies](https://github
|
||||
|
||||
Dependencies can introduce security vulnerabilities, but since all these packages are open source any issues are usually very quickly spotted. Dashy is using Snyk for dependency security monitoring, and you can see [the latest report here](https://snyk.io/test/github/lissy93/dashy). If any issue is detected by Snyk, a note about it will appear at the top of the Reamde, and will usually be fixed within 48 hours.
|
||||
|
||||
Note that packages listed under `deDependencies` section are only used for building the project, and are not included in the production environment.
|
||||
Note that packages listed under `devDependencies` section are only used for building the project, and are not included in the production environment.
|
||||
|
||||
---
|
||||
|
||||
|
||||
@ -62,6 +62,13 @@
|
||||
|
||||
---
|
||||
|
||||
### System Monitor
|
||||
> An aggregated board for monitoring system resource usage from a single view
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
### CFT Toolbox
|
||||
|
||||
|
||||
@ -112,10 +119,10 @@
|
||||
|
||||
---
|
||||
|
||||
### System Monitor
|
||||
> An aggregated board for monitoring system resource usage from a single view
|
||||
### Morning Dashboard
|
||||
> Displayed on my smart screen between 05:00 - 08:00, and includes all the info that I usually check before leaving for work
|
||||
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
|
||||
@ -1,6 +1,29 @@
|
||||
# Troubleshooting
|
||||
|
||||
This document contains common problems and their solutions.
|
||||
> _**This document contains common problems and their solutions.**_
|
||||
>
|
||||
> _If you came across an issue where the solution was not immediately obvious, consider adding it to this list to help other users._
|
||||
|
||||
### Contents
|
||||
- [Refused to Connect in Web Content View](#refused-to-connect-in-modal-or-workspace-view)
|
||||
- [404 On Static Hosting](#404-on-static-hosting)
|
||||
- [Yarn Build or Run Error](#yarn-error)
|
||||
- [Auth Validation Error: "should be object"](#auth-validation-error-should-be-object)
|
||||
- [Config Not Updating](#config-not-updating)
|
||||
- [Config Still not Updating](#config-still-not-updating)
|
||||
- [Styles and Assets not Updating](#styles-and-assets-not-updating)
|
||||
- [DockerHub toomanyrequests](#dockerhub-toomanyrequests)
|
||||
- [Config Validation Errors](#config-validation-errors)
|
||||
- [Node Sass unsupported environment](#node-sass-does-not-yet-support-your-current-environment)
|
||||
- [Cannot find module './_baseValues'](#error-cannot-find-module-_basevalues)
|
||||
- [Ngrok Invalid Host Headers](#invalid-host-header-while-running-through-ngrok)
|
||||
- [Warnings in the Console during deploy](#warnings-in-the-console-during-deploy)
|
||||
- [Docker Login Fails on Ubuntu](#docker-login-fails-on-ubuntu)
|
||||
- [Status Checks Failing](#status-checks-failing)
|
||||
- [How-To Open Browser Console](#how-to-open-browser-console)
|
||||
- [Git Contributions not Displaying](#git-contributions-not-displaying)
|
||||
|
||||
---
|
||||
## `Refused to Connect` in Modal or Workspace View
|
||||
|
||||
This is not an issue with Dashy, but instead caused by the target app preventing direct access through embedded elements. It can be fixed by setting the [`X-Frame-Options`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Frame-Options) HTTP header set to `ALLOW [path to Dashy]` or `SAMEORIGIN`, as defined in [RFC-7034](https://datatracker.ietf.org/doc/html/rfc7034). These settings are usually set in the config file for the web server that's hosting the target application, here are some examples of how to enable cross-origin access with common web servers:
|
||||
@ -191,3 +214,32 @@ Currently, the status check needs a page to be rendered, so if this URL in your
|
||||
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-To Open Browser Console
|
||||
When raising a bug, one crucial piece of info needed is the browser's console output. This will help the developer diagnose and fix the issue.
|
||||
|
||||
If you've been asked for this info, but are unsure where to find it, then it is under the "Console" tab, in the browsers developer tools, which can be opened with <kbd>F12</kbd>. You can right-click the console, and select Save As to download the log.
|
||||
|
||||
To open dev tools, and jump straight to the console:
|
||||
- Win / Linux: <kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>J</kbd>
|
||||
- MacOS: <kbd>Cmd</kbd> + <kbd>Option</kbd> + <kbd>J</kbd>
|
||||
|
||||
For more detailed walk through, see [this article](https://support.shortpoint.com/support/solutions/articles/1000222881-save-browser-console-file).
|
||||
|
||||
---
|
||||
|
||||
## Git Contributions not Displaying
|
||||
|
||||
If you've contributed to Dashy (or any other project), but your contributions are not showing up on your GH profile, or in Dashy's [Credits Page](https://github.com/Lissy93/dashy/blob/master/docs/credits.md), then this is likely a git config issue.
|
||||
|
||||
These statistics are generated using the username / email associated with commits. This info needs to be setup on your local machine using [`git config`](https://git-scm.com/docs/git-config).
|
||||
|
||||
Run the following commands (replacing name + email with your info):
|
||||
- `git config --global user.name "John Doe"`
|
||||
- `git config --global user.email johndoe@example.com`
|
||||
|
||||
For more info, see [Git First Time Setup Docs](https://git-scm.com/book/en/v2/Getting-Started-First-Time-Git-Setup).
|
||||
|
||||
Note that only contributions to the master / main branch or a project are counted
|
||||
|
||||
@ -635,6 +635,7 @@ Displays the latest news, click to read full article. Date is fetched from vario
|
||||
**`lang`** | `string` | _Optional_ | Specify the language for returned articles as a 2-digit ISO code (limited article support). The [following languages](https://api.currentsapi.services/v1/available/languages) are supported, defaults to `en`
|
||||
**`count`** | `number` | _Optional_ | Limit the number of results. Can be between `1` and `200`, defaults to `10`
|
||||
**`keywords`** | `string` | _Optional_ | Only return articles that contain an exact match within their title or description
|
||||
**`hideImages`** | `boolean` | _Optional_ | If set to `true`, then article image thumbnails will not be displayed
|
||||
|
||||
##### Example
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user