From 572758f3930fe8040dbc30774a984258f69a062b Mon Sep 17 00:00:00 2001 From: liss-bot Date: Sun, 9 Jan 2022 01:28:13 +0000 Subject: [PATCH] Auto Publish new pages --- authentication.md | 18 +++++++++++++++++- configuring.md | 11 +++++++++++ credits.md | 9 ++++++++- deployment.md | 33 +++++++++++++++++++++++++++++---- developing.md | 1 + 5 files changed, 66 insertions(+), 6 deletions(-) diff --git a/authentication.md b/authentication.md index e5de308..b429ade 100644 --- a/authentication.md +++ b/authentication.md @@ -143,9 +143,25 @@ appConfig: realm: 'alicia-homelab' clientId: 'dashy' ``` + +### 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 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 sections `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 + displayData: + showForKeycloakUsers: + roles: ['canViewDevResources'] + hideForKeycloakUsers: + groups: ['ProductTeam'] +``` + Your app is now secured :) When you load Dashy, it will redirect to your Keycloak login page, and any user without valid credentials will be prevented from accessing your dashboard. -From within the Keycloak console, you can then configure things like user permissions, time outs, password policies, access, etc. You can also backup your full Keycloak config, and it is recommended to do this, along with your Dashy config. You can spin up both Dashy and Keycloak simultaneously and restore both applications configs using a `docker-compose.yml` file, and this is recommended. +From within the Keycloak console, you can then configure things like time-outs, password policies, etc. You can also backup your full Keycloak config, and it is recommended to do this, along with your Dashy config. You can spin up both Dashy and Keycloak simultaneously and restore both applications configs using a `docker-compose.yml` file, and this is recommended. --- diff --git a/configuring.md b/configuring.md index bd975fd..9c2a32c 100644 --- a/configuring.md +++ b/configuring.md @@ -228,6 +228,8 @@ For more info, see the **[Authentication Docs](/docs/authentication.md)** **`hideForUsers`** | `string[]` | _Optional_ | Current section will be visible to all users, except for those specified in this list **`showForUsers`** | `string[]` | _Optional_ | Current section will be hidden from all users, except for those specified in this list **`hideForGuests`** | `boolean` | _Optional_ | Current section will be visible for logged in users, but not for guests (see `appConfig.enableGuestAccess`). Defaults to `false` +**`hideForKeycloakUsers`** | `object` | _Optional_ | Current section will be visible to all keycloak users, except for those configured via these groups and roles. See `hideForKeycloakUsers` +**`showForKeycloakUsers`** | `object` | _Optional_ | Current section will be hidden from all keyclaok users, except for those configured via these groups and roles. See `showForKeycloakUsers` **[⬆️ Back to Top](#configuring)** @@ -239,6 +241,15 @@ For more info, see the **[Authentication Docs](/docs/authentication.md)** **[⬆️ Back to Top](#configuring)** +### `section.displayData.hideForKeycloakUsers` and `section.displayData.showForKeycloakUsers` + +**Field** | **Type** | **Required**| **Description** +--- |------------| --- | --- +**`groups`** | `string[]` | _Optional_ | Current Section will be hidden or shown based on the user having any of the groups in this list +**`roles`** | `string[]` | _Optional_ | Current Section will be hidden or shown based on the user having any of the roles in this list + +**[⬆️ Back to Top](#configuring)** + --- ## Notes diff --git a/credits.md b/credits.md index 34994a4..3a2d2e4 100644 --- a/credits.md +++ b/credits.md @@ -27,10 +27,17 @@ - KierenConnell + KierenConnell
Kieren Connell + + + + ratty222 +
+ ratty222 + diff --git a/deployment.md b/deployment.md index 9f0508a..83f7683 100644 --- a/deployment.md +++ b/deployment.md @@ -16,6 +16,8 @@ Once you've got Dashy up and running, you'll want to configure it with your own - [Deploy with Docker](#deploy-with-docker) - [Using Docker Compose](#using-docker-compose) +- [Unraid](#unraid) +- [Synology NAS](#synology-nas) - [Build from Source](#build-from-source) - [Hosting with CDN](#hosting-with-cdn) - [Run as executable](#run-as-executable) @@ -23,7 +25,9 @@ Once you've got Dashy up and running, you'll want to configure it with your own - [Deploy to cloud service](#deploy-to-cloud-service) - [Use managed instance](#use-managed-instance) -### Deploy with Docker +--- + +## Deploy with Docker **Container Info**: [ ![Docker Supported Architecture](https://img.shields.io/badge/Architectures-amd64%20|%20arm32v7%20|%20arm64v8-6ba6e5) @@ -66,7 +70,9 @@ If you're deploying Dashy on a modern ARM-based board, such as a Raspberry Pi (2 The image defaults to `:latest`, but you can instead specify a specific version, e.g. `docker pull lissy93/dashy:release-1.5.0` -### Using Docker Compose +--- + +## Using Docker Compose Using Docker Compose can be useful for saving your specific config in files, without having to type out a long run command each time. Save compose config as a YAML file, and then run `docker compose up -d` (optionally use the `-f` flag to specify file location, if it isn't located at `./docker-compose.yml`), `-d` is detached mode (not running in the foreground of your terminal). Compose is also useful if you are using clusters, as the format is very similar to stack files, used with Docker Swarm. @@ -106,7 +112,21 @@ You can use a different tag, by for example setting `image: lissy93/dashy:arm64v If you are building from source, and would like to use one of the [other Dockerfiles](https://github.com/Lissy93/dashy/tree/master/docker), then under `services.dashy` first set `context: .`, then specify the the path to the dockerfile, e.g. `dockerfile: ./docker/Dockerfile-arm32v7` -### Build from Source +--- + +## Unraid + +// TODO + +--- + +## Synology NAS + +// TODO + +--- + +## Build from Source If you do not want to use Docker, you can run Dashy directly on your host system. For this, you will need both [git](https://git-scm.com/downloads) and the latest or LTS version of [Node.js](https://nodejs.org/) installed, and optionally [yarn](https://yarnpkg.com/) @@ -116,6 +136,8 @@ If you do not want to use Docker, you can run Dashy directly on your host system 4. Build: `yarn build` 5. Run: `yarn start` +--- + ### 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. @@ -236,13 +258,16 @@ yarn build surge ./dist ``` +--- -### Hosting with CDN +## Hosting with CDN Once Dashy has been built, it is effectivley just a static web app. This means that it can be served up with pretty much any static host, CDN or web server. To host Dashy through a CDN, the steps are very similar to building from source: clone the project, cd into it, install dependencies, write your config file and build the app. Once build is complete you will have a `./dist` directory within Dashy's root, and this is the build application which is ready to be served up. However without Dashy's node server, there are a couple of features that will be unavailible to you, including: Writing config changes to disk through the UI, triggering a rebuild through the UI and application status checks. Everything else will work fine. +--- + ## Requirements diff --git a/developing.md b/developing.md index 6f8ac2b..22672f1 100644 --- a/developing.md +++ b/developing.md @@ -285,6 +285,7 @@ Styleguides: │ ├── InitServiceWorker.js # Initializes and manages service worker, if enabled │ ├── Search.js # Helper functions for searching/ filtering items in all views │ ├── JsonToYaml.js # Function that parses and converts raw JSON into valid YAML +│ ├── KeycloakAuth.js # Singleton class to manage Keycloak authentication │ ├── languages.js # Handles fetching, switching and validating languages │ ╰── ThemeHelper.js # Function that handles the fetching and setting of user themes ╰── views # Directory of available pages, corresponding to available routes