From 99463413b1feffb5811e7b2e6a3d2c835059634f Mon Sep 17 00:00:00 2001 From: David Alasow Date: Mon, 22 Aug 2022 17:52:07 +0200 Subject: [PATCH 1/4] Fix formatting in documentation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Removed trailing whitespaces and extra newlines. Added some missing punctuation. Replaced unicode characters that aren't commonly used with the more common character. The replaced unicode characters are - ’ (U+2019) to ' (U+0027) - “ (U+201C) to " (U+0022) - ” (U+201D) to " (U+0022) --- docs/alternate-views.md | 2 +- docs/authentication.md | 16 ++--- docs/backup-restore.md | 2 +- docs/configuring.md | 9 ++- docs/contributing.md | 3 +- docs/deployment.md | 18 ++--- docs/developing.md | 13 ++-- docs/development-guides.md | 12 ++-- docs/icons.md | 8 +-- docs/management.md | 30 ++++---- docs/multi-language-support.md | 4 +- docs/pages-and-sections.md | 2 +- docs/privacy.md | 6 +- docs/quick-start.md | 2 +- docs/readme.md | 2 +- docs/release-workflow.md | 4 +- docs/searching.md | 6 +- docs/showcase.md | 6 +- docs/status-indicators.md | 12 ++-- docs/theming.md | 2 - docs/troubleshooting.md | 24 +++---- docs/widgets.md | 124 ++++++++++++++++----------------- 22 files changed, 151 insertions(+), 156 deletions(-) diff --git a/docs/alternate-views.md b/docs/alternate-views.md index 12d30b6e..268ddfb2 100644 --- a/docs/alternate-views.md +++ b/docs/alternate-views.md @@ -49,7 +49,7 @@ Dashy supports several different ways to launch your apps. The primary opening m You can also set a default opening method, which will be applied to all items that don't have a specified target, using `appConfig.defaultOpeningMethod`, to one of the above values. -Even if the target is not set (or is set to `sametab`), you can still launch any given app in an alternative method. Either right-click to see all options, or use one of the keyboard shortcuts: Alt + Click will open the modal, and Ctrl + Click will open in a new tab. +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.

diff --git a/docs/authentication.md b/docs/authentication.md index 080d9b7d..cdcc782d 100644 --- a/docs/authentication.md +++ b/docs/authentication.md @@ -22,7 +22,7 @@ Dashy has a basic login page included, and frontend authentication. You can enable this by adding users to the `auth` section under `appConfig` in your `conf.yml`. If this section is not specified, then no authentication will be required to access the app, and it the homepage will resolve to your dashboard. ### Setting Up Authentication -The `auth` property takes an array of users. Each user needs to include a username, hash and optional user type (`admin` or `normal`). The hash property is a [SHA-256 Hash](https://en.wikipedia.org/wiki/SHA-2) of your desired password. +The `auth` property takes an array of users. Each user needs to include a username, hash and optional user type (`admin` or `normal`). The hash property is a [SHA-256 Hash](https://en.wikipedia.org/wiki/SHA-2) of your desired password. For example: ```yaml @@ -118,7 +118,7 @@ You should now be able to access the Keycloak web interface, using the port spec ### 2. Setup Keycloak Users -Before we can use Keycloak, we must first set it up with some users. Keycloak uses Realms (similar to tenants) to create isolated groups of users. You must create a Realm before you will be able to add your first user. +Before we can use Keycloak, we must first set it up with some users. Keycloak uses Realms (similar to tenants) to create isolated groups of users. You must create a Realm before you will be able to add your first user. 1. Head over to the admin console 2. In the top-left corner there is a dropdown called 'Master', hover over it and then click 'Add Realm' 3. Give your realm a name, and hit 'Create' @@ -189,8 +189,8 @@ If you are self-hosting Dashy, and require secure authentication to prevent unau - [Password Protection (for cloud providers)](#static-site-hosting-providers) - Enable password-protection on your site ### Authentication Server -##### Authelia -[Authelia](https://www.authelia.com/) is an open-source full-featured authentication server, which can be self-hosted and either on bare metal, in a Docker container or in a Kubernetes cluster. It allows for fine-grained access control rules based on IP, path, users etc, and supports 2FA, simple password access or bypass policies for your domains. +##### Authelia +[Authelia](https://www.authelia.com/) is an open-source full-featured authentication server, which can be self-hosted and either on bare metal, in a Docker container or in a Kubernetes cluster. It allows for fine-grained access control rules based on IP, path, users etc, and supports 2FA, simple password access or bypass policies for your domains. - `git clone https://github.com/authelia/authelia.git` - `cd authelia/examples/compose/lite` @@ -230,7 +230,7 @@ server { ``` ##### Caddy -In Caddy, [Request Matchers](https://caddyserver.com/docs/caddyfile/matchers) can be used to filter requests +In Caddy, [Request Matchers](https://caddyserver.com/docs/caddyfile/matchers) can be used to filter requests ``` dashy.site { @public_networks not remote_ip [your-ip] @@ -244,9 +244,9 @@ Most web servers make password protecting certain apps very easy. Note that you ##### Apache First crate a `.htaccess` file in Dashy's route directory. Specify the auth type and path to where you want to store the password file (usually the same folder). For example: ``` -AuthType Basic -AuthName "Please Sign into Dashy" -AuthUserFile /path/dashy/.htpasswd +AuthType Basic +AuthName "Please Sign into Dashy" +AuthUserFile /path/dashy/.htpasswd require valid-user ``` diff --git a/docs/backup-restore.md b/docs/backup-restore.md index 2c6b2158..06d4b565 100644 --- a/docs/backup-restore.md +++ b/docs/backup-restore.md @@ -17,7 +17,7 @@ All data is encrypted before being sent to the backend. In Dashy, this is done i Once you've got Dashy configured to your preference, open the Backup & Restore menu (click the Cloud icon in the top-right corner). Here you will be prompted to choose a password, which will be used to encrypt your data. If you forget this password, there will be no way to recover your config. After clicking 'Backup' your data will be encrypted, compressed and sent to the hosted cloud service. A backup ID will be returned (in the format of xxxx-xxxx-xxxx-xxxx), this is what you use, along with your password to restore the backup on another system, so take note of it. To update a backup, return to this menu, enter your password, and click 'Update Backup'. ### Restoring a Backup -To restore a backup, navigate to the Backup & Restore menu, and under restore, enter your backup ID, and the password you chose. Your config file will be downloaded, decrypted and applied to local storage. +To restore a backup, navigate to the Backup & Restore menu, and under restore, enter your backup ID, and the password you chose. Your config file will be downloaded, decrypted and applied to local storage. ### Privacy & Security diff --git a/docs/configuring.md b/docs/configuring.md index 95c885b4..e4c19ad5 100644 --- a/docs/configuring.md +++ b/docs/configuring.md @@ -219,7 +219,7 @@ For more info, see the **[Authentication Docs](/docs/authentication.md)** **`tags`** | `string[]` | _Optional_ | A list of tags, which can be used for improved search **`statusCheck`** | `boolean` | _Optional_ | When set to `true`, Dashy will ping the URL associated with the current service, and display its status as a dot next to the item. The value here will override `appConfig.statusCheck` so you can turn off or on checks for a given service. Defaults to `appConfig.statusCheck`, falls back to `false` **`statusCheckUrl`** | `string` | _Optional_ | If you've enabled `statusCheck`, and want to use a different URL to what is defined under the item, then specify it here -**`statusCheckHeaders`** | `object` | _Optional_ | If you're endpoint requires any specific headers for the status checking, then define them here +**`statusCheckHeaders`** | `object` | _Optional_ | If you're endpoint requires any specific headers for the status checking, then define them here **`statusCheckAllowInsecure`** | `boolean` | _Optional_ | By default, any request to insecure content will be blocked. Setting this option to `true` will disable the `rejectUnauthorized` option, enabling you to ping non-HTTPS services for the current item. Defaults to `false` **`statusCheckAcceptCodes`** | `string` | _Optional_ | If your service's response code is anything other than 2xx, then you can opt to specify an alternative success code. E.g. if you expect your server to return 403, but still want the status indicator to be green, set this value to `403` **`statusCheckMaxRedirects`** | `number` | _Optional_ | If your service redirects to another page, and you would like status checks to follow redirects, then specify the maximum number of redirects here. Defaults to `0` / will not follow redirects @@ -254,7 +254,7 @@ For more info, see the **[Authentication Docs](/docs/authentication.md)** **`useProxy`** | `boolean` | _Optional_ | Some widgets make API requests to services that are not CORS-enabled. For these instances, you will need to route requests through a proxy, Dashy has a built in CORS-proxy, which you can use by setting this option to `true`. Defaults to `false`. See the [Proxying Requests Docs](/docs/widgets.md#proxying-requests) for more info **`timeout`** | `number` | _Optional_ | Request timeout in milliseconds, defaults to ½ a second (`500`) **`ignoreErrors`** | `boolean` | _Optional_ | Prevent an error message being displayed, if a network request or something else fails. Useful for false-positives -**`label`** | `string` | _Optional_ | Add custom label to a given widget. Useful for identification, if there are multiple of the same type of widget in a single section +**`label`** | `string` | _Optional_ | Add custom label to a given widget. Useful for identification, if there are multiple of the same type of widget in a single section **[⬆️ Back to Top](#configuring)** @@ -325,7 +325,7 @@ If you're new to YAML, it's pretty straight-forward. The format is exactly the s ### Config Saving Methods When updating the config through the JSON editor in the UI, you have two save options: **Local** or **Write to Disk**. - Changes saved locally will only be applied to the current user through the browser, and will not apply to other instances - you either need to use the cloud sync feature, or manually update the conf.yml file. -- On the other-hand, if you choose to write changes to disk, then your main `conf.yml` file will be updated, and changes will be applied to all users, and visible across all devices. For this functionality to work, you must be running Dashy with using the Docker container, or the Node server. A backup of your current configuration will also be saved in the same directory. +- On the other-hand, if you choose to write changes to disk, then your main `conf.yml` file will be updated, and changes will be applied to all users, and visible across all devices. For this functionality to work, you must be running Dashy with using the Docker container, or the Node server. A backup of your current configuration will also be saved in the same directory. ### Preventing Changes @@ -355,7 +355,7 @@ sections: # An array of sections - title: Demo description: A live demo icon: far fa-rocket - url: https://dashy-demo-1.netlify.app + url: https://dashy-demo-1.netlify.app - name: Section 2 - Local Services items: - title: Firewall @@ -373,4 +373,3 @@ If you need any help, feel free to [Raise an Issue](https://github.com/Lissy93/d Happy Configuring 🤓🔧 **[⬆️ Back to Top](#configuring)** - diff --git a/docs/contributing.md b/docs/contributing.md index 8898cb08..aa1cf5c3 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -40,7 +40,7 @@ Sponsoring will give you several perks - for $1 / £0.75 per month, you'll get a ## Enable Anonymous Bug Reports -Bug reports helps me to discover bugs I was unaware of, and then fix them, in order to make Dashy more reliable long term. This is a simple, yet really helpful step you can take to help improve Dashy. [Sentry](https://github.com/getsentry/sentry) is an open source error tracking and performance monitoring tool, which enables the identification any errors which occur in the production app (only if you enable it). +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 @@ -122,4 +122,3 @@ For a full list of Dashy's contributors, see the [Credits Page](/docs/credits.md ### Star-Gazers Over Time [![Stargazers](https://starchart.cc/Lissy93/dashy.svg)](https://seladb.github.io/StarTrack-js/#/preload?r=Lissy93,dashy) - diff --git a/docs/deployment.md b/docs/deployment.md index e9710e6a..02b74906 100644 --- a/docs/deployment.md +++ b/docs/deployment.md @@ -66,7 +66,7 @@ For all available options, and to learn more, see the [Docker Run Docs](https:// 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. +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` @@ -128,11 +128,11 @@ Installing dashy is really simply and fast: 2. Go to ```File Station``` and open the ```docker``` folder. Inside the docker folder, create one new folder and name it ```dashy```. > Note: Be careful to enter only lowercase, not uppercase letters. 3. Go to Control Panel / Task Scheduler / Create / Scheduled Task / User-defined script. -4. Once you click on ```User-defined``` script a new window will open. +4. Once you click on ```User-defined``` script a new window will open. 5. Follow the instructions below: -6. General: In the Task field type in Install dashy. Uncheck “Enabled” option. Select root User. -7. Schedule: Select Run on the following date then select “Do not repeat“. -8. Task Settings: Check “Send run details by email“, add your email then copy paste the code below in the Run command area. After that click OK. +6. General: In the Task field type in Install dashy. Uncheck "Enabled" option. Select root User. +7. Schedule: Select Run on the following date then select "Do not repeat". +8. Task Settings: Check "Send run details by email", add your email then copy paste the code below in the Run command area. After that click OK. ``` docker run -d \ @@ -247,7 +247,7 @@ https://render.com/deploy?repo=https://github.com/lissy93/dashy/tree/deploy_rend #### Scalingo [![Deploy on Scalingo](https://i.ibb.co/nj0KxyH/deploy-scalingo-button.png)](https://my.scalingo.com/deploy?source=https://github.com/lissy93/dashy#master) -[Scalingo](https://scalingo.com/) is a scalable container-based cloud platform as a service. It's focus is on compliance and uptime, and is geared towards enterprise users. Scalingo is also not free, although they do have a 3-day free trial that does not require a payment method +[Scalingo](https://scalingo.com/) is a scalable container-based cloud platform as a service. It's focus is on compliance and uptime, and is geared towards enterprise users. Scalingo is also not free, although they do have a 3-day free trial that does not require a payment method. To deploy Dashy to Scalingo, use the following link ``` @@ -295,13 +295,13 @@ However without Dashy's node server, there are a couple of features that will be Dashy works well on a Raspberry Pi (tested on Pi 3 and later), but should also run well on any system. ### Docker -Initial app build causes a spike in resource usage, but once the built app is running it is fairly steady. For this reason, Dashy works best with a minimum of 1GB of memory, and 1GB of disk space. +Initial app build causes a spike in resource usage, but once the built app is running it is fairly steady. For this reason, Dashy works best with a minimum of 1GB of memory, and 1GB of disk space. ### Bare Metal -Minimum 526mb mem, 2GB disk space, +Minimum 526mb mem, 2GB disk space. ### CDN / Cloud Deploy -No specific requirements. The built application alone (without the Node server) is very light-weight, and can be handled smoothly by pretty much any CDN or cloud deployment service (see [this list](/docs/deployment.md#deploy-to-cloud-service) or natively supported cloud providers). +No specific requirements. The built application alone (without the Node server) is very light-weight, and can be handled smoothly by pretty much any CDN or cloud deployment service (see [this list](/docs/deployment.md#deploy-to-cloud-service) or natively supported cloud providers). If you're using your own icons, or other assets, additional disk space will be required for those resources. diff --git a/docs/developing.md b/docs/developing.md index edd98f5f..2f2f0905 100644 --- a/docs/developing.md +++ b/docs/developing.md @@ -58,7 +58,7 @@ Dashy should now be being served on http://localhost:8080/. Hot reload is enable #### Notes - If you are using NPM, replace `yarn` with `npm run` - If you are using Docker, precede each command with `docker exec -it [container-id]`. Container ID can be found by running `docker ps` -- You can manage the app using the [Vue-CLI Service](https://cli.vuejs.org/guide/cli-service.html), with `npx vue-cli-service [command]`. Or to start the Vue Management UI, run `npx vue ui`, and open `http://localhost:8000` +- You can manage the app using the [Vue-CLI Service](https://cli.vuejs.org/guide/cli-service.html), with `npx vue-cli-service [command]`. Or to start the Vue Management UI, run `npx vue ui`, and open `http://localhost:8000` ### Environmental Variables All environmental variables are optional. Currently there are not many environmental variables used, as most of the user preferences are stored under `appConfig` in the `conf.yml` file. @@ -158,7 +158,7 @@ New to Web Development? Glad you're here! Dashy is a pretty simple app, so it sh - [Git cheat sheet](http://git-cheatsheet.com/) - [Basics of using NPM](https://www.freecodecamp.org/news/what-is-npm-a-node-package-manager-tutorial-for-beginners/) -As well as Node, Git and Docker- you'll also need an IDE (e.g. [VS Code](https://code.visualstudio.com/) or [Vim](https://www.vim.org/)) and a terminal (Windows users may find [WSL](https://docs.microsoft.com/en-us/windows/wsl/) more convenient). +As well as Node, Git and Docker- you'll also need an IDE (e.g. [VS Code](https://code.visualstudio.com/) or [Vim](https://www.vim.org/)) and a terminal (Windows users may find [WSL](https://docs.microsoft.com/en-us/windows/wsl/) more convenient). --- @@ -175,13 +175,13 @@ The most significant things to note are: - The final element in all objects must be preceded with a comma - Maximum line length is 100 - There must be exactly one blank line between sections, before function names, and at the end of the file -- With conditionals, put else on the same line as your if block’s closing brace +- With conditionals, put else on the same line as your if block's closing brace - All multiline blocks must use braces - Avoid console statements in the frontend Styleguides: - Vue: [Vue styleguide](https://vuejs.org/v2/style-guide/) -- JavaScript: [github.com/airbnb/javascript](https://github.com/airbnb/javascript) +- JavaScript: [github.com/airbnb/javascript](https://github.com/airbnb/javascript) --- @@ -213,7 +213,7 @@ Styleguides: ├── assets # Static non-compiled assets │ ├── fonts # .ttf font files │ ├── locales # All app text, each language in a separate JSON file -│ ╰── interface-icons # SVG icons used in the app +│ ╰── 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 @@ -250,7 +250,7 @@ Styleguides: │ │ ├── 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 +│ │ ├── 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 @@ -356,4 +356,3 @@ When running the build command, several warnings appear. These are not errors, a `WARN A new version of sass-loader is available. Please upgrade for best experience.` - Currently we're using an older version of SASS loader, since the more recent releases do not seem to be compatible with the Vue CLI's webpack configuration. `WARN asset size limit: The following asset(s) exceed the recommended size limit (244 KiB).` - For the PWA to support Windows 10, a splash screen asset is required, and is quite large. This throws a warning, however PWA assets are not loaded until needed, so shouldn't have any impact on application performance. A similar warning is thrown for the Raleway font, and that is looking to be addressed. - diff --git a/docs/development-guides.md b/docs/development-guides.md index 4f2256c8..cba17f0c 100644 --- a/docs/development-guides.md +++ b/docs/development-guides.md @@ -1,6 +1,6 @@ # Development Guides -A series of short tutorials, to guide you through the most common development tasks. +A series of short tutorials, to guide you through the most common development tasks. Sections: - [Creating a new theme](#creating-a-new-theme) @@ -18,10 +18,10 @@ Sections: Adding a new theme is really easy. There's two things you need to do: Pass the theme name to Dashy, so that it can be added to the theme selector dropdown menu, and then write some styles! ##### 1. Add Theme Name -Choose a snappy name for you're theme, and add it to the `builtInThemes` array inside [`defaults.js`](https://github.com/Lissy93/dashy/blob/master/src/utils/defaults.js#L27). +Choose a snappy name for you're theme, and add it to the `builtInThemes` array inside [`defaults.js`](https://github.com/Lissy93/dashy/blob/master/src/utils/defaults.js#L27). ##### 2. Write some Styles! -Put your theme's styles inside [`color-themes.scss`](https://github.com/Lissy93/dashy/blob/master/src/styles/color-themes.scss). +Put your theme's styles inside [`color-themes.scss`](https://github.com/Lissy93/dashy/blob/master/src/styles/color-themes.scss). Create a new block, and make sure that `data-theme` matches the theme name you chose above. For example: ```css @@ -91,7 +91,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! -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. +If you are not comfortable with making pull requests, or do not want to modify the code, then feel free to instead send the translated file to me, and I can add it into the application. I will be sure to credit you appropriately. # Adding a new option in the config file @@ -144,7 +144,7 @@ or Finally, add your new property to the [`configuring.md`](./configuring.md) API docs. Put it under the relevant section, and be sure to include field name, data type, a description and mention that it is optional. If your new feature needs more explaining, then you can also document it under the relevant section elsewhere in the documentation. Checklist: -- [ ] Ensure the new attribute is actually necessary, and nothing similar already exists +- [ ] Ensure the new attribute is actually necessary, and nothing similar already exists - [ ] Update the [Schema](https://github.com/Lissy93/dashy/blob/master/src/utils/ConfigSchema.js) with the parameters for your new option - [ ] If required, set a default or fallback value (usually in [`defaults.js`](https://github.com/Lissy93/dashy/blob/master/src/utils/defaults.js)) - [ ] Document the new value in [`configuring.md`](./configuring.md), and if required under the relevant section in the docs @@ -219,7 +219,7 @@ export default { }, }; ``` - + Finally, in the markup of your component, just add a `v-if` statement, referencing your computed value ```vue

diff --git a/docs/icons.md b/docs/icons.md index 1a620a51..6440e2e4 100644 --- a/docs/icons.md +++ b/docs/icons.md @@ -58,7 +58,7 @@ Font-Awesome has a wide variety of free icons, but you can also use their pro ic --- ## Simple Icons -[SimpleIcons.org](https://simpleicons.org/) is a collection of 2000+ high quality, free and open source brand and logo SVG icons. Usage of which is very similar to font-awesome icons. First find the glyph you want to use on the [website](https://simpleicons.org/), then just set your icon the the simple icon slug, prefixed with `si-`. +[SimpleIcons.org](https://simpleicons.org/) is a collection of 2000+ high quality, free and open source brand and logo SVG icons. Usage of which is very similar to font-awesome icons. First find the glyph you want to use on the [website](https://simpleicons.org/), then just set your icon the the simple icon slug, prefixed with `si-`.

@@ -136,11 +136,11 @@ sections: - name: Material Design Icons Example items: - title: Alien Icon - icon: mdi-alien + icon: mdi-alien - title: Fire Icon - icon: mdi-fire + icon: mdi-fire - title: Dino Icon - icon: mdi-google-downasaur + icon: mdi-google-downasaur ```

diff --git a/docs/management.md b/docs/management.md index 14f8dae9..ce73db2b 100644 --- a/docs/management.md +++ b/docs/management.md @@ -143,7 +143,7 @@ You can make a backup of any running container really easily, using [`docker com Note that this will not include any data in docker volumes, and the process here is a bit different. Since these files exist on your host system, if you have an existing backup solution implemented, you can incorporate and volume files within that system. ### Backing Up Volumes -[offen/docker-volume-backup](https://github.com/offen/docker-volume-backup) is a useful tool for periodic Docker volume backups, to any S3-compatible storage provider. It's run as a light-weight Docker container, and is easy to setup, and also supports GPG-encryption, email notification, and routing away older backups. +[offen/docker-volume-backup](https://github.com/offen/docker-volume-backup) is a useful tool for periodic Docker volume backups, to any S3-compatible storage provider. It's run as a light-weight Docker container, and is easy to setup, and also supports GPG-encryption, email notification, and routing away older backups. To get started, create a docker-compose similar to the example below, and then start the container. For more info, check out their [documentation](https://github.com/offen/docker-volume-backup), which is very clear. @@ -201,7 +201,7 @@ Enabling HTTPS with an SSL certificate is recommended, especially if you are hos ### Auto-SSL If you are using [NGINX Proxy Manager](https://nginxproxymanager.com/), then SSL is supported out of the box. Once you've added your proxy host and web address, then set the scheme to HTTPS, then under the SSL Tab select "Request a new SSL certificate" and follow the on-screen instructions. -If you're hosting Dashy behind Cloudflare, then they offer [free and easy SSL](https://www.cloudflare.com/en-gb/learning/ssl/what-is-an-ssl-certificate/)- all you need to do is enable it under the SSL/TLS tab. Or if you are using shared hosting, you may find [this tutorial](https://www.sitepoint.com/a-guide-to-setting-up-lets-encrypt-ssl-on-shared-hosting/) helpful. +If you're hosting Dashy behind Cloudflare, then they offer [free and easy SSL](https://www.cloudflare.com/en-gb/learning/ssl/what-is-an-ssl-certificate/)- all you need to do is enable it under the SSL/TLS tab. Or if you are using shared hosting, you may find [this tutorial](https://www.sitepoint.com/a-guide-to-setting-up-lets-encrypt-ssl-on-shared-hosting/) helpful. ### Getting a Self-Signed SSL Certificate [Let's Encrypt](https://letsencrypt.org/docs/) is a global Certificate Authority, providing free SSL/TLS Domain Validation certificates in order to enable secure HTTPS access to your website. They have good browser/ OS [compatibility](https://letsencrypt.org/docs/certificate-compatibility/) with their ISRG X1 and DST CA X3 root certificates, support [Wildcard issuance](https://community.letsencrypt.org/t/acme-v2-production-environment-wildcards/55578) done via ACMEv2 using the DNS-01 and have [Multi-Perspective Validation](https://letsencrypt.org/2020/02/19/multi-perspective-validation.html). Let's Encrypt provide [CertBot](https://certbot.eff.org/) an easy app for generating and setting up an SSL certificate. @@ -325,7 +325,7 @@ headers / { ``` location / { - add_header Access-Control-Allow-Origin *; + add_header Access-Control-Allow-Origin *; } ``` @@ -380,7 +380,7 @@ request_header_access Authorization allow all ### WireGuard -Using a VPN is one of the easiest ways to provide secure, full access to your local network from remote locations. [WireGuard](https://www.wireguard.com/) is a reasonably new open source VPN protocol, that was designed with ease of use, performance and security in mind. Unlike OpenVPN, it doesn't need to recreate the tunnel whenever connection is dropped, and it's also much easier to setup, using shared keys instead. +Using a VPN is one of the easiest ways to provide secure, full access to your local network from remote locations. [WireGuard](https://www.wireguard.com/) is a reasonably new open source VPN protocol, that was designed with ease of use, performance and security in mind. Unlike OpenVPN, it doesn't need to recreate the tunnel whenever connection is dropped, and it's also much easier to setup, using shared keys instead. - **Install Wireguard** - See the [Install Docs](https://www.wireguard.com/install/) for download links + instructions - On Debian-based systems, it's `sudo apt install wireguard` @@ -457,7 +457,7 @@ A useful tool for getting WG setup is [Algo](https://github.com/trailofbits/algo SSH (or [Secure Shell](https://en.wikipedia.org/wiki/Secure_Shell)) is a secure tunnel that allows you to connect to a remote host. Unlike the VPN methods, an SSH connection does not require an intermediary, and will not be affected by your IP changing. However it only allows you to access a single service at a time. SSH was really designed for terminal access, but because of the latter mentioned benefits it's useful to setup, as a fallback option. -Directly SSH'ing into your home, would require you to open a port (usually 22), which would be terrible for security, and is not recommended. However a reverse SSH connection is initiated from inside your network. Once the connection is established, the port is redirected, allowing you to use the established connection to SSH into your home network. +Directly SSH'ing into your home, would require you to open a port (usually 22), which would be terrible for security, and is not recommended. However a reverse SSH connection is initiated from inside your network. Once the connection is established, the port is redirected, allowing you to use the established connection to SSH into your home network. The issue you've probably spotted, is that most public, corporate, and institutional networks will block SSH connections. To overcome this, you'd have to establish a server outside of your homelab that your homelab's device could SSH into to establish the reverse SSH connection. You can then connect to that remote server (the _mothership_), which in turn connects to your home network. @@ -482,13 +482,13 @@ Done :) ### TCP Tunnel -If you're running Dashy on your local network, behind a firewall, but need to temporarily share it with someone external, this can be achieved quickly and securely using [Ngrok](https://ngrok.com/). It’s basically a super slick, encrypted TCP tunnel that provides an internet-accessible address that anyone use to access your local service, from anywhere. +If you're running Dashy on your local network, behind a firewall, but need to temporarily share it with someone external, this can be achieved quickly and securely using [Ngrok](https://ngrok.com/). It's basically a super slick, encrypted TCP tunnel that provides an internet-accessible address that anyone use to access your local service, from anywhere. To get started, [Download](https://ngrok.com/download) and install Ngrok for your system, then just run `ngrok http [port]` (replace the port with the http port where Dashy is running, e.g. 8080). When [using https](https://ngrok.com/docs#http-local-https), specify the full local url/ ip including the protocol. -Some Ngrok features require you to be authenticated, you can [create a free account](https://dashboard.ngrok.com/signup) and generate a token in [your dashboard](https://dashboard.ngrok.com/auth/your-authtoken), then run `ngrok authtoken [token]`. +Some Ngrok features require you to be authenticated, you can [create a free account](https://dashboard.ngrok.com/signup) and generate a token in [your dashboard](https://dashboard.ngrok.com/auth/your-authtoken), then run `ngrok authtoken [token]`. -It's recommended to use authentication for any publicly accessible service. Dashy has an [Auth](/docs/authentication.md) feature built in, but an even easier method it to use the [`-auth`](https://ngrok.com/docs#http-auth) switch. E.g. `ngrok http -auth=”username:password123” 8080` +It's recommended to use authentication for any publicly accessible service. Dashy has an [Auth](/docs/authentication.md) feature built in, but an even easier method it to use the [`-auth`](https://ngrok.com/docs#http-auth) switch. E.g. `ngrok http -auth="username:password123" 8080` By default, your web app is assigned a randomly generated ngrok domain, but you can also use your own custom domain. Under the [Domains Tab](https://dashboard.ngrok.com/endpoints/domains) of your Ngrok dashboard, add your domain, and follow the CNAME instructions. You can now use your domain, with the [`-hostname`](https://ngrok.com/docs#http-custom-domains) switch, e.g. `ngrok http -region=us -hostname=dashy.example.com 8080`. If you don't have your own domain name, you can instead use a custom sub-domain (e.g. `alicia-dashy.ngrok.io`), using the [`-subdomain`](https://ngrok.com/docs#custom-subdomain-names) switch. @@ -512,7 +512,7 @@ For locally running services, a domain can be set up directly in the DNS records If you're using Pi-Hole, a similar thing can be done in the `/etc/dnsmasq.d/03-custom-dns.conf` file, add a line like: `address=/dashy.example.com/192.168.2.0` for each of your services. -If you're running OPNSense/ PfSense, then this can be done through the UI with Unbound, it's explained nicely in [this article](https://homenetworkguy.com/how-to/use-custom-domain-name-in-internal-network/), by Dustin Casto. +If you're running OPNSense/ PfSense, then this can be done through the UI with Unbound, it's explained nicely in [this article](https://homenetworkguy.com/how-to/use-custom-domain-name-in-internal-network/), by Dustin Casto. ### Using NGINX If you're using NGINX, then you can use your own domain name, with a config similar to the below example. @@ -592,7 +592,7 @@ Running a container with admin privileges gives it more power than it needs, and Note that if you're facing permission issues on Debian-based systems, you may need to add your user to the Docker group. First create the group: `sudo groupadd docker`, then add your (non-root) user: `sudo usermod −aG docker [my-username]`, finally `newgrp docker` to refresh. ### Specify a User -One of the best ways to prevent privilege escalation attacks, is to configure the container to use an unprivileged user. This also means that any files created by the container and mounted, will be owned by the specified user (and not root), which makes things much easier. +One of the best ways to prevent privilege escalation attacks, is to configure the container to use an unprivileged user. This also means that any files created by the container and mounted, will be owned by the specified user (and not root), which makes things much easier. You can specify a user, using the [`--user` param](https://docs.docker.com/engine/reference/run/#user), and should include the user ID (`UID`), which can be found by running `id -u`, and the and the group ID (`GID`), using `id -g`. @@ -608,11 +608,11 @@ services: image: lissy93/dashy user: ${CURRENT_UID} ports: [ 4000:80 ] -``` +``` And then to set the variable, and start the container, run: `CURRENT_UID=$(id -u):$(id -g) docker-compose up` -### Limit capabilities +### Limit capabilities Docker containers run with a subset of [Linux Kernal's Capabilities](https://man7.org/linux/man-pages/man7/capabilities.7.html) by default. It's good practice to drop privilege permissions that are not needed for any given container. With Docker run, you can use the `--cap-drop` flag to remove capabilities, you can also use `--cap-drop=all` and then define just the required permissions using the `--cap-add` option. For a list of available capabilities, see the [Privilege Capabilities Docs](https://docs.docker.com/engine/reference/run/#runtime-privilege-and-linux-capabilities). @@ -635,7 +635,7 @@ services: - SETUID - DAC_OVERRIDE - NET_BIND_SERVICE -``` +``` ### Prevent new Privilages being Added To prevent processes inside the container from getting additional privileges, pass in the `--security-opt=no-new-privileges:true` option to the Docker run command (see [docs](https://docs.docker.com/engine/reference/run/#security-configuration)). @@ -675,7 +675,7 @@ You can also prevent a container from writing any changes to volumes on your hos Logging is important, as it enables you to review events in the future, and in the case of a compromise this will let get an idea of what may have happened. The default log level is `INFO`, and this is also the recommendation, use `--log-level info` to ensure this is set. ### Verify Image before Pulling -Only use trusted images, from verified/ official sources. If an app is open source, it is more likely to be safe, as anyone can verify the code. There are also tools available for scanning containers, +Only use trusted images, from verified/ official sources. If an app is open source, it is more likely to be safe, as anyone can verify the code. There are also tools available for scanning containers, Unless otherwise configured, containers can communicate among each other, so running one bad image may lead to other areas of your setup being compromised. Docker images typically contain both original code, as well as up-stream packages, and even if that image has come from a trusted source, the up-stream packages it includes may not have. @@ -697,7 +697,7 @@ Docker supports several modules that let you write your own security profiles. [AppArmor](https://www.apparmor.net/)is a kernel module that proactively protects the operating system and applications from external or internal threats, by enabling you to restrict programs' capabilities with per-program profiles. You can specify either a security policy by name, or by file path with the `apparmor` flag in docker run. Learn more about writing profiles, [here](https://gitlab.com/apparmor/apparmor/-/wikis/QuickProfileLanguage). -[Seccomp](https://en.wikipedia.org/wiki/Seccomp) (Secure Computing Mode) is a sandboxing facility in the Linux kernel that acts like a firewall for system calls (syscalls). It uses Berkeley Packet Filter (BPF) rules to filter syscalls and control how they are handled. These filters can significantly limit a containers access to the Docker Host’s Linux kernel - especially for simple containers/applications. It requires a Linux-based Docker host, with secomp enabled, and you can check for this by running `docker info | grep seccomp`. A great resource for learning more about this is [DockerLabs](https://training.play-with-docker.com/security-seccomp/). +[Seccomp](https://en.wikipedia.org/wiki/Seccomp) (Secure Computing Mode) is a sandboxing facility in the Linux kernel that acts like a firewall for system calls (syscalls). It uses Berkeley Packet Filter (BPF) rules to filter syscalls and control how they are handled. These filters can significantly limit a containers access to the Docker Host's Linux kernel - especially for simple containers/applications. It requires a Linux-based Docker host, with secomp enabled, and you can check for this by running `docker info | grep seccomp`. A great resource for learning more about this is [DockerLabs](https://training.play-with-docker.com/security-seccomp/). **[⬆️ Back to Top](#management)** diff --git a/docs/multi-language-support.md b/docs/multi-language-support.md index 44eb2cc2..49b09a17 100644 --- a/docs/multi-language-support.md +++ b/docs/multi-language-support.md @@ -36,7 +36,7 @@ Dashy is using [vue-i18n](https://vue-i18n.intlify.dev/guide/) to manage multi-l 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` for your language. +Create a new JSON file in `./src/assets/locales` for your language. You should name it with the 2-digit [ISO-639 code](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) for your locale (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 translation, then use the Posfix [CLDR](http://cldr.unicode.org/) format, where, e.g. `en-GB.json` (British English), `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) @@ -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! -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. +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. --- diff --git a/docs/pages-and-sections.md b/docs/pages-and-sections.md index f55c62f6..8dfe00eb 100644 --- a/docs/pages-and-sections.md +++ b/docs/pages-and-sections.md @@ -4,7 +4,7 @@ You can have additional pages within your dashboard, with each having it's own config file. The config files for sub-pages can either be stored locally, or hosted separately. A link to each additional page will be displayed in the navigation bar. -You can edit additional pages using the interactive editor, exactly the same was as your primary page (so long as it's local). But please save changes to one page, before you start editing the next. +You can edit additional pages using the interactive editor, exactly the same was as your primary page (so long as it's local). But please save changes to one page, before you start editing the next. ### Using Local Sub-Pages diff --git a/docs/privacy.md b/docs/privacy.md index 5b56d935..6945f8ed 100644 --- a/docs/privacy.md +++ b/docs/privacy.md @@ -83,7 +83,7 @@ Dashy has a primitive [web search feature](https://github.com/Lissy93/dashy/blob This feature can be disabled under appConfig, with `webSearch: { disableWebSearch: 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 code isn't even 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, used to identify any issues 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 code isn't even 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, 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/). @@ -164,7 +164,7 @@ The following section outlines all data that is stored in the browsers, as cooki #### Cookies > [Cookies](https://en.wikipedia.org/wiki/HTTP_cookie) will expire after their pre-defined lifetime -- `AUTH_TOKEN` - A unique token, generated from a hash of users credentials, to verify they are authenticated. Only used when auth is enabled +- `AUTH_TOKEN` - A unique token, generated from a hash of users credentials, to verify they are authenticated. Only used when auth is enabled. #### Session Storage > [Session storage](https://developer.mozilla.org/en-US/docs/Web/API/Window/sessionStorage) is deleted when the current session ends (tab / window is closed) @@ -229,7 +229,7 @@ This is covered in more detail in [App Management](/docs/management.md). ## Security Features #### Subresource Integrity -[Subresource Integrity](https://developer.mozilla.org/en-US/docs/Web/Security/Subresource_Integrity) or SRI is a security feature that enables browsers to verify that resources they fetch are delivered without unexpected manipulation. It works by allowing you to provide a cryptographic hash that a fetched resource must match. This prevents the app from loading any resources that have been manipulated, by verifying the files hashes. It safeguards against the risk of an attacker injecting arbitrary malicious content into any files served up via a CDN. +[Subresource Integrity](https://developer.mozilla.org/en-US/docs/Web/Security/Subresource_Integrity) or SRI is a security feature that enables browsers to verify that resources they fetch are delivered without unexpected manipulation. It works by allowing you to provide a cryptographic hash that a fetched resource must match. This prevents the app from loading any resources that have been manipulated, by verifying the files hashes. It safeguards against the risk of an attacker injecting arbitrary malicious content into any files served up via a CDN. Dashy supports SRI, and it is recommended to enable this if you are hosting your dashboard via a public CDN. To enable SRI, set the `INTEGRITY` environmental variable to `true`. diff --git a/docs/quick-start.md b/docs/quick-start.md index 7041fc76..7468ca78 100644 --- a/docs/quick-start.md +++ b/docs/quick-start.md @@ -101,7 +101,7 @@ If you need any help or support in getting Dashy running, head over to the [Disc 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). Huge thanks to [everyone](https://github.com/Lissy93/dashy/blob/master/docs/credits.md) who has already helped out! -Enjoy your dashboard :) +Enjoy your dashboard :) --- diff --git a/docs/readme.md b/docs/readme.md index b67b92c2..6aed6541 100644 --- a/docs/readme.md +++ b/docs/readme.md @@ -7,7 +7,7 @@ - [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 -### Development and Contributing +### Development and Contributing - [Developing](/docs/developing.md) - Running Dashy development server locally, and general workflow - [Development Guides](/docs/development-guides.md) - Common development tasks, to help new contributors - [Contributing](/docs/contributing.md) - How you can help keep Dashy alive diff --git a/docs/release-workflow.md b/docs/release-workflow.md index 99401c5e..4be4689c 100644 --- a/docs/release-workflow.md +++ b/docs/release-workflow.md @@ -104,7 +104,7 @@ When you submit your PR, include the required info, by filling out the PR templa ## Automated Workflows -Dashy makes heavy use of [GitHub Actions](https://github.com/features/actions) to fully automate the checking, testing, building, deploying of the project, as well as administration tasks like management of issues, tags, releases and documentation. The following section outlines each workflow, along with a link the the action file, current status and short description. A lot of these automations were made possible using community actions contributed to GH marketplace by some amazing people. +Dashy makes heavy use of [GitHub Actions](https://github.com/features/actions) to fully automate the checking, testing, building, deploying of the project, as well as administration tasks like management of issues, tags, releases and documentation. The following section outlines each workflow, along with a link the the action file, current status and short description. A lot of these automations were made possible using community actions contributed to GH marketplace by some amazing people. ### Code Processing @@ -155,4 +155,4 @@ Action | Description **Generate Credits**
[![generate-credits.yml](https://github.com/Lissy93/dashy/actions/workflows/generate-credits.yml/badge.svg)](https://github.com/Lissy93/dashy/actions/workflows/generate-credits.yml) | Generates a report, including contributors, collaborators, sponsors, bots and helpful users. Will then insert a markdown table with thanks to these GitHub users and links to their profiles into the Credits page, as well as a summary of sponsors and top contributors into the main readme **Wiki Sync**
[![wiki-sync.yml](https://github.com/Lissy93/dashy/actions/workflows/wiki-sync.yml/badge.svg)](https://github.com/Lissy93/dashy/actions/workflows/wiki-sync.yml) | Generates and publishes the repositories wiki page using the markdown files within the docs directory ---- \ No newline at end of file +--- diff --git a/docs/searching.md b/docs/searching.md index e699f97d..9f6822b2 100644 --- a/docs/searching.md +++ b/docs/searching.md @@ -10,7 +10,7 @@ You can navigate through your items or search results using the keyboard. You ca You can launch a elected app by hitting Enter. This will open the app using your default opening method, specified in `target` (either `newtab`, `sametab`, `modal`, `top` or `workspace`). You can also use Alt + Enter to open the app in a pop-up modal, or Ctrl + Enter to open it in a new tab. For all available opening methods, just right-click on an item, to bring up the context menu. ## Tags -By default, items are filtered by the `title` attribute, as well as the hostname (extracted from `url`), the `provider` and `description`. If you need to find results based on text which isn't included in these attributes, then you can add `tags` to a given item. +By default, items are filtered by the `title` attribute, as well as the hostname (extracted from `url`), the `provider` and `description`. If you need to find results based on text which isn't included in these attributes, then you can add `tags` to a given item. ```yaml items: @@ -59,7 +59,7 @@ Set your default search engine using the `webSearch.searchEngine` property. This ### Using Custom Search Engine You can also use a custom search engine, that isn't included in the above list (like a self-hosted instance of [Whoogle](https://github.com/benbusby/whoogle-search) or [Searx](https://searx.github.io/searx/)). Set `searchEngine: custom`, and then specify the URL (plus query params) to you're search engine under `customSearchEngine`. -For example: +For example: ```yaml appConfig: webSearch: @@ -73,7 +73,7 @@ In a similar way to opening apps, you can specify where you would like search re ### Using Bangs An insanely useful feature of DDG is [Bangs](https://duckduckgo.com/bang), where you type a specific character combination at the start of your search query, and it will be redirected the that website, such as '!w Docker' will display the Docker wikipedia page. Dashy has a similar feature, enabling you to define your own custom bangs to redirect search results to a specific app, website or search engine. -This is done under the `searchBangs` property, with a list of key value pairs. The key is what you will type, and the value is the destination, either as an identifier or a URL with query parameters. +This is done under the `searchBangs` property, with a list of key value pairs. The key is what you will type, and the value is the destination, either as an identifier or a URL with query parameters. For example: diff --git a/docs/showcase.md b/docs/showcase.md index dc4ebfdf..257f79d0 100644 --- a/docs/showcase.md +++ b/docs/showcase.md @@ -53,7 +53,7 @@ ### The Dragons Lair > By [dr460nf1r3](https://github.com/dr460nf1r3) via [#684](https://github.com/Lissy93/dashy/issues/684) -> My new startpage featuring the stuff I use most. And of course dragons! +> My new startpage featuring the stuff I use most. And of course dragons! ![screenshot-dragons-lair](https://raw.githubusercontent.com/Lissy93/dashy/master/docs/showcase/13-dragons-lair.png) @@ -178,8 +178,8 @@ --- -### Crypto Dash -> Example usage of widgets to monitor cryptocurrencies news, prices and data. Config is [available here](https://gist.github.com/Lissy93/000f712a5ce98f212817d20bc16bab10#file-example-8-dashy-crypto-widgets-conf-yml) +### Crypto Dash +> Example usage of widgets to monitor cryptocurrencies news, prices and data. Config is [available here](https://gist.github.com/Lissy93/000f712a5ce98f212817d20bc16bab10#file-example-8-dashy-crypto-widgets-conf-yml) ![screenshot-crypto-dash](https://user-images.githubusercontent.com/1862727/147394584-352fe3bf-740d-4624-a01b-9003a97bc832.png) diff --git a/docs/status-indicators.md b/docs/status-indicators.md index b602f571..413f581f 100644 --- a/docs/status-indicators.md +++ b/docs/status-indicators.md @@ -1,13 +1,13 @@ # Status Indicators -Dashy has an optional feature that can display a small icon next to each of your running services, indicating it's current status. This can be useful if you are using Dashy as your homelab's start page, as it gives you an overview of the health of each of your running services. The status feature will show response time, response code, online/ offline check and if applicable, a relevant error message +Dashy has an optional feature that can display a small icon next to each of your running services, indicating it's current status. This can be useful if you are using Dashy as your homelab's start page, as it gives you an overview of the health of each of your running services. The status feature will show response time, response code, online/ offline check and if applicable, a relevant error message.

## Enabling Status Indicators -By default, this feature is off. If you do not want this feature, just don't add the `statusCheck` to your conf.yml file, then no requests will be made. +By default, this feature is off. If you do not want this feature, just don't add the `statusCheck` to your conf.yml file, then no requests will be made. To enable status checks, you can either turn it on for all items, by setting `appConfig.statusCheck: true`, like: ```yaml @@ -40,7 +40,7 @@ sections: ## Continuous Checking By default, with status indicators enabled Dashy will check an applications status on page load, and will not keep indicators updated. This is usually desirable behavior. However, if you do want the status indicators to continue to poll your running services, this can be enabled by setting the `statusCheckInterval` attribute. Here you define an interval as an integer in seconds, and Dashy will poll your apps every x seconds. Note that if this number is very low (below 5 seconds), you may notice the app running slightly slower. -The following example, will instruct Dashy to continuously check the status of your services every 20 seconds +The following example, will instruct Dashy to continuously check the status of your services every 20 seconds. ``` appConfig: @@ -49,7 +49,7 @@ appConfig: ``` ## Using a Different Endpoint -By default, the status checker will use the URL of each application being checked. In some situations, you may want to use a different endpoint for status checking. Similarly, some services provide a dedicated path for uptime monitoring. +By default, the status checker will use the URL of each application being checked. In some situations, you may want to use a different endpoint for status checking. Similarly, some services provide a dedicated path for uptime monitoring. You can set the `statusCheckUrl` property on any given item in order to do this. The status checker will then ping that endpoint, instead of the apps main `url` property. @@ -87,11 +87,11 @@ 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. +If you're serving Dashy though a CDN, instead of using the Node server or Docker image, then the Node endpoint that makes requests will not be available to you, and all requests will fail. A workaround for this may be implemented in the future, but in the meantime, your only option is to use the Docker or Node deployment method. ## How it Works -When the app is loaded, if `appConfig.statusCheck: true` is set, or if any items have the `statusCheck: true` enabled, then Dashy will make a request, to `https://[your-host-name]/status-check?url=[address-or-servce]` (may al include GET params for headers and the secure flag), which in turn will ping that running service, and respond with a status code. Response time is calculated from the difference between start and end time of the request. +When the app is loaded, if `appConfig.statusCheck: true` is set, or if any items have the `statusCheck: true` enabled, then Dashy will make a request, to `https://[your-host-name]/status-check?url=[address-or-servce]` (may al include GET params for headers and the secure flag), which in turn will ping that running service, and respond with a status code. Response time is calculated from the difference between start and end time of the request. When the response completes, an indicator will display next to each item. The color denotes the status: Yellow while waiting for the response to return, green if request was successful, red if it failed, and grey if it was unable to make the request all together. diff --git a/docs/theming.md b/docs/theming.md index e6bbae60..68ecb823 100644 --- a/docs/theming.md +++ b/docs/theming.md @@ -193,5 +193,3 @@ These colors represent intent, and so are not often changed, but you can do so i - `--neutral` - Neutral color, usually grey / `#272f4d` - `--white` - Just white / `#fff` - `--black` - Just black / `#000` - - diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index 78e10f96..f09b90ac 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -46,7 +46,7 @@ ## `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. +This is not an issue with Dashy, but instead caused by the target app preventing direct access through embedded elements. As defined in [RFC-7034](https://datatracker.ietf.org/doc/html/rfc7034), for any web content to be accessed through an embedded element, it must have the [`X-Frame-Options`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Frame-Options) HTTP header set to `ALLOW`. If you are getting a `Refused to Connect` error then this header is set to `DENY` (or `SAMEORIGIN` and it's on a different host). Thankfully, for self-hosted services, it is easy to set these headers. @@ -77,7 +77,7 @@ header { 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]/" +Header set X-Frame-Options: "ALLOW-FROM http://[dashy-location]/" ``` ### LightHttpd @@ -90,7 +90,7 @@ Content-Security-Policy: frame-ancestors 'self' https://[dashy-location]/ ## 404 On Static Hosting -If you're seeing Dashy's 404 page on initial load/ refresh, and then the main app when you go back to Home, then this is likely caused by the Vue router, and if so can be fixed in one of two ways. +If you're seeing Dashy's 404 page on initial load/ refresh, and then the main app when you go back to Home, then this is likely caused by the Vue router, and if so can be fixed in one of two ways. The first solution is to switch the routing mode, from HTML5 `history` mode to `hash` mode, by setting `appConfig.routingMode` to `hash`. @@ -100,7 +100,7 @@ If this works, but you wish to continue using HTML5 history mode, then a bit of ## 404 after Launch from Mobile Home Screen -Similar to the above issue, if you get a 404 after using iOS and Android's “Add to Home Screen” feature, then this is caused by Vue router. +Similar to the above issue, if you get a 404 after using iOS and Android's "Add to Home Screen" feature, then this is caused by Vue router. It can be fixed by setting `appConfig.routingMode` to `hash` See also: [#628](https://github.com/Lissy93/dashy/issues/628), [#762](https://github.com/Lissy93/dashy/issues/762) @@ -246,13 +246,13 @@ See also: #479, #409, #507, #491, #341, #520 ``` Error response from daemon: OCI runtime create failed: container_linux.go:380: starting container process caused: process_linux.go:545: container init caused: -rootfs_linux.go:76: mounting "/home/ubuntu/my-conf.yml" to rootfs at -"/app/public/conf.yml" caused: mount through procfd: not a directory: +rootfs_linux.go:76: mounting "/home/ubuntu/my-conf.yml" to rootfs at +"/app/public/conf.yml" caused: mount through procfd: not a directory: unknown: Are you trying to mount a directory onto a file (or vice-versa)? Check if the specified host path exists and is the expected type. ``` -If you get an error similar to the one above, you are mounting a directory to the config file's location, when a plain file is expected. Create a YAML file, (`touch my-conf.yml`), populate it with a sample config, then pass it as a volume: `-v ./my-local-conf.yml:/app/public/conf.yml` +If you get an error similar to the one above, you are mounting a directory to the config file's location, when a plain file is expected. Create a YAML file, (`touch my-conf.yml`), populate it with a sample config, then pass it as a volume: `-v ./my-local-conf.yml:/app/public/conf.yml` --- @@ -279,7 +279,7 @@ If you find that your styles and other visual assets work when visiting `ip:port 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 +Continuing execution. Pulling image lissy93/dashy:release-1.6.0 error pulling image configuration: toomanyrequests ``` or @@ -288,7 +288,7 @@ You have reached your pull rate limit. You may increase the limit by authenticat ``` 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. +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 @@ -375,7 +375,7 @@ 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. +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. --- @@ -494,7 +494,7 @@ Finally, check the [browser console](#how-to-open-browser-console) for any error ## Copy to Clipboard not Working -If the copy to clipboard feature (either under Config --> Export, or Item --> Copy URL) isn't functioning as expected, first check the browser console. If you see `TypeError: Cannot read properties of undefined (reading 'writeText')` then this feature is not supported by your browser. +If the copy to clipboard feature (either under Config --> Export, or Item --> Copy URL) isn't functioning as expected, first check the browser console. If you see `TypeError: Cannot read properties of undefined (reading 'writeText')` then this feature is not supported by your browser. The most common reason for this, is if you not running the app over HTTPS. Copying to the clipboard requires the app to be running in a secure origin / aka have valid HTTPS cert. You can read more about this [here](https://stackoverflow.com/a/71876238/979052). As a workaround, you could either: @@ -512,7 +512,7 @@ In some instances cached assets can prevent your settings from being updated, in To clear all local data from the UI, head to the Config Menu, then click "Reset Local Settings", and Confirm when prompted. This will not affect your config file. But be sure that you keep a backup of your config, if you've not written changes it to disk. -You can also view any and all data that Dashy is storing, using the developer tools. Open your browser's dev tools (usually F12), in Chromium head to the Application tab, or in Firefox go to the Storage tab. Select Local Storage, then scroll down the the URL Dashy is running on. You should now see all data being stored, and you can select and delete any fields you wish. +You can also view any and all data that Dashy is storing, using the developer tools. Open your browser's dev tools (usually F12), in Chromium head to the Application tab, or in Firefox go to the Storage tab. Select Local Storage, then scroll down the the URL Dashy is running on. You should now see all data being stored, and you can select and delete any fields you wish. For a full list of all data that may be cached, see the [Privacy Docs](/docs/privacy.md#browser-storage). diff --git a/docs/widgets.md b/docs/widgets.md index 7a31041c..5e049a7a 100644 --- a/docs/widgets.md +++ b/docs/widgets.md @@ -161,7 +161,7 @@ A simple, live-updating local weather component, showing temperature, conditions ### Weather Forecast -Displays the weather (temperature and conditions) for the next few days for a given location. Note that this requires either the free [OpenWeatherMap Student Plan](https://home.openweathermap.org/students), or the Premium Plan. +Displays the weather (temperature and conditions) for the next few days for a given location. Note that this requires either the free [OpenWeatherMap Student Plan](https://home.openweathermap.org/students), or the Premium Plan.

@@ -249,7 +249,7 @@ Or what about showing a photo of the day? Try `https://source.unsplash.com/rando --- | --- | --- | --- **`imagePath`** | `string` | Required | The path (local or remote) of the image to display -##### Example +##### Example ```yaml - type: image @@ -276,7 +276,7 @@ _All fields are optional_ **`provider`** | `string` | _Optional_ | The name of the service to fetch IP address from. Can be either `ipapi.co`, `ip-api` or `ipgeolocation`. Defaults to `ipapi.co`. Note, `ip-api` doesn't work on HTTPS, and if you set to `ipgeolocation` then you must also provide an API key **`apiKey`** | `string` | _Optional_ | Only required if provider is set to `ipgeolocation`. You can get a free API key [here](https://ipgeolocation.io/signup.html) -##### Example +##### Example ```yaml - type: public-ip @@ -313,7 +313,7 @@ Notice certain web pages aren't loading? This widget quickly shows which blackli **`ipAddress`** | `string` | _Optional_ | The IP to check. This can also be a domain/ host name or even an email address. If left blank, Dashy will use your current public IP address. **`apiKey`** | `string` | Required | You can get your free API key from [blacklistchecker.com](https://blacklistchecker.com/keys) -##### Example +##### Example ```yaml - type: blacklist-check @@ -345,7 +345,7 @@ Keep an eye on the expiry dates of your domain names, using public whois records **`apiKey`** | `string` | Required | You can get your free API key from [my.whoapi.com](https://my.whoapi.com/user/signup) **`showFullInfo`** | `boolean` | _Optional_ | If set to true, the toggle-full-info panel will be open by default -##### Example +##### Example ```yaml - type: domain-monitor @@ -470,7 +470,7 @@ Keep track of your crypto balances and see recent transactions. Data is fetched - type: wallet-balance options: coin: btc - address: 3853bSxupMjvxEYfwGDGAaLZhTKxB2vEVC + address: 3853bSxupMjvxEYfwGDGAaLZhTKxB2vEVC ``` ##### Info @@ -644,7 +644,7 @@ Display current FX rates in your native currency. Hover over a row to view more **`outputCurrencies`** | `array` | Required | List or currencies to show results for. Specified as a 3-letter ISO-4217 code, see [here](https://www.exchangerate-api.com/docs/supported-currencies) for the full list of supported currencies, and their symbols **`apiKey`** | `string` | Required | API key for [exchangerate-api.com](https://www.exchangerate-api.com/), usually a 24-digit alpha-numeric string. You can sign up for a free account [here](https://app.exchangerate-api.com/sign-up) -##### Example +##### Example ```yaml - type: exchange-rates @@ -717,7 +717,7 @@ Keep track of the current COVID-19 status. Optionally also show cases by country **`limit`** | `number` | _Optional_ | If showing all countries, set a limit for number of results to return. Defaults to `10`, no maximum -##### Example +##### Example ```yaml - type: covid-stats @@ -799,7 +799,7 @@ Displays the latest news, click to read full article. Date is fetched from vario **`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 +##### Example ```yaml - type: news-headlines @@ -831,7 +831,7 @@ Shows real-time tube status of the London Underground. All fields are optional. **`sortAlphabetically`** | `boolean` | _Optional_ | By default lines are sorted by current status, set this option to `true` to instead sort them alphabetically **`linesToShow`** | `array` | _Optional_ | By default all lines are shown. If you're only interested in the status of a few lines, then pass in an array of lines to show, specified by name -##### Example +##### Example ```yaml - type: tfl-status @@ -873,7 +873,7 @@ Shows recent price history for a given publicly-traded stock or share **`chartColor`** | `string` | _Optional_ | Color of the chart value. Defaults to `--widget-text-color` which inherits dashboard primary color **`chartHeight`** | `number` | _Optional_ | The height of rendered chart in px. Defaults to `300` -##### Example +##### Example ```yaml - type: stock-price-chart @@ -901,7 +901,7 @@ Renders the current Gas cost of transactions on the Ethereum network (in both GW _No config options._ -##### Example +##### Example ```yaml - type: eth-gas-prices @@ -930,7 +930,7 @@ Renders a programming or generic joke. Data is fetched from the [JokesAPI](https **`safeMode`** | `boolean` | _Optional_ | Set to `true`, to prevent the fetching of any NSFW jokes. Defaults to `false` **`language`** | `string` | _Optional_ | Specify the language for returned jokes. The following languages are supported: `en`, `cs`, `de`, `es`, `fr` and `pt`, and an up-to-date list of supported languages can be found [here](https://v2.jokeapi.dev/languages). By default, your system language will be used, if it's supported, otherwise English -##### Example +##### Example ```yaml - type: joke @@ -992,7 +992,7 @@ Displays airport departure and arrival flights, using data from [AeroDataBox](ht **`limit`** | `number` | _Optional_ | For busy airports, you may wish to limit the number of results visible **`direction`** | `string` | _Optional_ | By default, both departure and arrival flights will be fetched, if you would like to only show flights in one direction, set this to wither `departure` or `arrival` -##### Example +##### Example ```yaml - type: flight-data @@ -1022,7 +1022,7 @@ Show the NASA Astronomy Pictore of the Day. Data is fetched from [APOD](https:// _No config options._ -##### Example +##### Example ```yaml - type: apod @@ -1051,7 +1051,7 @@ Displays currently trending projects on GitHub. Optionally specify a language an **`since`** | `string` | _Optional_ | The timeframe to use when calculating trends. Can be either `daily`, `weekly` or `monthly`. Defaults to `daily` **`limit`** | `number` | _Optional_ | Optionally limit the number of results. Max `25`, default is `10` -##### Example +##### Example ```yaml - type: github-trending-repos @@ -1085,7 +1085,7 @@ Display stats from your GitHub profile, using embedded cards from [anuraghazra/g **`repos`** | `array` | _Optional_ | If you'd like to also display stats for some GitHub reposotories, then add an array or repo names here. Specified as `[username]/[repo-name]`, e.g. `lissy93/dashy` -##### Example +##### Example ```yaml @@ -1121,7 +1121,7 @@ Displays info about the server which Dashy is hosted on. Includes user + host, o _No config options._ -##### Example +##### Example ```yaml - type: system-info @@ -1147,7 +1147,7 @@ Cron job monitoring using [Health Checks](https://github.com/healthchecks/health **`apiKey`** | `string` | Required | A read-only API key for the project to monitor. You can generate this by selecting a Project --> Settings --> API Access. Note that you must generate a separate key for each project **`host`** | `string` | _Optional_ | If you're self-hosting, or using any instance other than the official (healthchecks.io), you will need to specify the host address. E.g. `https://healthchecks.example.com` or `http://cron-monitoing.local` -##### Example +##### Example ```yaml - type: health-checks @@ -1178,7 +1178,7 @@ Pull recent CPU usage history from NetData. **`chartHeight`** | `number` | _Optional_ | The height of rendered chart in px. Defaults to `300` **`chartColor`** / **`chartColors`** | `string` / `array`| _Optional_ | Color of the chart value(s) as hex codes. `chartColor` is a single value (defaults to `--widget-text-color`), whereas `chartColors` is an array of colors -##### Example +##### Example ```yaml - type: nd-cpu-history @@ -1210,7 +1210,7 @@ Pull recent system RAM usage from NetData, and show as a breakdown of different **`chartHeight`** | `number` | _Optional_ | The height of rendered chart in px. Defaults to `300` **`chartColor`** / **`chartColors`** | `string` / `array`| _Optional_ | Color of the chart value(s) as hex codes. `chartColor` is a single value (defaults to `--widget-text-color`), whereas `chartColors` is an array of colors -##### Example +##### Example ```yaml - type: nd-ram-history @@ -1241,7 +1241,7 @@ Pull recent load usage in 1, 5 and 15 minute intervals, from NetData. **`chartHeight`** | `number` | _Optional_ | The height of rendered chart in px. Defaults to `300` **`chartColor`** / **`chartColors`** | `string` / `array`| _Optional_ | Color of the chart value(s) as hex codes. `chartColor` is a single value (defaults to `--widget-text-color`), whereas `chartColors` is an array of colors -##### Example +##### Example ```yaml - type: nd-load-history @@ -1271,7 +1271,7 @@ Displays the number of queries blocked by [Pi-Hole](https://pi-hole.net/). **`hostname`** | `string` | Required | The URL to your Pi-Hole instance **`hideStatus`** / **`hideChart`** / **`hideInfo`** | `boolean` | _Optional_ | Optionally hide any of the three parts of the widget -##### Example +##### Example ```yaml - type: pi-hole-stats @@ -1302,7 +1302,7 @@ Shows top queries that were blocked and allowed by [Pi-Hole](https://pi-hole.net **`apiKey`** | `string` | Required | Your Pi-Hole web password. It is **NOT** your pi-hole admin interface or server password. It can be found in `/etc/pihole/setupVars.conf`, and is a 64-character located on the line that starts with `WEBPASSWORD` **`count`** | `number` | _Optional_ | The number of queries to display. Defaults to `10` -##### Example +##### Example ```yaml - type: pi-hole-top-queries @@ -1332,7 +1332,7 @@ Shows number of recent traffic, using allowed and blocked queries from [Pi-Hole] --- | --- | --- | --- **`hostname`** | `string` | Required | The URL to your Pi-Hole instance -##### Example +##### Example ```yaml - type: pi-hole-traffic @@ -1364,7 +1364,7 @@ Displays the current and recent uptime of your running services, via a self-host **`showChart`** | `boolean`| Optional | If provided and `false` then charts are not displayed. Defaults to `true`. **`showInfo`** | `boolean`| Optional | If provided and `false` then information summaries are not displayed. Defaults to `true`. -##### Example +##### Example ```yaml - type: stat-ping @@ -1407,7 +1407,7 @@ Displays the current downloads/torrents tasks of your Synology NAS **`username`** | `string` | Required | The username of a user on your synology NAS. You will see only this user download station tasks if he is not part of the administrator group. Currently don't support OTP protected accounts. **`password`** | `string` | Required | The password of the account specified above. -##### Example +##### Example ```yaml - type: synology-download @@ -1443,7 +1443,7 @@ displays total number of allowed and blocked queries, plus a pie chart showing b **`username`** | `string` | _Optional_ | If you've got auth enabled on AdGuard, provide your username here **`password`** | `string` | _Optional_ | If you've got auth enabled on AdGuard, provide your password here -##### Example +##### Example ```yaml - type: adguard-stats @@ -1479,7 +1479,7 @@ Fetches data from your [AdGuard Home](https://adguard.com/en/adguard-home/overvi **`password`** | `string` | _Optional_ | If you've got auth enabled on AdGuard, provide your password here **`showOnOffStatusOnly`** | `boolean` | _Optional_ | If set to `true`, will only show aggregated AdGuard filter status (on/off), instead of a list of filters -##### Example +##### Example ```yaml - type: adguard-filter-status @@ -1515,7 +1515,7 @@ Fetches data from your [AdGuard Home](https://adguard.com/en/adguard-home/overvi **`password`** | `string` | _Optional_ | If you've got auth enabled on AdGuard, provide your password here **`showFullInfo`** | `boolean` | _Optional_ | If set to `true`, the full DNS info will be shown by default, without having to click "Show Info" -##### Example +##### Example ```yaml - type: adguard-dns-info @@ -1553,7 +1553,7 @@ Fetches data from your [AdGuard Home](https://adguard.com/en/adguard-home/overvi **`hideBlockedDomains`** | `boolean` | _Optional_ | Don't show the blocked domains list (queried domains only) **`hideQueriedDomains`** | `boolean` | _Optional_ | Don't show the queried domains list (blocked domains only) -##### Example +##### Example ```yaml - type: adguard-top-domains @@ -1595,7 +1595,7 @@ Known issues: the User API incorrectly reports available disk space as total for **`password`** | `string` | Required | Nextcloud app-password (create one in Settings -> Security) -##### Example +##### Example ```yaml - type: nextcloud-user @@ -1632,7 +1632,7 @@ Show user statuses for selected users. **`showEmpty`** | `boolean` | _Optional_ | Show statuses without a message, defaults to `true` -##### Example +##### Example ```yaml - type: nextcloud-userstatus @@ -1666,10 +1666,10 @@ Displays your notifications and allows deleting them. **`hostname`** | `string` | Required | The URL of the Nextcloud server **`username`** | `string` | Required | Nextcloud username **`password`** | `string` | Required | Nextcloud app-password (create one in Settings -> Security) -**`limit`** | `number\|string` | _Optional_ | Limit displayed notifications either by count, e.g. `5` to show the 5 most recent, or by age, e.g. `1d` to only show notifications not older than a day. Accepted suffixes for age limit are `m`, `h` and `d`. +**`limit`** | `number\|string` | _Optional_ | Limit displayed notifications either by count, e.g. `5` to show the 5 most recent, or by age, e.g. `1d` to only show notifications not older than a day. Accepted suffixes for age limit are `m`, `h` and `d`. -##### Example +##### Example ```yaml - type: nextcloud-userstatus @@ -1704,7 +1704,7 @@ Visualises overall memory utilisation and CPU load averages, shows server versio **`username`** | `string` | Required | Must be a Nextcloud admin user **`password`** | `string` | Required | Nextcloud app-password (create one in Settings -> Security) -##### Example +##### Example ```yaml - type: nextcloud-system @@ -1738,7 +1738,7 @@ Shows key usage statistics about your Nextcloud server. **`username`** | `string` | Required | Must be a Nextcloud admin user **`password`** | `string` | Required | Nextcloud app-password (create one in Settings -> Security) -##### Example +##### Example ```yaml - type: nextcloud-stats @@ -1772,7 +1772,7 @@ Shows statistics about PHP Opcache perforamnce on your Nextcloud server. **`username`** | `string` | Required | Must be a Nextcloud admin user **`password`** | `string` | Required | Nextcloud app-password (create one in Settings -> Security) -##### Example +##### Example ```yaml - type: nextcloud-stats @@ -1803,12 +1803,12 @@ Shows queue information regarding your self hosted Sabnzbd server. **Field** | **Type** | **Required** | **Description** --- | --- | --- | --- **`sabnzbdUrl`** | `string` | Required | The URL of the Sabnzbd server. No trailing `/`. -**`apiKey`** | `string` | Required | API key for Sabnzbd access. Located under `Config` -> `General` -> `Security` -> `API Key`. +**`apiKey`** | `string` | Required | API key for Sabnzbd access. Located under `Config` -> `General` -> `Security` -> `API Key`. **`hideDetails`** | `boolean` | _Optional_ | Hides extra server queue details. **`hideQueue`** | `boolean` | _Optional_ | Hides the queue list in an expandable dropdown. -##### Example +##### Example ```yaml - type: sabnzbd @@ -1838,11 +1838,11 @@ Display info from the Gluetun VPN container public IP API. This can show the IP **Field** | **Type** | **Required** | **Description** --- | --- | --- | --- -**`visibleFields`** | `string` | Required | A comma separated list of the fields you want visible in the widget. You can have any number of the following : `public_ip`, `region`, `country`, `city`, `location`, `organisation`, `postal_code`, `timezone`. Defaults to just `public_ip` +**`visibleFields`** | `string` | Required | A comma separated list of the fields you want visible in the widget. You can have any number of the following : `public_ip`, `region`, `country`, `city`, `location`, `organisation`, `postal_code`, `timezone`. Defaults to just `public_ip` **`host`** | `string` | Required | The url to the gluetun HTTP control server. E.g. `http://gluetun:8000` -##### Example +##### Example ```yaml @@ -1903,7 +1903,7 @@ Live-updating current CPU usage, as a combined average across alll cores

-##### Example +##### Example ```yaml - type: gl-current-cpu @@ -1919,7 +1919,7 @@ Live-updating CPU usage breakdown per core

-##### Example +##### Example ```yaml - type: gl-current-cores @@ -1941,7 +1941,7 @@ Recent CPU usage history, across all cores, and displayed by user and system --- | --- | --- | --- **`limit`** | `number` | _Optional_ | Limit the number of results returned, rendering more data points will take longer to load. Defaults to `100` -##### Example +##### Example ```yaml - type: gl-cpu-history @@ -1958,7 +1958,7 @@ Real-time memory usage gauge, with more info visible on click

-##### Example +##### Example ```yaml - type: gl-current-mem @@ -1981,7 +1981,7 @@ Recent memory usage chart **`limit`** | `number` | _Optional_ | Limit the number of results returned, rendering more data points will take longer to load. Defaults to `100` -##### Example +##### Example ```yaml - type: gl-mem-history @@ -1998,7 +1998,7 @@ List connected disks, showing free / used space and other info (file system, mou

-##### Example +##### Example ```yaml - type: gl-disk-space @@ -2010,11 +2010,11 @@ List connected disks, showing free / used space and other info (file system, mou ### Disk IO -Shows real-time read and write speeds and operations per sec for each disk +Shows real-time read and write speeds and operations per sec for each disk

-##### Example +##### Example ```yaml - type: gl-disk-io @@ -2030,7 +2030,7 @@ Shows the number of processes waiting in the run-queue, averaged across all core

-##### Example +##### Example ```yaml - type: gl-system-load @@ -2046,7 +2046,7 @@ Shows recent historical system load, calculated from the number of processes wai

-##### Example +##### Example ```yaml - type: gl-load-history @@ -2062,7 +2062,7 @@ Lists visible network interfaces, including real-time upload/ download stats

-##### Example +##### Example ```yaml - type: gl-network-interfaces @@ -2078,7 +2078,7 @@ Shows amount of data recently uploaded/ downloaded across all network interfaces

-##### Example +##### Example ```yaml - type: gl-network-traffic @@ -2095,7 +2095,7 @@ Lists recent high resource usage alerts (e.g. CPU, mem, IO, load, temp)

-##### Example +##### Example ```yaml - type: gl-alerts @@ -2111,7 +2111,7 @@ Shows public and private IP address. Note that the ip plugin is not available on

-##### Example +##### Example ```yaml - type: gl-ip-address @@ -2130,7 +2130,7 @@ You'll need to enable the sensors plugin to use this widget, using: `--enable-pl

-##### Example +##### Example ```yaml - type: gl-cpu-temp @@ -2155,7 +2155,7 @@ Embed any webpage into your dashboard as a widget. **`url`** | `string` | Required | The URL to the webpage to embed **`frameHeight`** | `number` | _Optional_ | If needed, specify height of iframe in `px`. E.g. `400`, defaults to auto -##### Example +##### Example ```yaml - type: iframe @@ -2182,13 +2182,13 @@ Many websites and apps provide their own embeddable widgets. These can be used w **`scriptSrc`** | `string` | _Optional_ | A URL to JavaScript content (caution) **`css`** | `string` | _Optional_ | Any stylings for widget contents -##### Example +##### Example ```yaml - type: embed options: scriptSrc: https://cdn.speedcheck.org/basic/scbjs.min.js - html: | + html: |
@@ -2380,7 +2380,7 @@ In some instances, this is a false positive, and the widget is actually function ### Widget Styling -Like elsewhere in Dashy, all colours can be easily modified with CSS variables. +Like elsewhere in Dashy, all colours can be easily modified with CSS variables. Widgets use the following color variables, which can be overridden if desired: - `--widget-text-color` - Text color, defaults to `--primary` @@ -2433,7 +2433,7 @@ Widgets cannot currently be edited through the UI. This feature is in developmen Widgets are built in a modular fashion, making it easy for anyone to create their own custom components. -For a full tutorial on creating your own widget, you can follow [this guide](/docs/development-guides.md#building-a-widget), or take a look at [here](https://github.com/Lissy93/dashy/commit/3da76ce2999f57f76a97454c0276301e39957b8e) for a code example. +For a full tutorial on creating your own widget, you can follow [this guide](/docs/development-guides.md#building-a-widget), or take a look at [here](https://github.com/Lissy93/dashy/commit/3da76ce2999f57f76a97454c0276301e39957b8e) for a code example. Alternatively, for displaying simple data, you could also just use the either the [iframe](#iframe-widget), [embed](#html-embedded-widget), [data feed](#data-feed) or [API response](#api-response) widgets. From 2d731d3ed30bdc0489832f9677bd79e7916e2f01 Mon Sep 17 00:00:00 2001 From: David Alasow Date: Tue, 23 Aug 2022 09:57:02 +0200 Subject: [PATCH 2/4] Fix inconsistent markdown formatting. This changes all of the documentation markdown files to follow the same rules. The rules I've applied are from https://github.com/DavidAnson/markdownlint/blob/v0.25.1/doc/Rules.md The reason I felt it was necessary to change all the files was that there were a lot inconsistencies in how the markdown was used. Ranging from header levels to some headers having a new line before content and some not. --- docs/alternate-views.md | 4 + docs/authentication.md | 95 +++++-- docs/backup-restore.md | 49 ++-- docs/configuring.md | 50 ++-- docs/contributing.md | 13 + docs/credits.md | 32 ++- docs/deployment.md | 90 ++++--- docs/developing.md | 31 ++- docs/development-guides.md | 63 +++-- docs/icons.md | 14 +- docs/management.md | 137 +++++++--- docs/multi-language-support.md | 28 +- docs/pages-and-sections.md | 1 - docs/privacy.md | 95 ++++--- docs/quick-start.md | 15 +- docs/readme.md | 14 +- docs/release-workflow.md | 12 +- docs/searching.md | 15 +- docs/showcase.md | 81 +++--- docs/status-indicators.md | 15 +- docs/theming.md | 32 ++- docs/troubleshooting.md | 96 ++++--- docs/widgets.md | 472 ++++++++++++++++++--------------- 23 files changed, 912 insertions(+), 542 deletions(-) diff --git a/docs/alternate-views.md b/docs/alternate-views.md index 268ddfb2..57f756c9 100644 --- a/docs/alternate-views.md +++ b/docs/alternate-views.md @@ -3,6 +3,7 @@ ## Views Dashy has three different views: + - Default View - This is the main homepage with sections in a grid layout - Workspace View - Items displayed on the side, and are launched within Dashy - Minimal View - A clean + simple tabbed view @@ -10,6 +11,7 @@ Dashy has three different views: You can switch between views using the dropdown in the top-right corner. Set your chosen Starting View with `appConfig.startingView`. Click the page title at any time to go back to your selected starting view. ### Default + This is the main page that you will land on when you first launch the application. Here all of your sections (with items + widgets) are visible in a grid layout.

@@ -18,6 +20,7 @@ This is the main page that you will land on when you first launch the applicatio

### Workspace + The workspace view displays your links in a sidebar on the left-hand side, and apps are launched inside an iframe without having to leave Dashy. This enables you to use all of your self-hosted apps from one place, and makes multi-tasking easy. You can specify a default app to be opened when you land on the workspace, by setting `appConfig.workspaceLandingUrl: https://app-to-open/`. If this app exists within your sections.items, then the corresponding section will also be expanded. @@ -30,6 +33,7 @@ You can also opt to keep previously opened websites/ apps open in the background

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

diff --git a/docs/authentication.md b/docs/authentication.md index cdcc782d..2ce80cd8 100644 --- a/docs/authentication.md +++ b/docs/authentication.md @@ -1,30 +1,33 @@ # Authentication - [Basic Auth](#built-in-auth) - - [Setting Up Authentication](#setting-up-authentication) - - [Hash Password](#hash-password) - - [Logging In and Out](#logging-in-and-out) - - [Guest Access](#enabling-guest-access) - - [Per-User Access](#granular-access) - - [Security Considerations](#security) + - [Setting Up Authentication](#setting-up-authentication) + - [Hash Password](#hash-password) + - [Logging In and Out](#logging-in-and-out) + - [Guest Access](#enabling-guest-access) + - [Per-User Access](#granular-access) + - [Security Considerations](#security) - [Keycloak Auth](#keycloak) - [Deploying Keycloak](#1-deploy-keycloak) - [Setting up Keycloak](#2-setup-keycloak-users) - [Configuring Dashy for Keycloak](#3-enable-keycloak-in-dashy-config-file) - [Alternative Authentication Methods](#alternative-authentication-methods) - - [VPN](#vpn) - - [IP-Based Access](#ip-based-access) - - [Web Server Authentication](#web-server-authentication) - - [OAuth Services](#oauth-services) - - [Auth on Cloud Hosting Services](#static-site-hosting-providers) + - [VPN](#vpn) + - [IP-Based Access](#ip-based-access) + - [Web Server Authentication](#web-server-authentication) + - [OAuth Services](#oauth-services) + - [Auth on Cloud Hosting Services](#static-site-hosting-providers) ## Built-In Auth + Dashy has a basic login page included, and frontend authentication. You can enable this by adding users to the `auth` section under `appConfig` in your `conf.yml`. If this section is not specified, then no authentication will be required to access the app, and it the homepage will resolve to your dashboard. ### Setting Up Authentication + The `auth` property takes an array of users. Each user needs to include a username, hash and optional user type (`admin` or `normal`). The hash property is a [SHA-256 Hash](https://en.wikipedia.org/wiki/SHA-2) of your desired password. For example: + ```yaml appConfig: auth: @@ -37,18 +40,23 @@ appConfig: ``` ### Hash Password + Dashy uses [SHA-256 Hash](https://en.wikipedia.org/wiki/Sha-256), a 64-character string, which you can generate using an online tool, such as [this one](https://passwordsgenerator.net/sha256-hash-generator/) or [CyberChef](https://gchq.github.io/CyberChef/) (which can be self-hosted/ ran locally). A hash is a one-way cryptographic function, meaning that it is easy to generate a hash for a given password, but very hard to determine the original password for a given hash. This means, that so long as your password is long, strong and unique, it is safe to store it's hash in the clear. Having said that, you should never reuse passwords, hashes can be cracked by iterating over known password lists, generating a hash of each. ### 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.auth.enableGuestAccess: true`. ### Granular Access + You can use the following properties to make certain sections or items only visible to some users, or hide sections and items from guests. + - `hideForUsers` - Section or Item will be visible to all users, except for those specified in this list - `showForUsers` - Section or Item will be hidden from all users, except for those specified in this list - `hideForGuests` - Section or Item will be visible for logged in users, but not for guests @@ -77,6 +85,7 @@ For Example: ``` ### Permissions + Any user who is not an admin (with `type: admin`) will not be able to write changes to disk. You can also prevent any user from writing changes to disk, using `preventWriteToDisk`. Or prevent any changes from being saved locally in browser storage, using `preventLocalSave`. Both properties can be found under [`appConfig`](./docs/configuring.md#appconfig-optional). @@ -84,6 +93,7 @@ You can also prevent any user from writing changes to disk, using `preventWriteT To disable all UI config features, including View Config, set `disableConfiguration`. ### Security + With basic auth, all logic is happening on the client-side, which could mean a skilled user could manipulate the code to view parts of your configuration, including the hash. If the SHA-256 hash is of a common password, it may be possible to determine it, using a lookup table, in order to find the original password. Which can be used to manually generate the auth token, that can then be inserted into session storage, to become a valid logged in user. Therefore, you should always use a long, strong and unique password, and if you instance contains security-critical info and/ or is exposed directly to the internet, and alternative authentication method may be better. The purpose of the login page is merely to prevent immediate unauthorized access to your homepage. **[⬆️ Back to Top](#authentication)** @@ -119,21 +129,25 @@ You should now be able to access the Keycloak web interface, using the port spec ### 2. Setup Keycloak Users Before we can use Keycloak, we must first set it up with some users. Keycloak uses Realms (similar to tenants) to create isolated groups of users. You must create a Realm before you will be able to add your first user. + 1. Head over to the admin console 2. In the top-left corner there is a dropdown called 'Master', hover over it and then click 'Add Realm' 3. Give your realm a name, and hit 'Create' You can now create your first user. + 1. In the left-hand menu, click 'Users', then 'Add User' 2. Fill in the form, including username and hit 'Save' 3. Under the 'Credentials' tab, give the new user an initial password. They will be prompted to change this after first login The last thing we need to do in the Keycloak admin console is to create a new client + 1. Within your new realm, navigate to 'Clients' on the left-hand side, then click 'Create' in the top-right 2. Choose a 'Client ID', set 'Client Protocol' to 'openid-connect', and for 'Valid Redirect URIs' put a URL pattern to where you're hosting Dashy (if you're just testing locally, then * is fine), and do the same for the 'Web Origins' field 3. Make note of your client-id, and click 'Save' ### 3. Enable Keycloak in Dashy Config File + Now that your Keycloak instance is up and running, all that's left to do is to configure Dashy to use it. Under `appConfig`, set `auth.enableKeycloak: true`, then fill in the details in `auth.keycloak`, including: `serverUrl` - the URL where your Keycloak instance is hosted, `realm` - the name you gave your Realm, and `clientId` - the Client ID you chose. For example: @@ -151,10 +165,12 @@ appConfig: Note that if you are using Keycloak V 17 or older, you will also need to set `legacySupport: true` (also under `appConfig.auth.keycloak`). This is because the API endpoint was updated in later versions. ### 4. Add groups and roles (Optional) + Keycloak allows you to assign users roles and groups. You can use these values to configure who can access various sections or items in Dashy. Keycloak server administration and configuration is a deep topic; please refer to the [server admin guide](https://www.keycloak.org/docs/latest/server_admin/index.html#assigning-permissions-and-access-using-roles-and-groups) to see details about creating and assigning roles and groups. Once you have groups or roles assigned to users you can configure access under each section or item `displayData.showForKeycloakUser` and `displayData.hideForKeycloakUser`. Both show and hide configurations accept a list of `groups` and `roles` that limit access. If a users data matches one or more items in these lists they will be allowed or excluded as defined. + ```yaml sections: - name: DeveloperResources @@ -181,6 +197,7 @@ From within the Keycloak console, you can then configure things like time-outs, ## Alternative Authentication Methods If you are self-hosting Dashy, and require secure authentication to prevent unauthorized access, then you can either use Keycloak, or one of the following options: + - [Authentication Server](#authentication-server) - Put Dashy behind a self-hosted auth server - [VPN](#vpn) - Use a VPN to tunnel into the network where Dashy is running - [IP-Based Access](#ip-based-access) - Disallow access from all IP addresses, except your own @@ -189,7 +206,9 @@ If you are self-hosting Dashy, and require secure authentication to prevent unau - [Password Protection (for cloud providers)](#static-site-hosting-providers) - Enable password-protection on your site ### Authentication Server -##### Authelia + +#### Authelia + [Authelia](https://www.authelia.com/) is an open-source full-featured authentication server, which can be self-hosted and either on bare metal, in a Docker container or in a Kubernetes cluster. It allows for fine-grained access control rules based on IP, path, users etc, and supports 2FA, simple password access or bypass policies for your domains. - `git clone https://github.com/authelia/authelia.git` @@ -201,22 +220,28 @@ If you are self-hosting Dashy, and require secure authentication to prevent unau For more information, see the [Authelia docs](https://www.authelia.com/docs/) ### VPN + A catch-all solution to accessing services running from your home network remotely is to use a VPN. It means you do not need to worry about implementing complex authentication rules, or trusting the login implementation of individual applications. However it can be inconvenient to use on a day-to-day basis, and some public and corporate WiFi block VPN connections. Two popular VPN protocols are [OpenVPN](https://openvpn.net/) and [WireGuard](https://www.wireguard.com/) ### IP-Based Access + If you have a static IP or use a VPN to access your running services, then you can use conditional access to block access to Dashy from everyone except users of your pre-defined IP address. This feature is offered by most cloud providers, and supported by most web servers. -##### Apache +#### Apache + In Apache, this is configured in your `.htaccess` file in Dashy's root folder, and should look something like: -``` + +```text Order Deny,Allow Deny from all Allow from [your-ip] ``` -##### NGINX +#### NGINX + In NGINX you can specify [control access](https://docs.nginx.com/nginx/admin-guide/security-controls/controlling-access-proxied-http/) rules for a given site in your `nginx.conf` or hosts file. For example: -``` + +```text server { listen 80; server_name www.dashy.example.com; @@ -229,9 +254,11 @@ server { } ``` -##### Caddy +#### Caddy + In Caddy, [Request Matchers](https://caddyserver.com/docs/caddyfile/matchers) can be used to filter requests -``` + +```text dashy.site { @public_networks not remote_ip [your-ip] respond @public_networks "Access denied" 403 @@ -239,11 +266,14 @@ dashy.site { ``` ### Web Server Authentication + Most web servers make password protecting certain apps very easy. Note that you should also set up HTTPS and have a valid certificate in order for this to be secure. -##### Apache +#### Apache + First crate a `.htaccess` file in Dashy's route directory. Specify the auth type and path to where you want to store the password file (usually the same folder). For example: -``` + +```text AuthType Basic AuthName "Please Sign into Dashy" AuthUserFile /path/dashy/.htpasswd @@ -251,21 +281,27 @@ require valid-user ``` Then create a `.htpasswd` file in the same directory. List users and their hashed passwords here, with one user on each line, and a colon between username and password (e.g. `[username]:[hashed-password]`). You will need to generate an MD5 hash of your desired password, this can be done with an [online tool](https://www.web2generators.com/apache-tools/htpasswd-generator). Your file will look something like: -``` + +```text alicia:$apr1$jv0spemw$RzOX5/GgY69JMkgV6u16l0 ``` -##### NGINX +#### NGINX + NGINX has an [authentication module](https://nginx.org/en/docs/http/ngx_http_auth_basic_module.html) which can be used to add passwords to given sites, and is fairly simple to set up. Similar to above, you will need to create a `.htpasswd` file. Then just enable auth and specify the path to that file, for example: -``` + +```text location / { auth_basic "closed site"; auth_basic_user_file conf/htpasswd; } ``` -##### Caddy + +#### Caddy + Caddy has a [basic-auth](https://caddyserver.com/docs/caddyfile/directives/basicauth) directive, where you specify a username and hash. The password hash needs to be base-64 encoded, the [`caddy hash-password`](https://caddyserver.com/docs/command-line#caddy-hash-password) command can help with this. For example: -``` + +```text basicauth /secret/* { alicia JDJhJDEwJEVCNmdaNEg2Ti5iejRMYkF3MFZhZ3VtV3E1SzBWZEZ5Q3VWc0tzOEJwZE9TaFlZdEVkZDhX } @@ -273,11 +309,13 @@ basicauth /secret/* { For more info about implementing a single sign on for all your apps with Caddy, see [this tutorial](https://joshstrange.com/securing-your-self-hosted-apps-with-single-signon/) -##### Lighttpd +#### Lighttpd + You can use the [mod_auth](https://doc.lighttpd.net/lighttpd2/mod_auth.html) module to secure your site with Lighttpd. Like with Apache, you need to first create a password file listing your usersnames and hashed passwords, but in Lighttpd, it's usually called `.lighttpdpassword`. Then in your `lighttpd.conf` file (usually in the `/etc/lighttpd/` directory), load in the mod_auth module, and configure it's directives. For example: -``` + +```text server.modules += ( "mod_auth" ) auth.debug = 2 auth.backend = "plain" @@ -296,12 +334,15 @@ $HTTP["host"] == "dashy.my-domain.net" { ) } ``` + Restart your web server for changes to take effect. ### OAuth Services + There are also authentication services, such as [Ory.sh](https://www.ory.sh/), [Okta](https://developer.okta.com/), [Auth0](https://auth0.com/), [Firebase](https://firebase.google.com/docs/auth/). Implementing one of these solutions would involve some changes to the [`Auth.js`](https://github.com/Lissy93/dashy/blob/master/src/utils/Auth.js) file, but should be fairly straight forward. ### Static Site Hosting Providers + If you are hosting Dashy on a cloud platform, you will probably find that it has built-in support for password protected access to web apps. For more info, see the relevant docs for your provider, for example: [Netlify Password Protection](https://docs.netlify.com/visitor-access/password-protection/), [Cloudflare Access](https://www.cloudflare.com/teams/access/), [AWS Cognito](https://aws.amazon.com/cognito/), [Azure Authentication](https://docs.microsoft.com/en-us/azure/app-service/scenario-secure-app-authentication-app-service) and [Vercel Password Protection](https://vercel.com/docs/platform/projects#password-protection). **[⬆️ Back to Top](#authentication)** diff --git a/docs/backup-restore.md b/docs/backup-restore.md index 06d4b565..856b6564 100644 --- a/docs/backup-restore.md +++ b/docs/backup-restore.md @@ -1,4 +1,4 @@ -### Cloud Backup and Restore +# Cloud Backup and Restore Dashy has a built-in feature for securely backing up your config to a hosted cloud service, and then restoring it on another instance. This feature is totally optional, and if you do not enable it, then Dashy will not make any external network requests. @@ -8,18 +8,19 @@ This is useful not only for backing up your configuration off-site, but it also

-### How it Works +## How it Works All data is encrypted before being sent to the backend. In Dashy, this is done in [`CloudBackup.js`](https://github.com/Lissy93/dashy/blob/master/src/utils/CloudBackup.js), using [crypto.js](https://github.com/brix/crypto-js)'s AES method, using the users chosen password as the key. The data is then sent to a [Cloudflare worker](https://developers.cloudflare.com/workers/learning/how-workers-works) (a platform for running serverless functions), and stored in a [KV](https://developers.cloudflare.com/workers/learning/how-kv-works) data store. +## Creating a Backup -### Creating a Backup Once you've got Dashy configured to your preference, open the Backup & Restore menu (click the Cloud icon in the top-right corner). Here you will be prompted to choose a password, which will be used to encrypt your data. If you forget this password, there will be no way to recover your config. After clicking 'Backup' your data will be encrypted, compressed and sent to the hosted cloud service. A backup ID will be returned (in the format of xxxx-xxxx-xxxx-xxxx), this is what you use, along with your password to restore the backup on another system, so take note of it. To update a backup, return to this menu, enter your password, and click 'Update Backup'. -### Restoring a Backup +## Restoring a Backup + To restore a backup, navigate to the Backup & Restore menu, and under restore, enter your backup ID, and the password you chose. Your config file will be downloaded, decrypted and applied to local storage. -### Privacy & Security +## Privacy & Security Data is only ever sent to the cloud when the user actively triggers a backup. All transmitted data is first encrypted using [AES](https://en.wikipedia.org/wiki/Advanced_Encryption_Standard). Your selected password never leaves your device, and is hashed before being compared. It is only possible to restore a configuration if you have both the backup ID and decryption password. @@ -27,24 +28,23 @@ Because the data is encrypted on the client-side (before being sent to the cloud Having said that, although the code uses robust security libraries and is open source- it was never intended to be a security product, and has not been audited, and therefore cannot be considered totally secure - please keep that in mind. - -### Fair Use Policy +## Fair Use Policy Maximum of 24mb of storage per user. Please do not repeatedly hit the endpoint, as if the quota is exceeded the service may become less available to other users. Abuse may result in your IP being temporarily banned by Cloudflare. --- -### Self-Hosting the Backup Server +## Self-Hosting the Backup Server +### Quick Start -#### Quick Start - Install Wrangler CLI Tool: `npm i -g @cloudflare/wrangler` - Log into Cloudflare account: `wrangler login` -- Create a new project: ` wrangler generate my-project` +- Create a new project: `wrangler generate my-project` - Install dependencies: `cd my-project` && `npm i` +### Populate `wrangler.toml` -#### Populate `wrangler.toml` - Add your `account_id` (found on the right sidebar of the Workers or Overview Dashboard) - Add your `zone_id` (found in the Overview tab of your desired domain on Cloudflare) - Add your `route`, which should be a domain or host, supporting a wildcard @@ -63,10 +63,11 @@ kv_namespaces = [ ] ``` -#### Complete `index.js` +### Complete `index.js` + - Write code to handle your requests, and interact with any other data sources in this file - Generally, this is done within an event listener for 'fetch', and returns a promise - - For Example: + - For Example: ```javascript addEventListener('fetch', event => { @@ -82,28 +83,28 @@ async function handleRequest(request) { - For the code used for Dashy's cloud service, see [here](https://gist.github.com/Lissy93/d19b43d50f30e02fa25f349cf5cb5ed8#file-index-js) +### Commands -#### Commands - `wrangler dev` - To start the wrangler development server - `wrangler publish` - To publish to your cloudflare account (first run `wrangler login`) -### API +## API There are four endpoints, and to keep things simple, they all use the same base URL/ route. - **`GET`** - Get config for a given user - - `backupId` - The ID of the desired encrypted object - - `subHash` - The latter half of the password hash, to verify ownership + - `backupId` - The ID of the desired encrypted object + - `subHash` - The latter half of the password hash, to verify ownership - **`POST`** - Save a new config object, and returns `backupId` - - `userData` - The encrypted, compressed and stringified user config - - `subHash` - The latter half of the password hash, to verify ownership + - `userData` - The encrypted, compressed and stringified user config + - `subHash` - The latter half of the password hash, to verify ownership - **`PUT`** - Update an existing config object - - `backupId` - The ID of the object to update - - `subHash` - Part of the hash, to verify ownership of said object - - `userData` - The new data to store + - `backupId` - The ID of the object to update + - `subHash` - Part of the hash, to verify ownership of said object + - `userData` - The new data to store - **`DELETE`** - Delete a specified config object - - `backupId` - The ID of the object to be deleted - - `subHash` - Part of the password hash, to verify ownership of the object + - `backupId` - The ID of the object to be deleted + - `subHash` - Part of the password hash, to verify ownership of the object For more info, see the [API Docs](https://documenter.getpostman.com/view/2142819/TzXumzce). diff --git a/docs/configuring.md b/docs/configuring.md index e4c19ad5..148d85e5 100644 --- a/docs/configuring.md +++ b/docs/configuring.md @@ -2,7 +2,8 @@ All app configuration is specified in [`/public/conf.yml`](https://github.com/Lissy93/dashy/blob/master/public/conf.yml) which is in [YAML Format](https://yaml.org/) format. If you're using Docker, this file can be passed in as a volume. Changes can either be made directly to this file, or done [through the UI](#editing-config-through-the-ui). From the UI you can also export, backup, reset, validate and download your configuration file. -#### There are three ways to edit the config +## There are three ways to edit the config + - **Directly in the YAML file** _(5/5 reliability, 3/5 usability)_ - Write changes directly to the conf.yml file, optionally using one of the templates provided. This can be done in your favorite editor and uploading to your server, or directly editing the file via SSH, but the easiest method would be to use [Code Server](https://github.com/coder/code-server) - **UI JSON Editor** _(4/5 reliability, 4/5 usability)_ @@ -12,7 +13,8 @@ All app configuration is specified in [`/public/conf.yml`](https://github.com/Li - **REST API** _(Coming soon)_ - Programmatically edit config either through the command line, using a script or a third-party application -#### Tips +## Tips + - You may find it helpful to look at some sample config files to get you started, a collection of which can be found [here](https://gist.github.com/Lissy93/000f712a5ce98f212817d20bc16bab10) - You can check that your config file fits the schema, by running `yarn validate-config` - After modifying your config, the app needs to be recompiled, by running `yarn build` - this happens automatically if you're using Docker @@ -23,7 +25,7 @@ All app configuration is specified in [`/public/conf.yml`](https://github.com/Li The following file provides a reference of all supported configuration options. -#### Contents +## Contents - [**`pageInfo`**](#pageinfo) - Header text, footer, title, navigation, etc - [`navLinks`](#pageinfonavlinks-optional) - Links to display in the navigation bar @@ -52,7 +54,7 @@ The following file provides a reference of all supported configuration options. --- -### Top-Level Fields +## Top-Level Fields **Field** | **Type** | **Required**| **Description** --- | --- | --- | --- @@ -63,7 +65,7 @@ The following file provides a reference of all supported configuration options. **[⬆️ Back to Top](#configuring)** -### `PageInfo` +## `PageInfo` **Field** | **Type** | **Required**| **Description** --- | --- | --- | --- @@ -75,7 +77,7 @@ The following file provides a reference of all supported configuration options. **[⬆️ Back to Top](#configuring)** -### `pageInfo.navLinks` _(optional)_ +## `pageInfo.navLinks` _(optional)_ **Field** | **Type** | **Required**| **Description** --- | --- | --- | --- @@ -85,7 +87,7 @@ The following file provides a reference of all supported configuration options. **[⬆️ Back to Top](#configuring)** -### `pages[]` _(optional)_ +## `pages[]` _(optional)_ **Field** | **Type** | **Required**| **Description** --- | --- | --- | --- @@ -94,7 +96,7 @@ The following file provides a reference of all supported configuration options. **[⬆️ Back to Top](#configuring)** -### `appConfig` _(optional)_ +## `appConfig` _(optional)_ **Field** | **Type** | **Required**| **Description** --- | --- | --- | --- @@ -136,7 +138,8 @@ The following file provides a reference of all supported configuration options. **[⬆️ Back to Top](#configuring)** -### `appConfig.auth` _(optional)_ +## `appConfig.auth` _(optional)_ + **Field** | **Type** | **Required**| **Description** --- | --- | --- | --- **`users`** | `array` | _Optional_ | An array of objects containing usernames and hashed passwords. If this is not provided, then authentication will be off by default, and you will not need any credentials to access the app. See [`appConfig.auth.users`](#appconfigauthusers-optional).
**Note** this method of authentication is handled on the client side, so for security critical situations, it is recommended to use an [alternate authentication method](/docs/authentication.md#alternative-authentication-methods). @@ -148,7 +151,7 @@ For more info, see the **[Authentication Docs](/docs/authentication.md)** **[⬆️ Back to Top](#configuring)** -### `appConfig.auth.users` _(optional)_ +## `appConfig.auth.users` _(optional)_ **Field** | **Type** | **Required**| **Description** --- | --- | --- | --- @@ -158,7 +161,7 @@ For more info, see the **[Authentication Docs](/docs/authentication.md)** **[⬆️ Back to Top](#configuring)** -### `appConfig.auth.keycloak` _(optional)_ +## `appConfig.auth.keycloak` _(optional)_ **Field** | **Type** | **Required**| **Description** --- | --- | --- | --- @@ -169,7 +172,7 @@ For more info, see the **[Authentication Docs](/docs/authentication.md)** **[⬆️ Back to Top](#configuring)** -### `appConfig.webSearch` _(optional)_ +## `appConfig.webSearch` _(optional)_ **Field** | **Type** | **Required**| **Description** --- | --- | --- | --- @@ -179,10 +182,9 @@ For more info, see the **[Authentication Docs](/docs/authentication.md)** **`openingMethod`** | `string` | _Optional_ | Set your preferred opening method for search results: `newtab`, `sametab`, `workspace`. Defaults to `newtab` **`searchBangs`** | `object` | _Optional_ | A key-value-pair set of custom search _bangs_ for redirecting query to a specific app or search engine. The key of each should be the bang you will type (typically starting with `/`, `!` or `:`), and value is the destination, either as a search engine key (e.g. `reddit`) or a URL with search parameters (e.g. `https://en.wikipedia.org/w/?search=`) - **[⬆️ Back to Top](#configuring)** -### `appConfig.hideComponents` _(optional)_ +## `appConfig.hideComponents` _(optional)_ **Field** | **Type** | **Required**| **Description** --- | --- | --- | --- @@ -194,7 +196,7 @@ For more info, see the **[Authentication Docs](/docs/authentication.md)** **[⬆️ Back to Top](#configuring)** -### `section` +## `section` **Field** | **Type** | **Required**| **Description** --- | --- | --- | --- @@ -206,7 +208,7 @@ For more info, see the **[Authentication Docs](/docs/authentication.md)** **[⬆️ Back to Top](#configuring)** -### `section.item` +## `section.item` **Field** | **Type** | **Required**| **Description** --- | --- | --- | --- @@ -230,8 +232,7 @@ For more info, see the **[Authentication Docs](/docs/authentication.md)** **[⬆️ Back to Top](#configuring)** - -### `item.displayData` _(optional)_ +## `item.displayData` _(optional)_ **Field** | **Type** | **Required**| **Description** --- | --- | --- | --- @@ -243,8 +244,7 @@ For more info, see the **[Authentication Docs](/docs/authentication.md)** **[⬆️ Back to Top](#configuring)** - -### `section.widget` _(optional)_ +## `section.widget` _(optional)_ **Field** | **Type** | **Required**| **Description** --- | --- | --- | --- @@ -258,8 +258,7 @@ For more info, see the **[Authentication Docs](/docs/authentication.md)** **[⬆️ Back to Top](#configuring)** - -### `section.displayData` _(optional)_ +## `section.displayData` _(optional)_ **Field** | **Type** | **Required**| **Description** --- | --- | --- | --- @@ -282,7 +281,7 @@ For more info, see the **[Authentication Docs](/docs/authentication.md)** **[⬆️ Back to Top](#configuring)** -### `section.icon` and `section.item.icon` +## `section.icon` and `section.item.icon` **Field** | **Type** | **Required**| **Description** --- | --- | --- | --- @@ -290,7 +289,7 @@ For more info, see the **[Authentication Docs](/docs/authentication.md)** **[⬆️ Back to Top](#configuring)** -### `section.displayData.hideForKeycloakUsers`, `section.displayData.showForKeycloakUsers`, `item.displayData.hideForKeycloakUsers` and `item.displayData.showForKeycloakUsers` +## `section.displayData.hideForKeycloakUsers`, `section.displayData.showForKeycloakUsers`, `item.displayData.hideForKeycloakUsers` and `item.displayData.showForKeycloakUsers` **Field** | **Type** | **Required**| **Description** --- |------------| --- | --- @@ -320,10 +319,13 @@ Config can be modified directly through the UI, and then written to disk, or app

### About YAML + If you're new to YAML, it's pretty straight-forward. The format is exactly the same as that of JSON, but instead of using curly braces, structure is denoted using whitespace. This [quick guide](https://linuxhandbook.com/yaml-basics/) should get you up to speed in a few minutes, for more advanced topics take a look at this [Wikipedia article](https://en.wikipedia.org/wiki/YAML). ### Config Saving Methods + When updating the config through the JSON editor in the UI, you have two save options: **Local** or **Write to Disk**. + - Changes saved locally will only be applied to the current user through the browser, and will not apply to other instances - you either need to use the cloud sync feature, or manually update the conf.yml file. - On the other-hand, if you choose to write changes to disk, then your main `conf.yml` file will be updated, and changes will be applied to all users, and visible across all devices. For this functionality to work, you must be running Dashy with using the Docker container, or the Node server. A backup of your current configuration will also be saved in the same directory. diff --git a/docs/contributing.md b/docs/contributing.md index aa1cf5c3..532b4a44 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -5,11 +5,13 @@ There are several ways that you can help out, and any contributions, however sma 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 :) [![Take the Survey](https://img.shields.io/badge/Take_the-Survey-%231a86fd?style=for-the-badge&logo=buddy)](https://survey.typeform.com/to/gl0L68ou) ## Share your dashboard + Dashy now has a [Showcase](https://github.com/Lissy93/dashy/blob/master/docs/showcase.md#dashy-showcase-) where you can show off a screenshot of your dashboard, and get inspiration from other users (and I really love seeing how people are using Dashy). To [submit your dashboard](https://github.com/Lissy93/dashy/blob/master/docs/showcase.md#submitting-your-dashboard), either open a PR or raise an issue. [![Add your Dashboard to the Showcase](https://img.shields.io/badge/Add_your_Dashboard-Showcase-%238616ee?style=for-the-badge&logo=feathub&logoColor=8616ee)](https://github.com/Lissy93/dashy/issues/new?assignees=&labels=%F0%9F%92%AF+Showcase&template=showcase-addition.yml&title=%5BSHOWCASE%5D+%3Ctitle%3E) @@ -36,6 +38,7 @@ Sponsoring will give you several perks - for $1 / £0.75 per month, you'll get a - **ZEC**: `t1bw1SefijsXRDQVxC9w64XsRK8hBhtQohQ`

+ ## Enable Anonymous Bug Reports @@ -43,6 +46,7 @@ Sponsoring will give you several perks - for $1 / £0.75 per month, you'll get a Bug reports helps me to discover bugs I was unaware of, and then fix them, in order to make Dashy more reliable long term. This is a simple, yet really helpful step you can take to help improve Dashy. [Sentry](https://github.com/getsentry/sentry) is an open source error tracking and performance monitoring tool, which enables the identification any errors which occur in the production app (only if you enable it). To enable error reporting: + ```yaml appConfig: enableErrorReporting: true @@ -51,31 +55,38 @@ appConfig: 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/developing.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. [![Raise a Bug](https://img.shields.io/badge/Raise_a-Bug-%23dc2d76?style=for-the-badge&logo=dependabot)](https://github.com/Lissy93/dashy/issues/new?assignees=lissy93&labels=%F0%9F%90%9B+Bug&template=bug.yml&title=%5BBUG%5D+%3Ctitle%3E) ## Join the discussion + I've enabled the discussion feature on GitHub, here you can share tips and tricks, useful information, or your dashboard. You can also ask questions, and offer basic support to other users. [![Join the Discussion on GitHub](https://img.shields.io/badge/Join_the-Discussion-%23ffd000?style=for-the-badge&logo=livechat)](https://github.com/Lissy93/dashy/discussions) ## Request a feature via BountySource + BountySource is a platform for sponsoring the development of certain features on open source projects. If there is a feature you'd like implemented into Dashy, but either isn't high enough priority or is deemed to be more work than it's worth, then you can instead contribute a bounty towards it's development. You won't pay a penny until your proposal is fully built, and you are satisfied with the result. This helps support the developers, and makes Dashy better for everyone. [![Request a Feature on BountySource](https://img.shields.io/badge/BountySource-Dashy-%23F67909?style=for-the-badge&logo=openbugbounty)](https://www.bountysource.com/teams/dashy) ## Spread the word + Dashy is still a relatively young project, and as such not many people know of it. It would be great to see more users, and so it would be awesome if you could consider sharing with your friends or on social platforms. [![Share Dashy on Mastodon](https://img.shields.io/badge/Share-Mastodon-%232b90d9?style=flat-square&logo=mastodon)](https://mastodon.social/?text=Check%20out%20Dashy%2C%20the%20privacy-friendly%2C%20self-hosted%20startpage%20for%20organizing%20your%20life%3A%20https%3A%2F%2Fgithub.com%2FLissy93%2Fdashy%20-%20By%20%40lissy93%40mastodon.social) @@ -90,6 +101,7 @@ Dashy is still a relatively young project, and as such not many people know of i [![Share Dashy via Email](https://img.shields.io/badge/Share-Email-%238A90C7?style=flat-square&logo=protonmail)](mailto:info@example.com?&subject=Check%20out%20Dashy%20-%20The%20self-hosted%20dashboard%20for%20your%20homelab%20%F0%9F%9A%80&cc=&bcc=&body=https://github.com/lissy93/dashy) ## Star, Upvote or Leave a Review + Dashy is on the following platforms, and if you could spare a few seconds to give it an upvote or review, this will also help new users discover Dashy [![ProductHunt](https://img.shields.io/badge/Review-ProductHunt-%23b74424?style=flat-square&logo=producthunt)](https://www.producthunt.com/posts/dashy) @@ -99,6 +111,7 @@ Dashy is on the following platforms, and if you could spare a few seconds to giv [![Star on DockerHub](https://img.shields.io/docker/stars/lissy93/dashy?color=4cb6e0&label=Star%20-%20Docker&logo=docker&style=flat-square)](https://hub.docker.com/r/lissy93/dashy) ## Follow for More + If you've enjoyed Dashy, you can follow the me to get updates about other projects that I am working on. [![Alicia Sykes on Twitter](https://img.shields.io/twitter/follow/Lissy_Sykes?style=social&logo=twitter)](https://twitter.com/Lissy_Sykes) diff --git a/docs/credits.md b/docs/credits.md index 5d7f6bcc..633eb659 100644 --- a/docs/credits.md +++ b/docs/credits.md @@ -1,6 +1,6 @@ # Credits -### Sponsors +## Sponsors @@ -143,7 +143,7 @@
-### Contributors +## Contributors @@ -357,8 +357,7 @@
- -### Helpful Users +## Helpful Users @@ -407,7 +406,7 @@
-### Bots +## Bots @@ -458,7 +457,7 @@ > The above section is auto-generated, using [contribute-list](https://github.com/marketplace/actions/contribute-list) by @akhilmhdh. -### Newest Stargazers +## Newest Stargazers [![Recent Star Gazers](https://reporoster.com/stars/dark/Lissy93/dashy)](https://github.com/Lissy93/dashy/stargazers) @@ -470,17 +469,20 @@ 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 +### Core + At it's core, the application uses [**Vue.js**](https://github.com/vuejs/vue), as well as it's services with [**VueX**](https://vuex.vuejs.org/) for state management. 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), with a simple [**Node.js**](https://github.com/nodejs/node) server to serve up the static app and the optional API endpoints, and container deployment is done with [**Docker**](https://www.docker.com/). -#### Utilities +### Utilities + - [`crypto-js`](https://github.com/brix/crypto-js) - Encryption implementations by @evanvosberg and community `MIT` - [`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 +### Frontend Components + - [`vue-select`](https://github.com/sagalbot/vue-select) - Dropdown component by @sagalbot `MIT` - [`vue-js-modal`](https://github.com/euvl/vue-js-modal) - Modal component by @euvl `MIT` - [`v-tooltip`](https://github.com/Akryum/v-tooltip) - Tooltip component by @Akryum `MIT` @@ -490,13 +492,16 @@ At it's core, the application uses [**Vue.js**](https://github.com/vuejs/vue), a - [`vue-toasted`](https://github.com/shakee93/vue-toasted) - Toast notification component by @shakee93 `MIT` - [`vue-swatches`](https://github.com/saintplay/vue-swatches) - Color palete picker by @saintplay `MIT` -#### Backup & Sync Server +### Backup & Sync Server + Although the app is purely frontend, there is an optional cloud sync feature, for off-site backup and restore. This is built as a serverless function on [Cloudflare workers](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 +### 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 images are hosted on [DockerHub](https://hub.docker.com/), and the demos are hosted on [Netlify](https://www.netlify.com/). -#### Actions +### Actions + This repo makes heavy use of [GitHub actions](https://github.com/features/actions) to run automated workflows. The following base actions are totally awesome, and have been extremely useful. Full credit to their respective authors - [`action-autotag`](https://github.com/butlerlogic/action-autotag) by @butlerlogic - Tags new versions when app version changes @@ -518,5 +523,6 @@ This repo makes heavy use of [GitHub actions](https://github.com/features/action --- -## You! +## You + Would you like to be listed here? Whatever your skill set, Dashy needs people like you to help support future development. Check out the [Contributing Page](/docs/contributing.md) for ways that you can get involved. Huge thank you to everyone who has already contributed! 💖 diff --git a/docs/deployment.md b/docs/deployment.md index 02b74906..6a957cdb 100644 --- a/docs/deployment.md +++ b/docs/deployment.md @@ -2,9 +2,11 @@ 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 +## Quick Start + 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: -``` + +```bash docker run -p 8080:80 lissy93/dashy ``` @@ -44,8 +46,7 @@ Once you've got Dashy up and running, you'll want to configure it with your own 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. - -```docker +```bash docker run -d \ -p 8080:80 \ -v /root/my-local-conf.yml:/app/public/conf.yml \ @@ -55,6 +56,7 @@ docker run -d \ ``` Explanation of the above options: + - `-d` Detached mode (not running in the foreground of your terminal) - `-p` The port that should be exposed, and the port it should be mapped to in your host system `[host-port][container-port]`, leave the container port as is - `-v` Specify volumes, to pass data from your host system to the container, in the format of `[host-path]:[container-path]`, you can use this to pass your config file, directory of assets (like icons), custom CSS or web assets (like favicon.ico, manifest.json etc) @@ -108,6 +110,7 @@ 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` @@ -126,7 +129,9 @@ Installing dashy is really simply and fast: 1. Install Docker via Synology ```Package Center```. 2. Go to ```File Station``` and open the ```docker``` folder. Inside the docker folder, create one new folder and name it ```dashy```. - > Note: Be careful to enter only lowercase, not uppercase letters. + + > Note: Be careful to enter only lowercase, not uppercase letters. + 3. Go to Control Panel / Task Scheduler / Create / Scheduled Task / User-defined script. 4. Once you click on ```User-defined``` script a new window will open. 5. Follow the instructions below: @@ -134,7 +139,7 @@ Installing dashy is really simply and fast: 7. Schedule: Select Run on the following date then select "Do not repeat". 8. Task Settings: Check "Send run details by email", add your email then copy paste the code below in the Run command area. After that click OK. -``` +```bash docker run -d \ -p 4000:80 \ -v /volume1/docker/dashy/my-local-conf.yml:/app/public/conf.yml \ @@ -142,7 +147,9 @@ docker run -d \ --restart=always \ lissy93/dashy:latest ``` + dashy should be up within 1-2min after you've started the install task procedure + --- ## Build from Source @@ -157,7 +164,7 @@ If you do not want to use Docker, you can run Dashy directly on your host system --- -### Deploy to cloud service +## 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. @@ -165,113 +172,134 @@ 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 +### Netlify + [![Deploy to Netlify](https://i.ibb.co/GtKMysT/deploy-netlify-button.png)](https://app.netlify.com/start/deploy?repository=https://github.com/lissy93/dashy) [Netlify](https://www.netlify.com/) offers Git-based serverless cloud hosting for web applications. Their services are free to use for personal use, and they support deployment from both public and private repos, as well as direct file upload. The free plan also allows you to use your own custom domain or sub-domain, and is easy to setup. To deploy Dashy to Netlify, use the following link -``` + +```text https://app.netlify.com/start/deploy?repository=https://github.com/lissy93/dashy ``` -#### Heroku +### Heroku + [![Deploy to Heroku](https://i.ibb.co/GdMFzBP/deploy-heroku-button.png)](https://heroku.com/deploy?template=https://github.com/Lissy93/dashy) [Heroku](https://www.heroku.com/) is a fully managed cloud platform as a service. You define app settings in a Procfile and app.json, which specifying how the app should be build and how the server should be started. Heroku is free to use for unlimited, non-commercial, single dyno apps, and supports custom domains. Heroku's single-dyno service is not as quite performant as some other providers, and the app will have a short wake-up time when not visited for a while To deploy Dashy to Heroku, use the following link -``` + +```text https://heroku.com/deploy?template=https://github.com/Lissy93/dashy ``` -#### Cloudflare Workers +### Cloudflare Workers + [![Deploy to Cloudflare Workers](https://i.ibb.co/jf9xVdm/deploy-cloudflare-button.png)](https://deploy.workers.cloudflare.com/?url=https://github.com/lissy93/dashy/tree/deploy_cloudflare) [Cloudflare Workers](https://workers.cloudflare.com/) is a simple yet powerful service for running cloud functions and hosting web content. It requires a Cloudflare account, but is completely free for smaller projects, and very reasonably priced ($0.15/million requests per month) for large applications. You can use your own domain, and applications are protected with Cloudflare's state of the art DDoS protection. For more info, see the docs on [Worker Sites](https://developers.cloudflare.com/workers/platform/sites) To deploy Dashy to Cloudflare, use the following link -``` + +```text https://deploy.workers.cloudflare.com/?url=https://github.com/lissy93/dashy/tree/deploy_cloudflare ``` -#### Vercel +### Vercel + [![Deploy with Vercel](https://i.ibb.co/mJF3R7m/deploy-vercel-button.png)](https://vercel.com/new/project?template=https://github.com/lissy93/dashy) [Vercel](https://vercel.com/) is a performance-focused platform for hosting static frontend apps. It comes bundled with some useful tools for monitoring and anaylzing application performance and other metrics. Vercel is free for personal use, allows for custom domains and has very reasonable limits. To deploy Dashy to Vercel, use the following link -``` + +```text https://vercel.com/new/project?template=https://github.com/lissy93/dashy ``` -#### DigitalOcean +### DigitalOcean + [![Deploy to DO](https://i.ibb.co/PFt0PkB/deploy-digital-ocean-button.png)](https://cloud.digitalocean.com/apps/new?repo=https://github.com/lissy93/dashy/tree/deploy_digital-ocean&refcode=3838338e7f79) [DigitalOcean](https://www.digitalocean.com/) is a cloud service providing affordable developer-friendly virtual machines from $5/month. But they also have an app platform, where you can run web apps, static sites, APIs and background workers. CDN-backed static sites are free for personal use. -``` +```text https://cloud.digitalocean.com/apps/new?repo=https://github.com/lissy93/dashy/tree/deploy_digital-ocean ``` -#### Google Cloud Platform +### Google Cloud Platform + [![Run on Google Cloud](https://i.ibb.co/LkvHttd/deploy-google-cloud-button.png)](https://deploy.cloud.run/?git_repo=https://github.com/lissy93/dashy.git) [Cloud Run](https://cloud.google.com/run/) is a service offered by [Google Cloud](https://cloud.google.com/). It's a fully managed serverless platform, for developing and deploying highly scalable containerized applications. Similar to AWS and Azure, GCP offers a wide range of cloud services, which are billed on a pay‐per‐use basis, but Cloud Run has a [free tier](https://cloud.google.com/run/pricing) offering 180,000 vCPU-seconds, 360,000 GiB-seconds, and 2 million requests per month. To deploy Dashy to GCP, use the following link -``` + +```text https://deploy.cloud.run/?git_repo=https://github.com/lissy93/dashy.git ``` -#### Platform.sh +### Platform.sh + [![Deploy to Platform.sh](https://i.ibb.co/nPnJgJP/deploy-platform-sh-button.png)](https://console.platform.sh/projects/create-project/?template=https://github.com/lissy93/dashy&utm_campaign=deploy_on_platform?utm_medium=button&utm_source=affiliate_links&utm_content=https://github.com/lissy93/dashy) [Platform.sh](https://platform.sh) is an end-to-end solution for developing and deploying applications. It is geared towards enterprise users with large teams, and focuses on allowing applications to scale up and down. Unlike the above providers, Platform.sh is not free, although you can deploy a test app to it without needing a payment method To deploy Dashy to Platform.sh, use the following link -``` + +```text https://console.platform.sh/projects/create-project/?template=https://github.com/lissy93/dashy ``` -#### Render +### Render + [![Deploy to Render](https://i.ibb.co/QXNCbxT/deploy-render-button.png)](https://render.com/deploy?repo=https://github.com/lissy93/dashy/tree/deploy_render) [Render](https://render.com) is cloud provider that provides easy deployments for static sites, Docker apps, web services, databases and background workers. Render is great for developing applications, and very easy to use. Static sites are free, and services start at $7/month. Currently there are only 2 server locations - Oregon, USA and Frankfurt, Germany. For more info, see the [Render Docs](https://render.com/docs) To deploy Dashy to Render, use the following link -``` + +```text https://render.com/deploy?repo=https://github.com/lissy93/dashy/tree/deploy_render ``` -#### Scalingo +### Scalingo + [![Deploy on Scalingo](https://i.ibb.co/nj0KxyH/deploy-scalingo-button.png)](https://my.scalingo.com/deploy?source=https://github.com/lissy93/dashy#master) [Scalingo](https://scalingo.com/) is a scalable container-based cloud platform as a service. It's focus is on compliance and uptime, and is geared towards enterprise users. Scalingo is also not free, although they do have a 3-day free trial that does not require a payment method. To deploy Dashy to Scalingo, use the following link -``` + +```text https://my.scalingo.com/deploy?source=https://github.com/lissy93/dashy#master ``` -#### Play-with-Docker +### Play-with-Docker + [![Try in PWD](https://i.ibb.co/SfbH7Zy/deploy-pwd-button.png)](https://labs.play-with-docker.com/?stack=https://raw.githubusercontent.com/Lissy93/dashy/master/docker-compose.yml) [Play with Docker](https://labs.play-with-docker.com/) is a community project by Marcos Liljedhal and Jonathan Leibiusky and sponsored by Docker, intended to provide a hands-on learning environment. Their labs let you quickly spin up a Docker container or stack, and test out the image in a temporary, sandboxed environment. There's no need to sign up, and it's completely free. To run Dashy in PWD, use the following URL: -``` + +```text https://labs.play-with-docker.com/?stack=https://raw.githubusercontent.com/Lissy93/dashy/master/docker-compose.yml ``` -#### Surge.sh +### Surge.sh + ![Follow instructions below](https://i.ibb.co/XkcKzKz/deploy-surge-button.png) [Surge.sh](http://surge.sh/) is quick and easy static web publishing platform for frontend-apps. Surge supports [password-protected projects](https://surge.sh/help/adding-password-protection-to-a-project). You can also [add a custom domain](https://surge.sh/help/adding-a-custom-domain) and then [force HTTPS by default](https://surge.sh/help/using-https-by-default) and optionally [set a custom SSL certificate](https://surge.sh/help/securing-your-custom-domain-with-ssl) To deploy Dashy to Surge.sh, first clone and cd into Dashy, install dependencies, and then use the following commands -``` + +```bash yarn add -g surge yarn build surge ./dist @@ -287,7 +315,6 @@ However without Dashy's node server, there are a couple of features that will be --- - ## Requirements ### System Requirements @@ -295,12 +322,15 @@ However without Dashy's node server, there are a couple of features that will be Dashy works well on a Raspberry Pi (tested on Pi 3 and later), but should also run well on any system. ### Docker + Initial app build causes a spike in resource usage, but once the built app is running it is fairly steady. For this reason, Dashy works best with a minimum of 1GB of memory, and 1GB of disk space. ### Bare Metal + Minimum 526mb mem, 2GB disk space. ### CDN / Cloud Deploy + No specific requirements. The built application alone (without the Node server) is very light-weight, and can be handled smoothly by pretty much any CDN or cloud deployment service (see [this list](/docs/deployment.md#deploy-to-cloud-service) or natively supported cloud providers). If you're using your own icons, or other assets, additional disk space will be required for those resources. diff --git a/docs/developing.md b/docs/developing.md index 2f2f0905..a7c0935d 100644 --- a/docs/developing.md +++ b/docs/developing.md @@ -24,6 +24,7 @@ If you're adding new features, you may want to check out the [Development Guides ## Setting up the Dev Environment ### Prerequisites + You will need either the latest or LTS version of **[Node.js](https://nodejs.org/)** to build and serve the application and **[Git](https://git-scm.com/downloads)** to easily fetch the code, and push any changes. If you plan on running or deploying the container, you'll also need **[Docker](https://docs.docker.com/get-docker/)**. To avoid any unexpected issues, ensure you've got at least **[NPM](https://www.npmjs.com/get-npm)** V 7.5 or **[Yarn](https://classic.yarnpkg.com/en/docs/install/#windows-stable)** 1.22 (you may find [NVM](https://github.com/nvm-sh/nvm) helpful for switching/ managing versions). ### Running the Project @@ -33,34 +34,40 @@ You will need either the latest or LTS version of **[Node.js](https://nodejs.org 3. Install dependencies: `yarn` 4. Start dev server: `yarn dev` -Dashy should now be being served on http://localhost:8080/. Hot reload is enabled, so making changes to any of the files will trigger them to be rebuilt and the page refreshed. +Dashy should now be being served on . Hot reload is enabled, so making changes to any of the files will trigger them to be rebuilt and the page refreshed. ### Project Commands #### Basics + - **`yarn build`** - In the interest of speed, the application is pre-compiled, this means that the config file is read during build-time, and therefore the app needs to rebuilt for any new changes to take effect. Luckily this is very straight forward. Just run `yarn build` or `docker exec -it [container-id] yarn build` - **`yarn start`** - Starts a web server, and serves up the production site from `./dist` (must run build command first) #### Development + - **`yarn dev`** - Starts the development server with hot reloading - **`yarn lint`** - Lints code to ensure it follows a consistent, neat style - **`yarn test`** - Runs tests, and outputs results #### Utils and Checks + - **`yarn validate-config`** - If you have quite a long configuration file, you may wish to check that it's all good to go, before deploying the app. This can be done with `yarn validate-config` or `docker exec -it [container-id] yarn validate-config`. Your config file needs to be in `/public/conf.yml` (or within your Docker container at `/app/public/conf.yml`). This will first check that your YAML is valid, and then validates it against Dashy's [schema](https://github.com/Lissy93/dashy/blob/master/src/utils/ConfigSchema.js). - **`yarn health-check`** - Checks that the application is up and running on it's specified port, and outputs current status and response times. Useful for integrating into your monitoring service, if you need to maintain high system availability #### Alternate Start Commands + - **`yarn build-and-start`** - Builds the app, runs checks and starts the production server. Commands are run in parallel, and so is faster than running them in independently. Uses the `yarn build` and `yarn start` commands - **`yarn build-watch`** - If you find yourself making frequent changes to your configuration, and do not want to have to keep manually rebuilding, then this option is for you. It will watch for changes to any files within the projects root, and then trigger a rebuild. Note that if you are developing new features, then `yarn dev` would be more appropriate, as it's significantly faster at recompiling (under 1 second), and has hot reloading, linting and testing integrated - **`yarn pm2-start`** - Starts the Node server using [PM2](https://pm2.keymetrics.io/), a process manager for Node.js applications, that helps them stay alive. PM2 has some built-in basic monitoring features, and an optional [management solution](https://pm2.io/). If you are running the app on bare metal, it is recommended to use this start command #### Notes + - If you are using NPM, replace `yarn` with `npm run` - If you are using Docker, precede each command with `docker exec -it [container-id]`. Container ID can be found by running `docker ps` - You can manage the app using the [Vue-CLI Service](https://cli.vuejs.org/guide/cli-service.html), with `npx vue-cli-service [command]`. Or to start the Vue Management UI, run `npx vue ui`, and open `http://localhost:8000` ### Environmental Variables + All environmental variables are optional. Currently there are not many environmental variables used, as most of the user preferences are stored under `appConfig` in the `conf.yml` file. You can set variables either in your environment, or using the [`.env`](https://github.com/Lissy93/dashy/blob/master/.env) file. @@ -75,6 +82,7 @@ You can set variables either in your environment, or using the [`.env`](https:// - `VUE_APP_VERSION` - Again, set automatically using package.json during build time ### Environment Modes + You can set the environment using the `NODE_ENV` variable. By default, the correct environment should be selected based on the script you run to start the app. The following environments are supported: `production`, `development` and `test`. For more info, see [Vue CLI Environment Modes](https://cli.vuejs.org/guide/mode-and-env.html#modes). --- @@ -82,6 +90,7 @@ You can set the environment using the `NODE_ENV` variable. By default, the corre ## Git Strategy ### Git Flow + Like most Git repos, we are following the [Github Flow](https://guides.github.com/introduction/flow) standard. 1. Create a branch (or fork if you don'd have write access) @@ -93,10 +102,12 @@ Like most Git repos, we are following the [Github Flow](https://guides.github.co 7. Merge 🎉 ### Git Branch Naming + The format of your branch name should be something similar to: `[TYPE]/[TICKET]_[TITLE]` For example, `FEATURE/420_Awesome-feature` or `FIX/690_login-server-error` ### Commit Emojis + Using a single emoji at the start of each commit message, to indicate the type task, makes the commit ledger easier to understand, plus it looks cool. - 🎨 `:art:` - Improve structure / format of the code. @@ -127,14 +138,17 @@ Using a single emoji at the start of each commit message, to indicate the type t For a full list of options, see [gitmoji.dev](https://gitmoji.dev/) ### PR Guidelines + Once you've made your changes, and pushed them to your fork or branch, you're ready to open a pull request! For a pull request to be merged, it must: + - Must be backwards compatible - The build, lint and tests (run by GH actions) must pass - There must not be any merge conflicts When you submit your PR, include the required info, by filling out the PR template. Including: + - A brief description of your changes - The issue, ticket or discussion number (if applicable) - For UI relate updates include a screenshot @@ -144,7 +158,9 @@ When you submit your PR, include the required info, by filling out the PR templa --- ## Resources for Beginners + New to Web Development? Glad you're here! Dashy is a pretty simple app, so it should make a good candidate for your first PR. Presuming that you already have a basic knowledge of JavaScript, the following articles should point you in the right direction for getting up to speed with the technologies used in this project: + - [Open Source for Beginners](https://opensource.guide/how-to-contribute/) - [Introduction to Vue.js](https://v3.vuejs.org/guide/introduction.html) - [Vue.js Walkthrough](https://www.taniarascia.com/getting-started-with-vue/) @@ -164,11 +180,12 @@ As well as Node, Git and Docker- you'll also need an IDE (e.g. [VS Code](https:/ ## App Info -## Style Guide +### 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, and any lint errors will trigger the build to fail. Note that all lint checks must pass before any PR can be merged. Linting is also run as a git pre-commit hook The most significant things to note are: + - Indentation should be done with two spaces - Strings should use single quotes - All statements must end in a semi-colon @@ -180,15 +197,17 @@ The most significant things to note are: - Avoid console statements in the frontend Styleguides: + - Vue: [Vue styleguide](https://vuejs.org/v2/style-guide/) - JavaScript: [github.com/airbnb/javascript](https://github.com/airbnb/javascript) --- -## Application Structure +### Application Structure #### Files in the Root: `./` -``` + +```text ╮ ├── package.json # Project meta-data, dependencies and paths to scripts ├── src/ # Project front-end source code @@ -207,7 +226,7 @@ Styleguides: #### Frontend Source: `./src/` -``` +```text ./src ├── App.vue # Vue.js starting file ├── assets # Static non-compiled assets @@ -340,9 +359,11 @@ Styleguides: ## Development Tools ### Performance - Lighthouse + The easiest method of checking performance is to use Chromium's build in auditing tool, Lighthouse. To run the test, open Developer Tools (usually F12) --> Lighthouse and click on the 'Generate Report' button at the bottom. ### Dependencies - BundlePhobia + [BundlePhobia](https://bundlephobia.com/) is a really useful app that lets you analyze the cost of adding any particular dependency to an application --- diff --git a/docs/development-guides.md b/docs/development-guides.md index cba17f0c..b88d1ff5 100644 --- a/docs/development-guides.md +++ b/docs/development-guides.md @@ -3,6 +3,7 @@ A series of short tutorials, to guide you through the most common development tasks. Sections: + - [Creating a new theme](#creating-a-new-theme) - [Writing Translations](#writing-translations) - [Adding a new option in the config file](#adding-a-new-option-in-the-config-file) @@ -17,10 +18,12 @@ Sections: Adding a new theme is really easy. There's two things you need to do: Pass the theme name to Dashy, so that it can be added to the theme selector dropdown menu, and then write some styles! -##### 1. Add Theme Name +### 1. Add Theme Name + Choose a snappy name for you're theme, and add it to the `builtInThemes` array inside [`defaults.js`](https://github.com/Lissy93/dashy/blob/master/src/utils/defaults.js#L27). -##### 2. Write some Styles! +### 2. Write some Styles + Put your theme's styles inside [`color-themes.scss`](https://github.com/Lissy93/dashy/blob/master/src/styles/color-themes.scss). Create a new block, and make sure that `data-theme` matches the theme name you chose above. For example: @@ -45,10 +48,12 @@ Dashy is using [vue-i18n](https://vue-i18n.intlify.dev/guide/) to manage multi-l Adding a new language is pretty straightforward, with just three steps: -##### 1. Create a new Language File +### 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). -##### 2. Translate! +### 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. ```json @@ -65,7 +70,7 @@ Using [`en.json`](https://github.com/Lissy93/dashy/tree/master/src/assets/locale } ``` -##### 3. Add your file to the app +### 3. Add your file to the app In [`./src/utils/languages.js`](https://github.com/Lissy93/dashy/tree/master/src/utils/languages.js), you need to do 2 small things: @@ -73,6 +78,7 @@ First import your new translation file, do this at the top of the page. E.g. `import de from '@/assets/locales/de.json';` Second, add it to the array of languages, e.g: + ```javascript export const languages = [ { @@ -89,11 +95,12 @@ 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! If you are not comfortable with making pull requests, or do not want to modify the code, then feel free to instead send the translated file to me, and I can add it into the application. I will be sure to credit you appropriately. -# Adding a new option in the config file +## Adding a new option in the config file This section is for, adding a new setting to the config file. @@ -101,6 +108,7 @@ All of the users config is specified in `./public/conf.yml` - see [Configuring D It's important to first ensure that there isn't a similar option already available, the new option is definitely necessary, and most importantly that it is fully backwards compatible. Next choose the appropriate section to place it under + - Application settings should be located under `appConfig` - Page info (such as text and metadata) should be under `pageInfo` - Data relating to specific sections should be under `section[n].displayData` @@ -132,7 +140,9 @@ For example: "example": "0821c65656" } ``` + or + ```json "iconSize": { "enum": [ "small", "medium", "large" ], @@ -144,6 +154,7 @@ or Finally, add your new property to the [`configuring.md`](./configuring.md) API docs. Put it under the relevant section, and be sure to include field name, data type, a description and mention that it is optional. If your new feature needs more explaining, then you can also document it under the relevant section elsewhere in the documentation. Checklist: + - [ ] Ensure the new attribute is actually necessary, and nothing similar already exists - [ ] Update the [Schema](https://github.com/Lissy93/dashy/blob/master/src/utils/ConfigSchema.js) with the parameters for your new option - [ ] If required, set a default or fallback value (usually in [`defaults.js`](https://github.com/Lissy93/dashy/blob/master/src/utils/defaults.js)) @@ -163,12 +174,12 @@ It is important to thoroughly test after any big dependency updates. When Dashy is deployed to Netlify, it is effectively running as a static app, and therefore the server-side code for the Node.js endpoints is not available. However Netlify now supports serverless cloud lambda functions, which can be used to replace most functionality. -#### 1. Run Netlify Dev Server +### 1. Run Netlify Dev Server First off, install the Netlify CLI: `npm install netlify-cli -g` Then, from within the root of Dashy's directory, start the server, by running: `netlify dev` -#### 2. Create a lambda function +### 2. Create a lambda function This should be saved it in the [`./services/serverless-functions`](https://github.com/Lissy93/dashy/tree/master/services/serverless-functions) directory @@ -179,7 +190,7 @@ exports.handler = async () => ({ }); ``` -#### 3. Redirect the Node endpoint to the function +### 3. Redirect the Node endpoint to the function In the [`netlify.toml`](https://github.com/Lissy93/dashy/blob/FEATURE/serverless-functions/netlify.toml) file, add a 301 redirect, with the path to the original Node.js endpoint, and the name of your cloud function @@ -194,20 +205,23 @@ In the [`netlify.toml`](https://github.com/Lissy93/dashy/blob/FEATURE/serverless --- ## 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 +### 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 +### 2. Add the conditional to the structural component to hide First, import the helper function: + ```javascript import { shouldBeVisible } from '@/utils/SectionHelpers'; ``` Then you can create a computed value, that calls this function, passing in the route name: + ```javascript export default { ... @@ -221,6 +235,7 @@ export default { ``` Finally, in the markup of your component, just add a `v-if` statement, referencing your computed value + ```vue
... @@ -230,6 +245,7 @@ Finally, in the markup of your component, just add a `v-if` statement, referenci --- ## Adding / Using Environmental Variables + All environmental variables are optional. Currently there are not many environmental variables used, as most of the user preferences are stored under `appConfig` in the `conf.yml` file. You can set variables either in your environment, or using the [`.env`](https://github.com/Lissy93/dashy/blob/master/.env) file. @@ -250,12 +266,10 @@ To build a widget, you'll also need some basic knowledge of Vue.js. The [officia If you just want to jump straight in, then [here](https://github.com/Lissy93/dashy/commit/3da76ce2999f57f76a97454c0276301e39957b8e) is a complete implementation of a new example widget, or take a look at the [`XkcdComic.vue`](https://github.com/Lissy93/dashy/blob/master/src/components/Widgets/XkcdComic.vue) widget, which is pretty simple. - ### Step 1 - Create Widget Firstly, create a new `.vue` file under [`./src/components/Widgets`](https://github.com/Lissy93/dashy/tree/master/src/components/Widgets). - ```vue