From 23576873dee72cb9da2e62529671e6690cd6e0f6 Mon Sep 17 00:00:00 2001 From: Alicia Sykes Date: Tue, 16 Apr 2024 17:00:22 +0100 Subject: [PATCH] =?UTF-8?q?=F0=9F=93=9D=20Update=20docs=20for=20V3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/authentication.md | 7 ++++++- docs/backup-restore.md | 2 ++ docs/configuring.md | 10 +++++++++- docs/icons.md | 4 ++-- docs/management.md | 4 +++- docs/privacy.md | 2 +- docs/widgets.md | 27 +++++++++++++++++++++++++++ 7 files changed, 50 insertions(+), 6 deletions(-) diff --git a/docs/authentication.md b/docs/authentication.md index 13f42242..c7e74f8a 100644 --- a/docs/authentication.md +++ b/docs/authentication.md @@ -20,7 +20,7 @@ > [!IMPORTANT] -> Dashy's built-in auth is not indented to protect a publicly hosted instance against unauthorized access. Instead you should use an auth provider compatible with your reverse proxy, or access Dashy via your VPN. +> Dashy's built-in auth is not indented to protect a publicly hosted instance against unauthorized access. Instead you should use an auth provider compatible with your reverse proxy, or access Dashy via your VPN, or implement your own SSO logic. > > In cases where Dashy is only accessibly within your home network, and you just want to add a login page, then the built-in auth may be sufficient, but keep in mind that configuration can still be accessed. @@ -28,6 +28,11 @@ Dashy has a basic login page included, and frontend authentication. You can enable this by adding users to the `auth` section under `appConfig` in your `conf.yml`. If this section is not specified, then no authentication will be required to access the app, and the homepage will resolve to your dashboard. +> [!NOTE] +> Since the auth is initiated in the main app entry point (for security), a rebuild is required to apply changes to the auth configuration. +> You can trigger a rebuild through the UI, under Config --> Rebuild, or by running `yarn build` in the root directory. + + ### 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. diff --git a/docs/backup-restore.md b/docs/backup-restore.md index 856b6564..f42e95e4 100644 --- a/docs/backup-restore.md +++ b/docs/backup-restore.md @@ -1,5 +1,7 @@ # Cloud Backup and Restore +Beyond the cloud backup/restore service, there are several other self-hosted options you can use to backup Dashy, and any other Docker container data. These are outlined in the Management docs, at: [Docker Backup Options](/docs/management.md#backing-up). + Dashy has a built-in feature for securely backing up your config to a hosted cloud service, and then restoring it on another instance. This feature is totally optional, and if you do not enable it, then Dashy will not make any external network requests. This is useful not only for backing up your configuration off-site, but it also enables Dashy to be used without having write a YAML config file, and makes it possible to use a public hosted instance, without the need to self-host. diff --git a/docs/configuring.md b/docs/configuring.md index 3c812995..3bcb0d4a 100644 --- a/docs/configuring.md +++ b/docs/configuring.md @@ -102,7 +102,7 @@ The following file provides a reference of all supported configuration options. **Field** | **Type** | **Required**| **Description** --- | --- | --- | --- **`language`** | `string` | _Optional_ | The 2 (or 4-digit) [ISO 639-1 code](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) for your language, e.g. `en` or `en-GB`. This must be a language that the app has already been [translated](https://github.com/Lissy93/dashy/tree/master/src/assets/locales) into. If your language is unavailable, Dashy will fallback to English. By default Dashy will attempt to auto-detect your language, although this may not work on some privacy browsers. -**`startingView`** | `enum` | _Optional_ | Which page to load by default, and on the base page or domain root. You can still switch to different views from within the UI. Can be either `default`, `minimal` or `workspace`. Defaults to `default` +~~**`startingView`**~~ | `enum` | _Optional_ | Which page to load by default, and on the base page or domain root. You can still switch to different views from within the UI. Can be either `default`, `minimal` or `workspace`. Defaults to `default`. NOTE: This has been replaced by an environmental variable: `VUE_APP_STARTING_VIEW` in V3 onwards **`defaultOpeningMethod`** | `enum` | _Optional_ | The default opening method for items, if no `target` is specified for a given item. Can be either `newtab`, `sametab`, `modal`, `workspace`, `clipboard`, `top` or `parent`. Defaults to `newtab` **`statusCheck`** | `boolean` | _Optional_ | When set to `true`, Dashy will ping each of your services and display their status as a dot next to each item. This can be overridden by setting `statusCheck` under each item. Defaults to `false` **`statusCheckInterval`** | `number` | _Optional_ | The number of seconds between checks. If set to `0` then service will only be checked on initial page load, which is usually the desired functionality. If value is less than `10` you may experience a hit in performance. Defaults to `0` @@ -143,6 +143,14 @@ The following file provides a reference of all supported configuration options. ## `appConfig.auth` _(optional)_ +> [!NOTE] +> Since the auth is initiated in the main app entry point (for security), a rebuild is required to apply changes to the auth configuration. +> You can trigger a rebuild through the UI, under Config --> Rebuild, or by running `yarn build` in the root directory. + +> [!WARNING] +> Built-in auth should **not be used** for security-critical applications, or if your Dashy instance is publicly accessible. +> For these, it is recommended to use an [alternate authentication method](/docs/authentication.md#alternative-authentication-methods). + **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). diff --git a/docs/icons.md b/docs/icons.md index 1a71e1d9..8f3b0542 100644 --- a/docs/icons.md +++ b/docs/icons.md @@ -167,7 +167,7 @@ You can also set an icon by passing in a valid URL pointing to the icons locatio ## Local Icons -You may also want to store your icons locally, bundled within Dashy so that there is no reliance on outside services. This can be done by putting the icons within Dashy's `./public/item-icons/` directory. If you are using Docker, then the easiest option is to map a volume from your host system, for example: `-v /local/image/directory:/app/public/item-icons/`. To reference an icon stored locally, just specify it's name and extension. For example, if my icon was stored in `/app/public/item-icons/maltrail.png`, then I would just set `icon: maltrail.png`. +You may also want to store your icons locally, bundled within Dashy so that there is no reliance on outside services. This can be done by putting the icons within Dashy's `./user-data/item-icons/` directory. If you are using Docker, then the easiest option is to map a volume from your host system, for example: `-v /local/image/directory:/app/user-data/item-icons/`. To reference an icon stored locally, just specify it's name and extension. For example, if my icon was stored in `/app/user-data/item-icons/maltrail.png`, then I would just set `icon: maltrail.png`. You can also use sub-folders within the `item-icons` directory to keep things organized. You would then specify an icon with it's folder name slash image name. For example: `networking/monit.png` @@ -187,7 +187,7 @@ If you don't wish for a given item or section to have an icon, just leave out th ## Icon Collections and Resources -The following websites provide good-quality, free icon sets. To use any of these icons, either copy the link to the raw icon (it should end in `.svg` or `.png`) and paste it as your `icon`, or download and save the icons in `/public/item-icons` / mapped Docker volume. Full credit to the authors, please see the licenses for each service for usage and copyright information. +The following websites provide good-quality, free icon sets. To use any of these icons, either copy the link to the raw icon (it should end in `.svg` or `.png`) and paste it as your `icon`, or download and save the icons in `/user-data/item-icons` / mapped Docker volume. Full credit to the authors, please see the licenses for each service for usage and copyright information. - [Icons for Self-Hosted Apps](https://thehomelab.wiki/books/helpful-tools-resources/page/icons-for-self-hosted-dashboards) - 350+ high-quality icons for commonly self-hosted services - [SVG Box](https://svgbox.net/iconsets/) - Cryptocurrency, social media apps and flag icons diff --git a/docs/management.md b/docs/management.md index 76b88653..a626ccb0 100644 --- a/docs/management.md +++ b/docs/management.md @@ -197,7 +197,9 @@ docker run --rm -v some_volume:/volume -v /tmp:/backup alpine sh -c "rm -rf /vol ### Dashy-Specific Backup -Since Dashy is open source, and freely available, providing you're configuration data is passed in as volumes, there shouldn't be any need to backup the main container. Your main config file, and any assets you're using should be kept backed up, preferably in at least two places, and you should ensure that you can easily restore from backup, if needed. +All configuration and dashboard settings are stored in your `user-data/conf.yml` file. If you provide additional assets (like icons, fonts, themes, etc), these will also live in the `user-data` directory. So to backup all Dashy data, this is the only directory you need to backup. + +Since Dashy is open source, there shouldn't be any need to backup the main container. Dashy also has a built-in cloud backup feature, which is free for personal users, and will let you make and restore fully encrypted backups of your config directly through the UI. To learn more, see the [Cloud Backup Docs](/docs/backup-restore.md) diff --git a/docs/privacy.md b/docs/privacy.md index 917fb8c5..05c44c97 100644 --- a/docs/privacy.md +++ b/docs/privacy.md @@ -192,7 +192,7 @@ The following section outlines all data that is stored in the browsers, as cooki > [Local storage](https://developer.mozilla.org/en-US/docs/Web/API/Window/localStorage) is persisted between sessions, and only deleted when manually removed - `LANGUAGE` - The locale to show app text in -- `HIDE_WELCOME_BANNER` - Set to true once user dismissed welcome message, so that it's not shown again +- `HIDE_INFO_NOTIFICATION` - Set to true once user dismissed welcome message, so that it's not shown again - `LAYOUT_ORIENTATION` - Preferred section layout, either horizontal, vertical or auto - `COLLAPSE_STATE` - Remembers which sections are collapsed - `ICON_SIZE` - Size of items, either small, medium or large diff --git a/docs/widgets.md b/docs/widgets.md index 6db695d9..a657693a 100644 --- a/docs/widgets.md +++ b/docs/widgets.md @@ -92,6 +92,7 @@ Dashy has support for displaying dynamic content in the form of widgets. There a - [Widget Usage Guide](#widget-usage-guide) - [Continuous Updates](#continuous-updates) - [Proxying Requests](#proxying-requests) + - [Handling Secrets](#handling-secrets) - [Setting Timeout](#setting-timeout) - [Adding Labels](#adding-labels) - [Ignoring Errors](#ignoring-errors) @@ -2856,6 +2857,32 @@ Vary: Origin --- +### Handling Secrets + +Some widgets require you to pass potentially sensetive info such as API keys. The `conf.yml` is not ideal for this, as it's stored in plaintext. +Instead, for secrets you should use environmental vairables. + +You can do this, by setting the environmental variable name as the value, instead of the actual key, and then setting that env var in your container or local environment. + +The key can be named whatever you like, but it must start with `VUE_APP_` (to be picked up by Vue). If you need to update any of these values, a rebuild is required (this can be done under the Config menu in the UI, or by running `yarn build` then restarting the container). + +For more infomation about setting and managing your environmental variables, see [Management Docs --> Environmental Variables](/docs/management.md#passing-in-environmental-variables). + +For example: + +```yaml +- type: weather + options: + apiKey: VUE_APP_WEATHER_TOKEN + city: London + units: metric + hideDetails: true +``` + +Then, set `VUE_APP_WEATHER_TOKEN='xxx'` + +--- + ### Setting Timeout If the endpoint you are requesting data from is slow to respond, you may see a timeout error in the console. This can easily be fixed by specifying the `timeout` property on the offending widget. This should be an integer value, in milliseconds. By default timeout is `2500` ms (2½ seconds).