mirror of
https://github.com/Lissy93/dashy.git
synced 2024-09-10 21:55:44 +03:00
📕 Chore: Sync Wiki
liss-bot
parent
1a00d5c7d8
commit
b2e548c975
@ -0,0 +1,47 @@
|
||||
# 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`).
|
||||
|
||||
### 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.
|
||||
|
||||
<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 within 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 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.
|
||||
|
||||
<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.
|
||||
|
||||
<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 default 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
|
||||
- `modal` - Launch app in a resizable/ movable popup modal on the current page
|
||||
- `workspace` - Changes to Workspace view, and launches app
|
||||
|
||||
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`.
|
||||
|
||||
<p align="center">
|
||||
<img width="500" src="https://i.ibb.co/vmZdSRt/dashy-context-menu-2.png" />
|
||||
</p>
|
||||
|
||||
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).
|
||||
File diff suppressed because one or more lines are too long
|
Before Width: | Height: | Size: 741 KiB After Width: | Height: | Size: 1.0 MiB |
BIN
assets/minimal-view-demo.gif
Normal file
BIN
assets/minimal-view-demo.gif
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 2.0 MiB |
@ -36,6 +36,36 @@ A hash is a one-way cryptographic function, meaning that it is easy to generate
|
||||
## Logging In and Out
|
||||
Once authentication is enabled, so long as there is no valid token in cookie storage, the application will redirect the user to the login page. When the user enters credentials in the login page, they will be checked, and if valid, then a token will be generated, and they can be redirected to the home page. If credentials are invalid, then an error message will be shown, and they will remain on the login page. Once in the application, to log out the user can click the logout button (in the top-right), which will clear cookie storage, causing them to be redirected back to the login page.
|
||||
|
||||
## Enabling Guest Access
|
||||
With authentication setup, by default no access is allowed to your dashboard without first logging in with valid credentials. Guest mode can be enabled to allow for read-only access to a secured dashboard by any user, without the need to log in. A guest user cannot write any changes to the config file, but can apply modifications locally (stored in their browser). You can enable guest access, by setting `appConfig.enableGuestAccess: true`.
|
||||
|
||||
## Granular Access
|
||||
You can use the following properties to make certain sections only visible to some users, or hide sections from guests.
|
||||
- `hideForUsers` - Section will be visible to all users, except for those specified in this list
|
||||
- `showForUsers` - Section will be hidden from all users, except for those specified in this list
|
||||
- `hideForGuests` - Section will be visible for logged in users, but not for guests
|
||||
|
||||
For Example:
|
||||
|
||||
```yaml
|
||||
- name: Code Analysis & Monitoring
|
||||
icon: fas fa-code
|
||||
displayData:
|
||||
cols: 2
|
||||
hideForUsers: [alicia, bob]
|
||||
items:
|
||||
...
|
||||
```
|
||||
|
||||
```yaml
|
||||
- name: Deployment Pipelines
|
||||
icon: fas fa-rocket
|
||||
displayData:
|
||||
hideForGuests: true
|
||||
items:
|
||||
...
|
||||
```
|
||||
|
||||
## Security
|
||||
Since all authentication is happening entirely on the client-side, it is vulnerable to manipulation by an adversary. An attacker could look at the source code, find the function used generate the auth token, then decode the minified JavaScript to find the hash, and manually generate a token using it, then just insert that value as a cookie using the console, and become a logged in user. Therefore, if you need secure authentication for your app, it is strongly recommended to implement this using your web server, or use a VPN to control access to Dashy. The purpose of the login page is merely to prevent immediate unauthorized access to your homepage.
|
||||
|
||||
|
||||
@ -57,23 +57,27 @@ To disallow any changes from being written to disk via the UI config editor, set
|
||||
**Field** | **Type** | **Required**| **Description**
|
||||
--- | --- | --- | ---
|
||||
**`language`** | `string` | _Optional_ | The 2 (or 4-digit) [ISO 639-1 code](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) for your language, e.g. `en` or `en-GB`. This must be a language that the app has already been [translated](https://github.com/Lissy93/dashy/tree/master/src/assets/locales) into. If your language is unavailable, Dashy will fallback to English. By default Dashy will attempt to auto-detect your language, although this may not work on some privacy browsers.
|
||||
**`startingView`** | `enum` | _Optional_ | Which page to load by default, and on the base page or domain root. You can still switch to different views from within the UI. Can be either `default`, `minimal` or `workspace`. Defaults to `default`
|
||||
**`statusCheck`** | `boolean` | _Optional_ | When set to `true`, Dashy will ping each of your services and display their status as a dot next to each item. This can be overridden by setting `statusCheck` under each item. Defaults to `false`
|
||||
**`statusCheckInterval`** | `boolean` | _Optional_ | The number of seconds between checks. If set to `0` then service will only be checked on initial page load, which is usually the desired functionality. If value is less than `10` you may experience a hit in performance. Defaults to `0`
|
||||
**`backgroundImg`** | `string` | _Optional_ | Path to an optional full-screen app background image. This can be either remote (http) or local (/). Note that this will slow down initial load
|
||||
**`enableFontAwesome`** | `boolean` | _Optional_ | Where `true` is enabled, if left blank font-awesome will be enabled only if required by 1 or more icons
|
||||
**`fontAwesomeKey`** | `string` | _Optional_ | If you have a font-awesome key, then you can use it here and make use of premium icons. It is a 10-digit alpha-numeric string from you're FA kit URL (e.g. `13014ae648`)
|
||||
**`faviconApi`** | `string` | _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`, `google`, `clearbit`, `webmasterapi` and `allesedv`. Defaults to `faviconkit`. See [Icons](/docs/icons.md#favicons) 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`, `google`, `clearbit`, `webmasterapi` and `allesedv`. Defaults to `faviconkit`. See [Icons](/docs/icons.md#favicons) for more info
|
||||
**`auth`** | `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. Note authentication is done on the client side, and so if your instance of Dashy is exposed to the internet, it is recommend to configure your web server to handle this. See [`auth`](#appconfigauth-optional)
|
||||
**`layout`** | `string` | _Optional_ | App layout, either `horizontal`, `vertical`, `auto` or `sidebar`. Defaults to `auto`. This specifies the layout and direction of how sections are positioned on the home screen. This can also be modified from the UI.
|
||||
**`iconSize`** | `string` | _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.
|
||||
**`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` to be configured. Defaults to `false`.
|
||||
**`layout`** | `enum` | _Optional_ | App layout, either `horizontal`, `vertical`, `auto` or `sidebar`. Defaults to `auto`. This specifies the layout and direction of how sections are positioned on the home screen. This can also be modified 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.
|
||||
**`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/theming.md#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)
|
||||
**`enableMultiTasking`** | `boolean` | _Optional_ | If set to true, will keep apps open in the background when in the workspace view. Useful for quickly switching between multiple sites, and preserving their state, but comes at the cost of performance.
|
||||
**`allowConfigEdit`** | `boolean` | _Optional_ | Should prevent / allow the user to write configuration changes to the conf.yml from the UI. When set to `false`, the user can only apply changes locally using the config editor within the app, whereas if set to `true` then changes can be written to disk directly through the UI. Defaults to `true`. Note that if authentication is enabled, the user must be of type `admin` in order to apply changes globally.
|
||||
**`enableErrorReporting`** | `boolean` | _Optional_ | Enable reporting of unexpected errors and crashes. This is off by default, and **no data will ever be captured unless you explicitly enable it**. Turning on error reporting helps previously unknown bugs get discovered and fixed. Dashy uses [Sentry](https://github.com/getsentry/sentry) for error reporting. Defaults to `false`.
|
||||
**`sentryDsn`** | `boolean` | _Optional_ | If you need to monitor errors in your instance, then you can use Sentry to collect and process bug reports. Sentry can be self-hosted, or used as SaaS, once your instance is setup, then all you need to do is pass in the DSN here, and enable error reporting. You can learn more on the [Sentry DSN Docs](https://docs.sentry.io/product/sentry-basics/dsn-explainer/). Note that this will only ever be used if `enableErrorReporting` is explicitly enabled.
|
||||
**`disableUpdateChecks`** | `boolean` | _Optional_ | If set to true, Dashy will not check for updates. Defaults to `false`.
|
||||
**`disableServiceWorker`** | `boolean` | _Optional_ | Service workers cache web applications to improve load times and offer basic offline functionality, and are enabled by default in Dashy. The service worker can sometimes cause older content to be cached, requiring the app to be hard-refreshed. If you do not want SW functionality, or are having issues with caching, set this property to `true` to disable all service workers.
|
||||
**`disableContextMenu`** | `boolean` | _Optional_ | If set to `true`, the custom right-click context menu will be disabled. Defaults to `false`.
|
||||
@ -145,6 +149,9 @@ To disallow any changes from being written to disk via the UI config editor, set
|
||||
**`sectionLayout`** | `string` | _Optional_ | Specify which CSS layout will be used to responsivley place items. Can be either `auto` (which uses flex layout), or `grid`. If `grid` is selected, then `itemCountX` and `itemCountY` may also be set. Defaults to `auto`
|
||||
**`itemCountX`** | `number` | _Optional_ | The number of items to display per row / horizontally. If not set, it will be calculated automatically based on available space. Can only be set if `sectionLayout` is set to `grid`. Must be a whole number between `1` and `12`
|
||||
**`itemCountY`** | `number` | _Optional_ | The number of items to display per column / vertically. If not set, it will be calculated automatically based on available space. If `itemCountX` is set, then `itemCountY` can be calculated automatically. Can only be set if `sectionLayout` is set to `grid`. Must be a whole number between `1` and `12`
|
||||
**`hideForUsers`** | `string[]` | _Optional_ | Current section will be visible to all users, except for those specified in this list
|
||||
**`showForUsers`** | `string[]` | _Optional_ | Current section will be hidden from all users, except for those specified in this list
|
||||
**`hideForGuests`** | `boolean` | _Optional_ | Current section will be visible for logged in users, but not for guests (see `appConfig.enableGuestAccess`). Defaults to `false`
|
||||
|
||||
**[⬆️ Back to Top](#configuring)**
|
||||
|
||||
@ -152,7 +159,7 @@ To disallow any changes from being written to disk via the UI config editor, set
|
||||
|
||||
**Field** | **Type** | **Required**| **Description**
|
||||
--- | --- | --- | ---
|
||||
**`icon`** | `string` | _Optional_ | The icon for a given item or section. Can be a font-awesome icon, favicon, remote URL or local URL. If set to `favicon`, the icon will be automatically fetched from the items website URL. To use font-awesome, specify the category, followed by the icon name, e.g. `fas fa-rocket`, `fab fa-monero` or `fal fa-duck` - note that to use pro icons, you mut specify `appConfig.fontAwesomeKey`. 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. Can be a font-awesome icon, favicon, remote URL or local URL. If set to `favicon`, the icon will be automatically fetched from the items website URL. To use font-awesome, specify the category, followed by the icon name, e.g. `fas fa-rocket`, `fab fa-monero` or `fal fa-duck` - note that to use pro icons, you mut specify `appConfig.fontAwesomeKey`. Similarly, you can also use [simple-icons](https://simpleicons.org/) by setting icon to `si-[icon-name]` or [material-design-icons](https://dev.materialdesignicons.com/icons) by setting icon to `mdi-[icon-name]`. If set to `generative`, then a unique icon is generated from the apps URL or IP. You can also use hosted any by specifying it's URL, e.g. `https://i.ibb.co/710B3Yc/space-invader-x256.png`. To use a local image, first store it in `./public/item-icons/` (or `-v /app/public/item-icons/` in Docker) , and reference it by name and extension - e.g. set `image.png` to use `./public/item-icon/image.png`, you can also use sub-folders if you have a lot of icons, to keep them organised.
|
||||
|
||||
**[⬆️ Back to Top](#configuring)**
|
||||
|
||||
|
||||
@ -10,14 +10,27 @@ Contributing to the code or documentation is super helpful. You can fix a bug, a
|
||||
## 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).
|
||||
|
||||
## 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 :)
|
||||
|
||||
[](https://n9fy6xak9yd.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.
|
||||
|
||||
## 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. You can [Raise a Bug here](https://github.com/Lissy93/dashy/issues/new?assignees=Lissy93&labels=%F0%9F%90%9B+Bug&template=bug-report---.md&title=%5BBUG%5D) 🐛.
|
||||
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-report---.md&title=%5BBUG%5D)
|
||||
|
||||
## 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.
|
||||
|
||||
## 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.
|
||||
[](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.
|
||||
@ -33,12 +46,14 @@ Dashy is still a relatively young project, and as such not many people know of i
|
||||
[](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)
|
||||
|
||||
## Leave a review
|
||||
## 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)
|
||||
|
||||
## 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.
|
||||
@ -47,15 +62,20 @@ Please only do this is you can definitely afford to. Don't feel any pressure to
|
||||
|
||||
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).
|
||||
|
||||
You can also send one-off small contriutions using crypto:
|
||||
<details>
|
||||
<summary>You can also send a one-off small contribution using crypto</summary>
|
||||
<p>
|
||||
|
||||
- **BTC**: `3853bSxupMjvxEYfwGDGAaLZhTKxB2vEVC`
|
||||
- **ETH**: `0x0fc98cBf8bea932B4470C46C0FbE1ed1f6765017` / `aliciasykes.eth`
|
||||
- **XMR**: `471KZdxb6N63aABR4WYwMRjTVkc1p1x7wGsUTEF7AMYzL8L94A5pCuYWkosgJQ5Ze8Y2PscVCGZFJa3hDPg6MaDq47GUm8r`#
|
||||
- **XMR**: `471KZdxb6N63aABR4WYwMRjTVkc1p1x7wGsUTEF7AMYzL8L94A5pCuYWkosgJQ5Ze8Y2PscVCGZFJa3hDPg6MaDq47GUm8r`
|
||||
</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.
|
||||
|
||||
For more info, see [Dashy on Bounty Source](https://www.bountysource.com/teams/dashy)
|
||||
[](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.
|
||||
@ -69,7 +89,7 @@ appConfig:
|
||||
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/).
|
||||
|
||||
## Follow for More
|
||||
If you've enjoyed Dashy, you can follow the me to get updates about other projects that I am working on. Or [subscribe to my mailing list](https://notes.aliciasykes.com/subscribe) for very occasional blog post updates.
|
||||
If you've enjoyed Dashy, you can follow the me to get updates about other projects that I am working on.
|
||||
|
||||
[](https://twitter.com/Lissy_Sykes)
|
||||
[](https://github.com/Lissy93)
|
||||
@ -79,10 +99,14 @@ If you've enjoyed Dashy, you can follow the me to get updates about other projec
|
||||
[](https://aliciasykes.com)
|
||||
[](https://notes.aliciasykes.com/)
|
||||
|
||||
If you like, you could also consider [subscribing to my mailing list](https://notes.aliciasykes.com/subscribe) for very occasional blog post updates, or even [nominating me (`@lissy93`)](https://stars.github.com/nominate/) on the GitHub Star Programme.
|
||||
|
||||
---
|
||||
|
||||
### Contributors
|
||||
|
||||
For a full list of Dashy's contributors, see the [Credits Page](/docs/credits.md)
|
||||
|
||||
|
||||
|
||||
### Star-Gazers Over Time
|
||||
|
||||
68
credits.md
68
credits.md
@ -10,12 +10,19 @@
|
||||
<br />
|
||||
<sub><b>Robert Ernst</b></sub>
|
||||
</a>
|
||||
</td>
|
||||
<td align="center">
|
||||
<a href="https://github.com/swcarlosrj">
|
||||
<img src="https://avatars.githubusercontent.com/u/9881700?u=c92e4a0ccc0bff241e50582bce914b179b6d89b6&v=4" width="80;" alt="swcarlosrj"/>
|
||||
<br />
|
||||
<sub><b>Carlos Rufo</b></sub>
|
||||
</a>
|
||||
</td></tr>
|
||||
</table>
|
||||
<!-- readme: sponsors -end -->
|
||||
|
||||
## Contributors
|
||||
<!-- readme: contributors -start -->
|
||||
<!-- readme: contributors, BeginCI/-, deepsourcebot/- -start -->
|
||||
<table>
|
||||
<tr>
|
||||
<td align="center">
|
||||
@ -26,17 +33,17 @@
|
||||
</a>
|
||||
</td>
|
||||
<td align="center">
|
||||
<a href="https://github.com/BeginCI">
|
||||
<img src="https://avatars.githubusercontent.com/u/57495754?v=4" width="80;" alt="BeginCI"/>
|
||||
<a href="https://github.com/EVOTk">
|
||||
<img src="https://avatars.githubusercontent.com/u/45015615?v=4" width="80;" alt="EVOTk"/>
|
||||
<br />
|
||||
<sub><b>Begin</b></sub>
|
||||
<sub><b>EVOTk</b></sub>
|
||||
</a>
|
||||
</td>
|
||||
<td align="center">
|
||||
<a href="https://github.com/turnrye">
|
||||
<img src="https://avatars.githubusercontent.com/u/701035?v=4" width="80;" alt="turnrye"/>
|
||||
<a href="https://github.com/evroon">
|
||||
<img src="https://avatars.githubusercontent.com/u/11857441?v=4" width="80;" alt="evroon"/>
|
||||
<br />
|
||||
<sub><b>Ryan Turner</b></sub>
|
||||
<sub><b>Erik Vroon</b></sub>
|
||||
</a>
|
||||
</td>
|
||||
<td align="center">
|
||||
@ -45,12 +52,49 @@
|
||||
<br />
|
||||
<sub><b>Snyk Bot</b></sub>
|
||||
</a>
|
||||
</td>
|
||||
<td align="center">
|
||||
<a href="https://github.com/onedr0p">
|
||||
<img src="https://avatars.githubusercontent.com/u/213795?v=4" width="80;" alt="onedr0p"/>
|
||||
<br />
|
||||
<sub><b>ᗪєνιη ᗷυнʟ</b></sub>
|
||||
</a>
|
||||
</td>
|
||||
<td align="center">
|
||||
<a href="https://github.com/UrekD">
|
||||
<img src="https://avatars.githubusercontent.com/u/38784343?v=4" width="80;" alt="UrekD"/>
|
||||
<br />
|
||||
<sub><b>UrekD</b></sub>
|
||||
</a>
|
||||
</td></tr>
|
||||
<tr>
|
||||
<td align="center">
|
||||
<a href="https://github.com/BeginCI">
|
||||
<img src="https://avatars.githubusercontent.com/u/57495754?v=4" width="80;" alt="BeginCI"/>
|
||||
<br />
|
||||
<sub><b>Begin</b></sub>
|
||||
</a>
|
||||
</td>
|
||||
<td align="center">
|
||||
<a href="https://github.com/deepsourcebot">
|
||||
<img src="https://avatars.githubusercontent.com/u/60907429?v=4" width="80;" alt="deepsourcebot"/>
|
||||
<br />
|
||||
<sub><b>DeepSource Bot</b></sub>
|
||||
</a>
|
||||
</td>
|
||||
<td align="center">
|
||||
<a href="https://github.com/turnrye">
|
||||
<img src="https://avatars.githubusercontent.com/u/701035?v=4" width="80;" alt="turnrye"/>
|
||||
<br />
|
||||
<sub><b>Ryan Turner</b></sub>
|
||||
</a>
|
||||
</td></tr>
|
||||
</table>
|
||||
<!-- readme: contributors -end -->
|
||||
<!-- readme: contributors, BeginCI/-, deepsourcebot/- -end -->
|
||||
|
||||
|
||||
## Helpful Users
|
||||
<!-- readme: EVOTk,shadowking001,turnrye,Robert-Ernst,MilesTEG1,Niklashere -start -->
|
||||
<!-- readme: EVOTk,shadowking001,turnrye,Robert-Ernst,Niklashere,evroon,MilesTEG1 -start -->
|
||||
<table>
|
||||
<tr>
|
||||
<td align="center">
|
||||
@ -131,7 +175,7 @@
|
||||
This app definitely wouldn't have been quite so possible without the making use of the following package and components. Full credit and big kudos to their respective authors, who've done an amazing job in building and maintaining them. For a full breakdown of dependency licenses, please see [Legal](https://github.com/Lissy93/dashy/blob/master/.github/LEGAL.md)
|
||||
|
||||
##### Core
|
||||
At it's core, the application uses [Vue.js](https://github.com/vuejs/vue), as well as it's services. Styling is done with [SCSS](https://github.com/sass/sass), JavaScript is currently [Babel](https://github.com/babel/babel), (but I am in the process of converting to [TypeScript](https://github.com/Microsoft/TypeScript)), linting is done with [ESLint](https://github.com/eslint/eslint), the config is defined in [YAML](https://github.com/yaml/yaml), and there is a simple [Node.js](https://github.com/nodejs/node) server to serve up the static app.
|
||||
At it's core, the application uses [Vue.js](https://github.com/vuejs/vue), as well as it's services. Styling is done with [SCSS](https://github.com/sass/sass), JavaScript is currently [Babel](https://github.com/babel/babel), (but I am in the process of converting to [TypeScript](https://github.com/Microsoft/TypeScript)). Linting is done with [ESLint](https://github.com/eslint/eslint) and [Prettier](https://prettier.io/), both following the [AirBnB Styleguide](https://github.com/airbnb/javascript). The config is defined in [YAML](https://github.com/yaml/yaml), and there is a simple [Node.js](https://github.com/nodejs/node) server to serve up the static app and the optional API endpoints.
|
||||
|
||||
##### Utilities
|
||||
- [`crypto-js`](https://github.com/brix/crypto-js) - Encryption implementations by @evanvosberg and community `MIT`
|
||||
@ -147,15 +191,13 @@ At it's core, the application uses [Vue.js](https://github.com/vuejs/vue), as we
|
||||
- [`VJsoneditor`](https://github.com/yansenlei/VJsoneditor) - Interactive JSON editor component by @yansenlei `MIT`
|
||||
- Forked from [`JsonEditor`](https://github.com/josdejong/jsoneditor) by @josdejong `Apache-2.0 License`
|
||||
- [`vue-toasted`](https://github.com/shakee93/vue-toasted) - Toast notification component by @shakee93 `MIT`
|
||||
- [`vue-prism-editor`](https://github.com/koca/vue-prism-editor) - Lightweight code editor by @koca `MIT`
|
||||
- Forked from [`prism.js`](https://github.com/PrismJS/prism) `MIT`
|
||||
- [`vue-swatches`](https://github.com/saintplay/vue-swatches) - Color palete picker by @saintplay `MIT`
|
||||
|
||||
##### Backup & Sync Server
|
||||
Although the app is purely frontend, there is an optional cloud backup and restore feature. This is built as a serverless function on [Cloudflare workers](https://workers.cloudflare.com/) using [KV](https://developers.cloudflare.com/workers/runtime-apis/kv) and [web crypto](https://developers.cloudflare.com/workers/runtime-apis/web-crypto)
|
||||
|
||||
##### External Services
|
||||
The 1-Click deploy demo uses [Play-with-Docker Labs](https://play-with-docker.com/). Code is hosted on [GitHub](https://github.com), Docker image is hosted on [DockerHub](https://hub.docker.com/), and the demos are hosted on [Netlify](https://www.netlify.com/).
|
||||
The 1-Click deploy demo uses [Play-with-Docker Labs](https://play-with-docker.com/). Code is hosted on [GitHub](https://github.com), Docker images are hosted on [DockerHub](https://hub.docker.com/), and the demos are hosted on [Netlify](https://www.netlify.com/).
|
||||
|
||||
---
|
||||
|
||||
|
||||
@ -3,14 +3,14 @@
|
||||
Welcome to Dashy, so glad you're here :) Deployment is super easy, and there are several methods available depending on what type of system you're using. If you're self-hosting, then deploying with Docker (or similar container engine) is the recommended approach.
|
||||
|
||||
#### Quick Start
|
||||
If you want to skip the fuss, and get straight down to it, then you can spin up a new instance of Dashy by running:
|
||||
If you want to skip the fuss, and [get straight down to it](/docs/quick-start.md), then you can spin up a new instance of Dashy by running:
|
||||
```
|
||||
docker run -p 8080:80 lissy93/dashy
|
||||
```
|
||||
|
||||
See [Management Docs](./docs/management.md) for info about securing, monitoring, updating, health checks, auto starting, web server configuration, etc
|
||||
See [Management Docs](/docs/management.md) 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. You can either reference the [configuring docs]() or follow this [step-by-step guide]().
|
||||
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.md).
|
||||
|
||||
## Deployment Methods
|
||||
|
||||
@ -25,6 +25,19 @@ Once you've got Dashy up and running, you'll want to configure it with your own
|
||||
|
||||
### Deploy with Docker
|
||||
|
||||
**Container Info**: [
|
||||
|
||||
|
||||
|
||||
](https://hub.docker.com/r/lissy93/dashy)<br>
|
||||
**Status**: [
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
](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.
|
||||
|
||||
|
||||
@ -43,17 +56,21 @@ Explanation of the above options:
|
||||
- `-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, by replacing `:latest` with one of tthe [tags](https://hub.docker.com/r/lissy93/dashy/tags)
|
||||
- `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` (optionally use the `-f` flag to specify file location, if it isn't located at `./docker-compose.yml`).
|
||||
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` (optionally use the `-f` flag to specify file location, if it isn't located at `./docker-compose.yml`). Compose is also useful if you are using clusters, as the format is very similar to stack files, used with Docker Swarm.
|
||||
|
||||
Compose is also useful if you are using clusters, as the format is very similar to stack files, used with Docker Swarm.
|
||||
|
||||
The following is a complete example of a `docker-compose.yml` for Dashy. Run it as is, or uncomment the additional options you need.
|
||||
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
|
||||
---
|
||||
@ -85,23 +102,20 @@ services:
|
||||
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`
|
||||
|
||||
### 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 git@github.com:Lissy93/dashy.git` and `cd dashy`
|
||||
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`
|
||||
|
||||
### Run as executable
|
||||
|
||||
### Install with NPM
|
||||
|
||||
### Use managed instance
|
||||
|
||||
### 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.
|
||||
@ -110,8 +124,8 @@ Some hosting providers required a bit of extra configuration, which was why I've
|
||||
|
||||
**Note** If you use a static hosting provider, then status checks, writing new config changes to disk from the UI, and triggering a rebuild through the UI will not be availible. This is because these features need endpoints provided by Dashy's local Node server. Everything else should work just the same though.
|
||||
|
||||
#### Netlify <img src="https://i.ibb.co/ZxtzrP3/netlify.png" width="24"/>
|
||||
[](https://app.netlify.com/start/deploy?repository=https://github.com/lissy93/dashy)
|
||||
#### Netlify
|
||||
[](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.
|
||||
|
||||
@ -120,8 +134,8 @@ To deploy Dashy to Netlify, use the following link
|
||||
https://app.netlify.com/start/deploy?repository=https://github.com/lissy93/dashy
|
||||
```
|
||||
|
||||
#### Heroku <img src="https://i.ibb.co/d2P1WZ7/heroku.png" width="24"/>
|
||||
[](https://heroku.com/deploy?template=https://github.com/Lissy93/dashy)
|
||||
#### Heroku
|
||||
[](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 is free to use for unlimited, non-commercial, single dyno apps, and supports custom domains. Heroku's single-dyno service is not as quite performant as some other providers, and the app will have a short wake-up time when not visited for a while
|
||||
|
||||
@ -130,8 +144,8 @@ To deploy Dashy to Heroku, use the following link
|
||||
https://heroku.com/deploy?template=https://github.com/Lissy93/dashy
|
||||
```
|
||||
|
||||
#### Cloudflare Workers <img src="https://i.ibb.co/CvpFM1S/cloudflare.png" width="24"/>
|
||||
[](https://deploy.workers.cloudflare.com/?url=https://github.com/lissy93/dashy/tree/deploy_cloudflare)
|
||||
#### Cloudflare Workers
|
||||
[](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)
|
||||
|
||||
@ -140,8 +154,8 @@ To deploy Dashy to Cloudflare, use the following link
|
||||
https://deploy.workers.cloudflare.com/?url=https://github.com/lissy93/dashy/tree/deploy_cloudflare
|
||||
```
|
||||
|
||||
#### Vercel <img src="https://i.ibb.co/Ld2FZzb/vercel.png" width="24"/>
|
||||
[](https://vercel.com/new/project?template=https://github.com/lissy93/dashy)
|
||||
#### Vercel
|
||||
[](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 anaylzing application performance and other metrics. Vercel is free for personal use, allows for custom domains and has very reasonable limits.
|
||||
|
||||
@ -150,8 +164,8 @@ To deploy Dashy to Vercel, use the following link
|
||||
https://vercel.com/new/project?template=https://github.com/lissy93/dashy
|
||||
```
|
||||
|
||||
#### DigitalOcean <img src="https://i.ibb.co/V2MxtGC/digitalocean.png" width="24"/>
|
||||
[](https://cloud.digitalocean.com/apps/new?repo=https://github.com/lissy93/dashy/tree/deploy_digital-ocean&refcode=3838338e7f79)
|
||||
#### DigitalOcean
|
||||
[](https://cloud.digitalocean.com/apps/new?repo=https://github.com/lissy93/dashy/tree/deploy_digital-ocean&refcode=3838338e7f79)
|
||||
|
||||
[DigitalOcan](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.
|
||||
|
||||
@ -159,8 +173,8 @@ https://vercel.com/new/project?template=https://github.com/lissy93/dashy
|
||||
https://cloud.digitalocean.com/apps/new?repo=https://github.com/lissy93/dashy/tree/deploy_digital-ocean
|
||||
```
|
||||
|
||||
#### Google Cloud Platform <img src="https://i.ibb.co/J7MGymY/googlecloud.png" width="24"/>
|
||||
[](https://deploy.cloud.run/?git_repo=https://github.com/lissy93/dashy.git)
|
||||
#### Google Cloud Platform
|
||||
[](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.
|
||||
|
||||
@ -169,8 +183,8 @@ To deploy Dashy to GCP, use the following link
|
||||
https://deploy.cloud.run/?git_repo=https://github.com/lissy93/dashy.git
|
||||
```
|
||||
|
||||
#### Platform.sh <img src="https://i.ibb.co/GdfvH3Z/platformsh.png" width="24"/>
|
||||
[](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://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
|
||||
|
||||
@ -179,8 +193,8 @@ To deploy Dashy to Platform.sh, use the following link
|
||||
https://console.platform.sh/projects/create-project/?template=https://github.com/lissy93/dashy
|
||||
```
|
||||
|
||||
#### Render <img src="https://i.ibb.co/xCHtzgh/render.png" width="24"/>
|
||||
[](https://render.com/deploy?repo=https://github.com/lissy93/dashy/tree/deploy_render)
|
||||
#### Render
|
||||
[](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)
|
||||
|
||||
@ -189,8 +203,8 @@ To deploy Dashy to Render, use the following link
|
||||
https://render.com/deploy?repo=https://github.com/lissy93/dashy/tree/deploy_render
|
||||
```
|
||||
|
||||
#### Scalingo <img src="https://i.ibb.co/Rvf5c4y/scalingo.png" width="24"/>
|
||||
[](https://my.scalingo.com/deploy?source=https://github.com/lissy93/dashy#master)
|
||||
#### Scalingo
|
||||
[](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
|
||||
|
||||
@ -199,8 +213,8 @@ To deploy Dashy to Scalingo, use the following link
|
||||
https://my.scalingo.com/deploy?source=https://github.com/lissy93/dashy#master
|
||||
```
|
||||
|
||||
#### Play-with-Docker <img src="https://i.ibb.co/HVWVYF7/docker.png" width="24"/>
|
||||
[](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/?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.
|
||||
|
||||
@ -209,9 +223,10 @@ To run Dashy in PWD, use the following URL:
|
||||
https://labs.play-with-docker.com/?stack=https://raw.githubusercontent.com/Lissy93/dashy/master/docker-compose.yml
|
||||
```
|
||||
|
||||
#### Surge.sh <img src="https://i.ibb.co/WgVC4mB/surge.png" width="24"/>
|
||||
[Surge.sh](http://surge.sh/) is quick and easy static web publishing platform for frontend-apps.
|
||||
#### Surge.sh
|
||||
|
||||
|
||||
[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
|
||||
|
||||
@ -18,7 +18,7 @@ You will need either the latest or LTS version of **[Node.js](https://nodejs.org
|
||||
|
||||
### Running the Project
|
||||
|
||||
1. Get Code: `git clone git@github.com:Lissy93/dashy.git`
|
||||
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`
|
||||
@ -154,7 +154,7 @@ As well as Node, Git and Docker- you'll also need an IDE (e.g. [VS Code](https:/
|
||||
|
||||
## Style Guide
|
||||
|
||||
Linting is done using [ESLint](https://eslint.org/), and using the [Vue.js Styleguide](https://github.com/vuejs/eslint-config-standard), which is very similar to the [AirBnB Stylguide](https://github.com/airbnb/javascript). You can run `yarn lint` to report and fix issues. While the dev server is running, issues will be reported to the console automatically. 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
|
||||
Linting is done using [ESLint](https://eslint.org/), and using the [Vue.js Styleguide](https://github.com/vuejs/eslint-config-standard), which is very similar to the [AirBnB Stylguide](https://github.com/airbnb/javascript). You can run `yarn lint` to report and fix issues. While the dev server is running, issues will be reported to the console automatically, and any lint errors will trigger the build to fail. Note that all lint checks must pass before any PR can be merged. Linting is also run as a git pre-commit hook
|
||||
|
||||
The most significant things to note are:
|
||||
- Indentation should be done with two spaces
|
||||
@ -167,7 +167,9 @@ The most significant things to note are:
|
||||
- All multiline blocks must use braces
|
||||
- Avoid console statements in the frontend
|
||||
|
||||
For the full styleguide, see: [github.com/airbnb/javascript](https://github.com/airbnb/javascript)
|
||||
Styleguides:
|
||||
- Vue: [Vue styleguide](https://vuejs.org/v2/style-guide/)
|
||||
- JavaScript: [github.com/airbnb/javascript](https://github.com/airbnb/javascript)
|
||||
|
||||
---
|
||||
|
||||
@ -229,7 +231,7 @@ For the full styleguide, see: [github.com/airbnb/javascript](https://github.com/
|
||||
│ │ ├── Nav.vue # Navigation bar, includes a list of links
|
||||
│ │ ╰── PageTitle.vue # Page title and sub-title, visible within the Header
|
||||
│ ╰── Settings # Components relating to the quick-settings, in the top-right
|
||||
│ ├── AppButtons.vue # Logout button and other app info
|
||||
│ ├── AuthButtons.vue # Logout button and other app info
|
||||
│ ├── ConfigLauncher.vue # Icon that when clicked will launch the Configuration component
|
||||
│ ├── CustomThemeMaker.vue # Color pickers for letting user build their own theme
|
||||
│ ├── ItemSizeSelector.vue # Set of buttons used to set and save item size
|
||||
|
||||
@ -34,14 +34,14 @@ Note that if you're theme is just for yourself, and you're not submitting a PR,
|
||||
|
||||
## Writing Translations
|
||||
|
||||
For full docs about Dashy's multi-language support, see [Multi-Language Support](./multi-language-support.md)
|
||||
|
||||
Dashy is using [vue-i18n](https://vue-i18n.intlify.dev/guide/) to manage multi-language support.
|
||||
|
||||
Adding a new language is pretty straightforward, with just three steps:
|
||||
|
||||
##### 1. Create a new Language File
|
||||
Create a new JSON file in `./src/assets/locales` name is a 2-digit [ISO-639 code](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) for your language, E.g. for German `de.json`, French `fr.json` or Spanish `es.json` - You can find a list of all ISO codes at [iso.org](https://www.iso.org/obp/ui).
|
||||
If your language is a specific dialect or regional language, then use the Posfix [CLDR](http://cldr.unicode.org/) format, where, e.g. `en-GB.json` (British), `es-MX.json` (Spanish, in Mexico) or `zh-CN.json` (Chinese, simplified) - A list of which can be found [here](https://github.com/unicode-org/cldr-json/blob/master/cldr-json/cldr-core/availableLocales.json)
|
||||
|
||||
|
||||
##### 2. Translate!
|
||||
Using [`en.json`](https://github.com/Lissy93/dashy/tree/master/src/assets/locales/en.json) as an example, translate the JSON values to your language, while leaving the keys as they are. It's fine to leave out certain items, as if they're missing they will fall-back to English. If you see any attribute which include curly braces (`{xxx}`), then leave the inner value of these braces as is, as this is for variables.
|
||||
@ -84,7 +84,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, 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.
|
||||
|
||||
@ -137,4 +137,42 @@ Checklist:
|
||||
|
||||
## Updating Dependencies
|
||||
|
||||
Running `yarn upgrade` will updated all dependencies based on the ranges specified in the `package.json`. The `yarn.lock` file will be updated, as will the contents of `./node_modules`, for more info, see the [yarn upgrade documentation](https://classic.yarnpkg.com/en/docs/cli/upgrade/). It is important to thoroughly test after any big dependency updates.
|
||||
Running `yarn upgrade` will updated all dependencies based on the ranges specified in the `package.json`. The `yarn.lock` file will be updated, as will the contents of `./node_modules`, for more info, see the [yarn upgrade documentation](https://classic.yarnpkg.com/en/docs/cli/upgrade/). It is important to thoroughly test after any big dependency updates.
|
||||
|
||||
---
|
||||
|
||||
## Hiding Page Furniture on Certain Routes
|
||||
For some pages (such as the login page, the minimal start page, etc) the basic page furniture, (like header, footer, nav, etc) is not needed. This section explains how you can hide furniture on a new view (step 1), or add a component that should be hidden on certain views (step 2).
|
||||
|
||||
##### 1. Add the route name to the should hide array
|
||||
|
||||
In [`./src/utils/defaults.js`](https://github.com/Lissy93/dashy/blob/master/src/utils/defaults.js), there's an array called `hideFurnitureOn`. Append the name of the route (the same as it appears in [`router.js`](https://github.com/Lissy93/dashy/blob/master/src/router.js)) here.
|
||||
|
||||
##### 2. Add the conditional to the structural component to hide
|
||||
|
||||
First, import the helper function:
|
||||
```javascript
|
||||
import { shouldBeVisible } from '@/utils/MiscHelpers';
|
||||
```
|
||||
|
||||
Then you can create a computed value, that calls this function, passing in the route name:
|
||||
```javascript
|
||||
export default {
|
||||
...
|
||||
computed: {
|
||||
...
|
||||
isVisible() {
|
||||
return shouldBeVisible(this.$route.name);
|
||||
},
|
||||
},
|
||||
};
|
||||
```
|
||||
|
||||
Finally, in the markup of your component, just add a `v-if` statement, referencing your computed value
|
||||
```vue
|
||||
<header v-if="isVisible">
|
||||
...
|
||||
</header>
|
||||
```
|
||||
|
||||
---
|
||||
24
icons.md
24
icons.md
@ -14,6 +14,8 @@ Both sections and items can have an icon, which is specified using the `icon` at
|
||||
<img width="500" src="https://i.ibb.co/GTVmZnc/dashy-example-icons.png" />
|
||||
</p>
|
||||
|
||||
Note that, if you are using icons from an external source (like font-awesome or material-design-icons), then the relevant font file will be loaded in automatically if and when needed, but combining icons from multiple services may have a negative impact on performance.
|
||||
|
||||
### Font Awesome
|
||||
You can use any [Font Awesome Icon](https://fontawesome.com/icons) simply by specifying it's identifier. This is in the format of `[category] [name]` and can be found on the page for any given icon on the Font Awesome site. For example: `fas fa-rocket`, `fab fa-monero` or `fas fa-unicorn`.
|
||||
|
||||
@ -54,7 +56,7 @@ You can use almost any emoji as an icon for items or sections. You can specify t
|
||||
<img width="580" src="https://i.ibb.co/YLwgTf9/emoji-icons-1.png" />
|
||||
</p>
|
||||
|
||||
The following example shows the unicode options available, all three will render the 🚀 emoji.
|
||||
The following examples will all render the same rocket (🚀) emoji:
|
||||
|
||||
```yaml
|
||||
items:
|
||||
@ -74,5 +76,25 @@ You may also want to store your icons locally, bundled within Dashy so that ther
|
||||
|
||||
You can also use sub-folders within the `item-icons` directory to keep things organised. You would then specify an icon with it's folder name slash image name. For example: `networking/monit.png`
|
||||
|
||||
### Material Design Icons
|
||||
Dashy also supports 5000+ [material-design-icons](https://github.com/Templarian/MaterialDesign). To use these, first find the name/ slug for your icon [here](https://dev.materialdesignicons.com/icons), and then prefix is with `mdi-`.
|
||||
|
||||
For example:
|
||||
```yaml
|
||||
sections:
|
||||
- name: Material Design Icons Example
|
||||
items:
|
||||
- title: Alien Icon
|
||||
icon: mdi-alien
|
||||
- title: Fire Icon
|
||||
icon: mdi-fire
|
||||
- title: Dino Icon
|
||||
icon: mdi-google-downasaur
|
||||
|
||||
```
|
||||
|
||||
### Simple Icons
|
||||
To use glyphs from [SimpleIcons.org](https://simpleicons.org/), first find the icon slug, and then prefix it with `si-`. The image will be loaded directly from the Simple Icons
|
||||
|
||||
### No Icon
|
||||
If you don't wish for a given item or section to have an icon, just leave out the `icon` attribute.
|
||||
|
||||
38
privacy.md
38
privacy.md
@ -11,7 +11,7 @@ For privacy and security tips, check out another project of mine: **[Personal Se
|
||||
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.
|
||||
|
||||
### Font Awesome
|
||||
If either sections or items are using font-awesome icons, then these will be fetched directly from font-awesome on page load.
|
||||
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.
|
||||
|
||||
### Favicon Fetching
|
||||
If an item's icon is set to `favicon`, then it will be auto-fetched from the corresponding URL. Since not all websites have their icon located at `/favicon.ico`, and if they do, it's often very low resolution (like `16 x 16 px`). Therefore, the default behavior is for Dashy to check if the URL is public, and if so will use an API to fetch the favicon. For self-hosted services, the favion will be fetched from the default path, and no external requests will be made.
|
||||
@ -31,18 +31,49 @@ The status check util will ping your services directly, and does not rely on any
|
||||
When the application loads, it checks for updates. The results of which are displayed in the config menu of the UI. This was implemented because using a very outdated version of Dashy may have unfixed issues. Your version is fetched from the source (local request), but the latest version is fetched from GitHub, which is an external request. This can be disabled by setting `appConfig.disableUpdateChecks: true`
|
||||
|
||||
### Anonymous Error Reporting
|
||||
Error reporting is disabled by default, and no data will ever be sent without your explicit consent. In fact, the error tracking method will not even be imported unless you have actively enabled it. [Sentry](https://github.com/getsentry/sentry) is used for this, it's an open source error tracking and performance monitoring tool, which is used to identify any errors which occur in the production app (if you enable it).
|
||||
Error reporting is disabled by default, and no data will ever be sent without your explicit consent. In fact, the error tracking method will not even be imported unless you have actively enabled it. [Sentry](https://github.com/getsentry/sentry) is used for this, it's an open source error tracking and performance monitoring tool, which is used to identify any issues which occur in the production app (if you enable it).
|
||||
|
||||
The crash report includes the file or line of code that triggered the error, and a 2-layer deep stack trace. Reoccurring errors will also include the following user information: OS type (Mac, Windows, Linux, Android or iOS) and browser type (Firefox, Chrome, IE, Safari). Data scrubbing is enabled. IP address will not be stored. If any potentially identifiable data ever finds its way into a crash report, it will be automatically and permanently erased. All statistics collected are anonomized and stored securely, and ae automatically deleted after 14 days. For more about privacy and security, see the [Sentry Docs](https://sentry.io/security/).
|
||||
|
||||
Enabling anonymous error reporting helps me to discover bugs I was unaware of, and then fix them, in order to make Dashy more reliable long term. Error reporting is activated by setting `appConfig.enableErrorReporting: true`.
|
||||
|
||||
If you need to monitor bugs yourself, then you can [self-host your own Sentry Server](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.
|
||||
|
||||
---
|
||||
|
||||
## Local Storage
|
||||
In order for user preferences to be persisted between sessions, certain data needs to be stored in the browsers local storage. No personal info is kept here, none of this data can be accessed by other domains, and no data is ever sent to any server without your prior consent.
|
||||
You can view your browsers session storage by opening up the dev tools (F12) --> Application --> Storage.
|
||||
|
||||
The following section outlines all data that is stored in the browsers, as cookies or local storage.
|
||||
|
||||
#### Cookies
|
||||
- `AUTH_TOKEN` - A unique token, generated from a hash of users credentials, to verify they are authenticated. Only used when auth is enabled
|
||||
|
||||
#### Local Storage
|
||||
- `LANGUAGE` - The locale to show app text in
|
||||
- `HIDE_WELCOME_BANNER` - Set to true once user dismissed welcome message, so that it's not shown again
|
||||
- `LAYOUT_ORIENTATION` - Preferred section layout, either horizontal, vertical or auto
|
||||
- `COLLAPSE_STATE` - Remembers which sections are collapsed
|
||||
- `ICON_SIZE` - Size of items, either small, medium or large
|
||||
- `THEME: 'theme` - Users applied theme
|
||||
- `CUSTOM_COLORS` - Any color modifications made to a given theme
|
||||
- `BACKUP_ID` - If a backup has been made, the ID is stored here
|
||||
- `BACKUP_HASH` - A unique hash of the previous backups meta data
|
||||
- `HIDE_SETTINGS` - Lets user hide or show the settings menu
|
||||
- `USERNAME` - If user logged in, store username in order to welcome them
|
||||
- `CONF_SECTIONS` - Array of sections, only used when user applies changes locally
|
||||
- `PAGE_INFO` - Config page info, only used when user applies changes locally
|
||||
- `APP_CONFIG` - App config, only used when user applies changes locally
|
||||
|
||||
---
|
||||
|
||||
## Dependencies
|
||||
As with most web projects, Dashy relies on several [dependencies](https://github.com/Lissy93/dashy/blob/master/docs/credits.md#dependencies-). For links to each, and a breakdown of their licenses, please see [Legal](https://github.com/Lissy93/dashy/blob/master/.github/LEGAL.md).
|
||||
|
||||
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).
|
||||
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.
|
||||
|
||||
---
|
||||
|
||||
@ -58,6 +89,7 @@ There is very little complexity involved with Dashy, and therefore the attack su
|
||||
- Enable and configure firewall rules
|
||||
- Implement security, malware and traffic scanning
|
||||
- Setup malicious traffic detection
|
||||
- Understand the [Docker attack fronts](https://docs.docker.com/engine/security/), and follow [Docker Security Best Practices](https://snyk.io/blog/10-docker-image-security-best-practices/)
|
||||
|
||||
This is covered in more detail in [App Management](/docs/management.md).
|
||||
|
||||
|
||||
128
quick-start.md
Normal file
128
quick-start.md
Normal file
@ -0,0 +1,128 @@
|
||||
# Quick Start
|
||||
|
||||
Welcome to Dashy! So glad you're here 😊 In a couple of minutes, you'll have your new dashboard up and running 🚀
|
||||
|
||||
**TDLR;** Run `docker run -p 8080:80 lissy93/dashy`, then open `http://localhost:8080`
|
||||
|
||||
---
|
||||
|
||||
## 1. Prerequisites
|
||||
|
||||
The quickest and easiest method of running Dashy is using Docker (or another container engine). You can find installation instructions for your system in the [Docker Documentation](https://docs.docker.com/get-docker/).
|
||||
If you don't want to use Docker, then you can use one of Dashy's other supported installation methods instead, all of which are outlined in the [Deployment Docs](https://github.com/Lissy93/dashy/blob/master/docs/deployment.md).
|
||||
|
||||
---
|
||||
|
||||
## 2. Installation
|
||||
|
||||
To pull the latest image, and build and start the app run:
|
||||
```
|
||||
docker run -d \
|
||||
-p 8080:80 \
|
||||
--name my-dashboard \
|
||||
--restart=always \
|
||||
lissy93/dashy:latest
|
||||
```
|
||||
|
||||
For a full list of available options, then see [Dashy with Docker](https://github.com/Lissy93/dashy/blob/master/docs/deployment.md#deploy-with-docker) Docs. If you'd prefer to use Docker Compose, then see [Dashy with Docker Compose](https://github.com/Lissy93/dashy/blob/master/docs/deployment.md#using-docker-compose) Docs.
|
||||
|
||||
Your dashboard should now be up and running at `http://localhost:8080` (or your servers IP address/ domain, and the port that you chose). The first build will may take a few minutes
|
||||
|
||||
---
|
||||
|
||||
## 3. Configure
|
||||
|
||||
Now that you've got Dashy running, you are going to want to set it up with your own content.
|
||||
Config is written in [YAML Format](https://yaml.org/), and saved in [`/public/conf.yml`](https://github.com/Lissy93/dashy/blob/master/public/conf.yml).
|
||||
The format on the config file is pretty straight forward. There are three root attributes:
|
||||
- [`pageInfo`](https://github.com/Lissy93/dashy/blob/master/docs/configuring.md#pageinfo) - Dashboard meta data, like title, description, nav bar links and footer text
|
||||
- [`appConfig`](https://github.com/Lissy93/dashy/blob/master/docs/configuring.md#appconfig-optional) - Dashboard settings, like themes, authentication, language and customization
|
||||
- [`sections`](https://github.com/Lissy93/dashy/blob/master/docs/configuring.md#section) - An array of sections, each including an array of items
|
||||
|
||||
|
||||
You can view a full list of all available config options in the [Configuring Docs](https://github.com/Lissy93/dashy/blob/master/docs/configuring.md).
|
||||
|
||||
```yaml
|
||||
pageInfo:
|
||||
title: Home Lab
|
||||
sections: # An array of sections
|
||||
- name: Example Section
|
||||
icon: far fa-rocket
|
||||
items:
|
||||
- title: GitHub
|
||||
description: Dashy source code and docs
|
||||
icon: fab fa-github
|
||||
url: https://github.com/Lissy93/dashy
|
||||
- title: Issues
|
||||
description: View open issues, or raise a new one
|
||||
icon: fas fa-bug
|
||||
url: https://github.com/Lissy93/dashy/issues
|
||||
- name: Local Services
|
||||
items:
|
||||
- title: Firewall
|
||||
icon: favicon
|
||||
url: http://192.168.1.1/
|
||||
- title: Game Server
|
||||
icon: https://i.ibb.co/710B3Yc/space-invader-x256.png
|
||||
url: http://192.168.130.1/
|
||||
```
|
||||
|
||||
Notes:
|
||||
- You can use a Docker volume to pass a config file from your host system to the container
|
||||
- E.g. `-v ./host-system/my-local-conf.yml:/app/public/conf.yml`
|
||||
- It's also possible to edit your config directly through the UI, and changes will be saved in this file
|
||||
- Check your config against Dashy's schema, with `docker exec -it [container-id] yarn validate-config`
|
||||
- You might find it helpful to look at some examples, a collection of which can be [found here](https://gist.github.com/Lissy93/000f712a5ce98f212817d20bc16bab10)
|
||||
- After editing your config, the app will rebuild in the background, which may take a minute
|
||||
|
||||
---
|
||||
|
||||
## 4. Further Customisation
|
||||
|
||||
Once you've got Dashy setup, you'll want to ensure the container is properly healthy, secured, backed up and kept up-to-date. All this is covered in the [Management Docs](https://github.com/Lissy93/dashy/blob/master/docs/management.md).
|
||||
|
||||
|
||||
You might also want to check out the docs for specific features you'd like to use:
|
||||
- [Authentication](/docs/authentication.md) - Setting up authentication to protect your dashboard
|
||||
- [Backup & Restore](/docs/backup-restore.md) - Guide to Dashy's cloud sync feature
|
||||
- [Icons](/docs/icons.md) - Outline of all available icon types for sections and items
|
||||
- [Localisation](/docs/multi-language-support.md) - How to change language, or add your own
|
||||
- [Status Indicators](/docs/status-indicators.md) - Using Dashy to monitor uptime and status of your apps
|
||||
- [Theming](/docs/theming.md) - Complete guide to applying, writing and modifying themes and styles
|
||||
|
||||
---
|
||||
|
||||
## 5. Final Note
|
||||
|
||||
If you're enjoying Dashy, and have a few minutes to spare, please do take a moment to look at the [Contributing Page](https://github.com/Lissy93/dashy/blob/master/docs/contributing.md). There are a few things that we really need some help with, and whatever your skill set, there are ways you can help out. Any contributions, however small would be greatly appreciated.
|
||||
Thank you to [everyone](https://github.com/Lissy93/dashy/blob/master/docs/credits.md) who is already doing so, without developing and maintaining Dashy would not have been so possible.
|
||||
|
||||
You can also consider sharing your dashboard in the [Showcase](https://github.com/Lissy93/dashy/blob/master/docs/showcase.md), to help provide inspiration for others.
|
||||
|
||||
For more info, check out the [Documentation](https://github.com/Lissy93/dashy/tree/master/docs#readme). If you've got any questions feel free to ask in the [Discussion](https://github.com/Lissy93/dashy/discussions), and if you think you've found a bug you can [raise an issue](https://github.com/Lissy93/dashy/issues/new/choose) to get it fixed.
|
||||
|
||||
Enjoy your dashboard :)
|
||||
|
||||
---
|
||||
|
||||
## Alternative Deployment Method 1 - From Source
|
||||
|
||||
You can also easily run the app on your system without Docker. For this [Git](https://git-scm.com/downloads), [Node.js](https://nodejs.org/), and [Yarn](https://yarnpkg.com/) are required.
|
||||
|
||||
```
|
||||
git clone https://github.com/Lissy93/dashy.git && cd dashy
|
||||
yarn # Install dependencies
|
||||
yarn build # Build the app
|
||||
yarn start # Start the app
|
||||
```
|
||||
Then edit `./public/conf.yml` and rebuild the app with `yarn build`
|
||||
|
||||
---
|
||||
|
||||
## Alternative Deployment Method 2 - Netlify
|
||||
|
||||
Don't have a server? No problem! You can run Dashy for free on Netlify (as well as many [other cloud providers](./docs/deployment.md#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
|
||||
3. Click "New site from Git" and select your forked repo, then click **Deploy**!
|
||||
4. You can then edit the config in `./public/conf.yml` in your repo, and Netlify will rebuild the app
|
||||
@ -1,7 +1,8 @@
|
||||
|
||||
|
||||
### Running Dashy
|
||||
- [Deployment](/docs/deployment.md) - Getting Dashy up and running
|
||||
- [Quick Start](/docs/quick-start.md) - TDLR guide on getting Dashy up and running
|
||||
- [Deployment](/docs/deployment.md) - Full guide on deploying Dashy either locally or online
|
||||
- [Configuring](/docs/configuring.md) - Complete list of all available options in the config file
|
||||
- [App Management](/docs/management.md) - Managing your app, updating, security, web server configuration, etc
|
||||
- [Troubleshooting](/docs/troubleshooting.md) - Common errors and problems, and how to fix them
|
||||
@ -15,13 +16,14 @@
|
||||
|
||||
### Feature Docs
|
||||
- [Authentication](/docs/authentication.md) - Guide to setting up authentication to protect your dashboard
|
||||
- [Alternate Views](/docs/alternate-views.md) - Outline of available pages / views and item opening methods
|
||||
- [Backup & Restore](/docs/backup-restore.md) - Guide to Dashy's cloud sync feature
|
||||
- [Icons](/docs/icons.md) - Outline of all available icon types for sections and items
|
||||
- [Language Switching](/docs/multi-language-support.md)
|
||||
- [Language Switching](/docs/multi-language-support.md) - Details on how to switch language, or add a new locale
|
||||
- [Status Indicators](/docs/status-indicators.md) - Using Dashy to monitor uptime and status of your apps
|
||||
- [Theming](/docs/theming.md) - Complete guide to applying, writing and modifying themes and styles
|
||||
|
||||
#### Misc
|
||||
### Misc
|
||||
- [Privacy & Security](/docs/privacy.md) - List of requests, potential issues, and security resources
|
||||
- [License](/LICENSE) - Copy of the MIT License
|
||||
- [Legal](/.github/LEGAL.md) - Licenses of direct dependencies
|
||||
|
||||
@ -1,8 +1,41 @@
|
||||
# Troubleshooting
|
||||
|
||||
This document contains common problems and their solutions.
|
||||
## `Refused to Connect` in Modal or Workspace View
|
||||
|
||||
### Yarn Error
|
||||
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:
|
||||
|
||||
### NGINX
|
||||
In NGINX, you can use the [`add_header`](https://nginx.org/en/docs/http/ngx_http_headers_module.html) module within the app block.
|
||||
```
|
||||
server {
|
||||
...
|
||||
add_header X-Frame-Options SAMEORIGIN always;
|
||||
}
|
||||
```
|
||||
Then reload with `service nginx reload`
|
||||
|
||||
### Caddy
|
||||
|
||||
In Caddy, you can use the [`header`](https://caddyserver.com/docs/caddyfile/directives/header) directive.
|
||||
|
||||
```yaml
|
||||
header {
|
||||
X-Frame-Options SAMEORIGIN
|
||||
}
|
||||
```
|
||||
|
||||
### Apache
|
||||
|
||||
In Apache, you can use the [`mod_headers`](https://httpd.apache.org/docs/current/mod/mod_headers.html) module to set the `X-Frame-Options` in your config file. This file is usually located somewhere like `/etc/apache2/httpd.conf
|
||||
|
||||
```
|
||||
Header set X-Frame-Options: "ALLOW-FROM http://[dashy-location]/"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Yarn Error
|
||||
|
||||
For more info, see [Issue #1](https://github.com/Lissy93/dashy/issues/1)
|
||||
|
||||
@ -18,3 +51,45 @@ Alternatively, as a workaround, you have several options:
|
||||
- Try using [NPM](https://www.npmjs.com/get-npm) instead: So clone, cd, then run `npm install`, `npm run build` and `npm start`
|
||||
- Try using [Docker](https://www.docker.com/get-started) instead, and all of the system setup and dependencies will already be taken care of. So from within the directory, just run `docker build -t lissy93/dashy .` to build, and then use docker start to run the project, e.g: `docker run -it -p 8080:80 lissy93/dashy` (see the [deploying docs](https://github.com/Lissy93/dashy/blob/master/docs/deployment.md#deploy-with-docker) for more info)
|
||||
|
||||
---
|
||||
|
||||
## DockerHub `toomanyrequests`
|
||||
|
||||
This situation relates to error messages similar to one of the following, returned when pulling, updating or running the Docker container from Docker Hub.
|
||||
|
||||
```
|
||||
Continuing execution. Pulling image lissy93/dashy:release-1.6.0
|
||||
error pulling image configuration: toomanyrequests
|
||||
```
|
||||
or
|
||||
```
|
||||
You have reached your pull rate limit. You may increase the limit by authenticating and upgrading: https://www.docker.com/increase-rate-limit
|
||||
```
|
||||
|
||||
When DockerHub returns one of these errors, or a `429` status, that means you've hit your rate limit. This was [introduced](https://www.docker.com/blog/scaling-docker-to-serve-millions-more-developers-network-egress/) last year, and prevents unauthenticated or free users from running docker pull more than 100 times per 6 hours.
|
||||
You can [check your rate limit status](https://www.docker.com/blog/checking-your-current-docker-pull-rate-limits-and-status/) by looking for the `ratelimit-remaining` header in any DockerHub responses.
|
||||
|
||||
#### Solution 1 - Use an alternate container registry
|
||||
- Dashy is also availible through GHCR, which at present does not have any hard limits. Just use `docker pull ghcr.io/lissy93/dashy:latest` to fetch the image
|
||||
- You can also build the image from source, by cloning the repo, and running `docker build -t dashy .` or use the pre-made docker compose
|
||||
|
||||
#### Solution 2 - Increase your rate limits
|
||||
- Logging in to DockerHub will increase your rate limit from 100 requests to 200 requests per 6 hour period
|
||||
- Upgrading to a Pro for $5/month will increase your image requests to 5,000 per day, and any plans above have no rate limits
|
||||
- Since rate limits are counted based on your IP address, proxying your requests, or using a VPN may work
|
||||
|
||||
---
|
||||
|
||||
## Config Validation Errors
|
||||
The configuration file is validated against [Dashy's Schema](https://github.com/Lissy93/dashy/blob/master/src/utils/ConfigSchema.json) using AJV.
|
||||
|
||||
First, check that your syntax is valid, using [YAML Validator](https://codebeautify.org/yaml-validator/) or [JSON Validator](https://codebeautify.org/jsonvalidator). If the issue persists, then take a look at the [schema](https://github.com/Lissy93/dashy/blob/master/src/utils/ConfigSchema.json), and verify that the field you are trying to add/ modify matches the required format. You can also use [this tool](https://www.jsonschemavalidator.net/s/JFUj7X9J) to validate your JSON config against the schema, or run `yarn validate-config`.
|
||||
|
||||
If you're trying to use a recently released feature, and are getting a warning, this is likely because you've not yet updated the the current latest version of Dashy.
|
||||
|
||||
If the issue still persists, you should raise an issue.
|
||||
|
||||
---
|
||||
|
||||
## Warnings in the Console during deploy
|
||||
Please acknowledge the difference between errors and warnings before raising an issue about messages in the console. It's not unusual to see warnings about a new version of a certain package being available, an asset bundle bing oversized or a service worker not yet having a cache. These shouldn't have any impact on the running application, so please don't raise issues about these unless it directly relates to a bug or issue you're experiencing. Errors on the other hand should not appear in the console, and they are worth looking into further.
|
||||
|
||||
Loading…
Reference in New Issue
Block a user