From 0022940c653f8bc3be167ce63de21e61c19b9ab6 Mon Sep 17 00:00:00 2001 From: Liss-Bot Date: Sun, 28 Apr 2024 21:59:15 +0000 Subject: [PATCH] Update documentation --- docs/authentication.md | 34 ++++++++++++++++++++++++++++++++++ docs/quick-start.md | 36 +++++++++++++++++++++++++++++++----- 2 files changed, 65 insertions(+), 5 deletions(-) diff --git a/docs/authentication.md b/docs/authentication.md index 6e74371958..8f53cff63a 100644 --- a/docs/authentication.md +++ b/docs/authentication.md @@ -6,7 +6,10 @@ - [Logging In and Out](#logging-in-and-out) - [Guest Access](#enabling-guest-access) - [Per-User Access](#granular-access) + - [Using Environment Variables for Passwords](#using-environment-variables-for-passwords) + - [Adding HTTP Auth to Configuration](#adding-http-auth-to-configuration) - [Security Considerations](#security) +- [HTTP Auth](#http-auth) - [Keycloak Auth](#keycloak) - [Deploying Keycloak](#1-deploy-keycloak) - [Setting up Keycloak](#2-setup-keycloak-users) @@ -115,6 +118,27 @@ You can also prevent any user from writing changes to disk, using `preventWriteT To disable all UI config features, including View Config, set `disableConfiguration`. Alternatively you can disable UI config features for all non admin users by setting `disableConfigurationForNonAdmin` to true. +### Using Environment Variables for Passwords + +If you don't want to hash your password, you can instead leave out the `hash` attribute, and replace it with `password` which should have the value of an environmental variable name you wish to use. + +Note that env var must begin with `VUE_APP_`, and you must set this variable before building the app. + +For example: + +```yaml + auth: + users: + - user: bob + password: VUE_APP_BOB +``` + +Just be sure to set `VUE_APP_BOB='my super secret password'` before build-time. + +### Adding HTTP Auth to Configuration + +If you'd also like to prevent direct visit access to your configuration file, you can set the `ENABLE_HTTP_AUTH` environmental variable. + ### 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. @@ -123,6 +147,16 @@ With basic auth, all logic is happening on the client-side, which could mean a s --- +## HTTP Auth + +If you'd like to protect all your config files from direct access, you can set the `BASIC_AUTH_USERNAME` and `BASIC_AUTH_PASSWORD` environmental variables. You'll then be prompted to enter these credentials when visiting Dashy. + +Then, if you'd like your frontend to automatically log you in, without prompting you for credentials, then also specify `VUE_APP_BASIC_AUTH_USERNAME` and `VUE_APP_BASIC_AUTH_PASSWORD`. This is useful for when you're hosting Dashy on a private server, and you want to prevent unauthorized access to your config files, while still allowing the frontend to access them. Note that a rebuild is required for these changes to take effect. + +**[⬆️ Back to Top](#top)** + +--- + ## Keycloak Dashy also supports using a [Keycloak](https://www.keycloak.org/) authentication server. The setup for this is a bit more involved, but it gives you greater security overall, useful for if your instance is exposed to the internet. diff --git a/docs/quick-start.md b/docs/quick-start.md index 0ba7421ff0..63add056b4 100644 --- a/docs/quick-start.md +++ b/docs/quick-start.md @@ -32,7 +32,32 @@ Your dashboard should now be up and running at `http://localhost:8080` (or your --- -## 3. Configure +## 3. User Data Directory + +Your config file should be placed inside `user-data/` (in Docker, that's `/app/user-data/`). + +This directory can also contain some optional assets you wish to use within your dashboard, like icons, fonts, styles, scripts, etc. + +Any files placed here will be served up to the root of the domain, and override the contents of `public/`. +For example, if you had `user-data/favicon.ico` this would be accessible at `http://my-dashy-instance.local/favicon.ico` + +Example Files in `user-data`: +- `conf.yml` - This is the only file that is compulsary, it's your main Dashy config +- `**.yml` - Include more config files, if you'd like to have multiple pages, see [Multi-page support](/docs/pages-and-sections#multi-page-support) for docs +- `favicon.ico` - The default favicon, shown in the browser's tab title +- `initialization.html` - Static HTML page displayed before the app has finished compiling, see [`public/initialization.html`](https://github.com/Lissy93/dashy/blob/master/public/initialization.html) +- `robots.txt` - Search engine crawl rules, override this if you want your dashboard to be indexable +- `manifest.json` - PWA configuration file, for installing Dashy on mobile devices +- `index.html` - The main index page which initializes the client-side app, copy it from [`/public/index.html`](https://github.com/Lissy93/dashy/blob/master/public/index.html) +- `**.html` - Write your own HTML pages, and access them at `http://my-dashy-instance.local/my-page.html` +- `fonts/` - Custom fonts (be sure to include the ones already in [`public/fonts`](https://github.com/Lissy93/dashy/tree/master/public/fonts) +- `item-icons/` - To use your own icons for items on your dashboard, see [Icons --> Local Icons](/docs/icons#local-icons) +- `web-icons/` - Override Dashy logo +- `widget-resources/` - Fonts, icons and assets for custom widgets + +--- + +## 4. Configure Now that you've got Dashy running, you are going to want to set it up with your own content. Config is written in [YAML Format](https://yaml.org/), and saved in [`/user-data/conf.yml`](https://github.com/Lissy93/dashy/blob/master/user-data/conf.yml). @@ -41,6 +66,7 @@ The format on the config file is pretty straight forward. There are three root a - [`pageInfo`](https://github.com/Lissy93/dashy/blob/master/docs/configuring.md#pageinfo) - Dashboard meta data, like title, description, nav bar links and footer text - [`appConfig`](https://github.com/Lissy93/dashy/blob/master/docs/configuring.md#appconfig-optional) - Dashboard settings, like themes, authentication, language and customization - [`sections`](https://github.com/Lissy93/dashy/blob/master/docs/configuring.md#section) - An array of sections, each including an array of items +- [`pages`](https://github.com/Lissy93/dashy/blob/master/docs/configuring.md#pages-optional) - Have multiples pages in your dashboard You can view a full list of all available config options in the [Configuring Docs](https://github.com/Lissy93/dashy/blob/master/docs/configuring.md). @@ -76,11 +102,11 @@ Notes: - It's also possible to edit your config directly through the UI, and changes will be saved in this file - Check your config against Dashy's schema, with `docker exec -it [container-id] yarn validate-config` - You might find it helpful to look at some examples, a collection of which can be [found here](https://gist.github.com/Lissy93/000f712a5ce98f212817d20bc16bab10) -- After editing your config, the app will rebuild in the background, which may take a minute +- It's also possible to load a remote config, e.g. from a GitHub Gist --- -## 4. Further Customisation +## 5. Further Customisation Once you've got Dashy setup, you'll want to ensure the container is properly healthy, secured, backed up and kept up-to-date. All this is covered in the [Management Docs](https://github.com/Lissy93/dashy/blob/master/docs/management.md). @@ -97,7 +123,7 @@ You might also want to check out the docs for specific features you'd like to us --- -## 5. Final Note +## 6. Final Note If you need any help or support in getting Dashy running, head over to the [Discussions](https://github.com/Lissy93/dashy/discussions) page. If you think you've found a bug, please do [raise it](https://github.com/Lissy93/dashy/issues/new/choose) so it can be fixed. For contact options, see the [Support Page](https://github.com/Lissy93/dashy/blob/master/.github/SUPPORT.md). @@ -118,7 +144,7 @@ yarn build # Build the app yarn start # Start the app ``` -Then edit `./user-data/conf.yml` and rebuild the app with `yarn build` +Then edit `./user-data/conf.yml` ---