tyler.durden/dashy
1
0
Fork 0
mirror of https://github.com/Lissy93/dashy.git synced 2025-07-27 15:44:27 +02:00
Code Issues Packages Projects Releases Wiki Activity

Update documentation

Browse Source
This commit is contained in:
Liss-Bot 2024-03-07 18:23:09 +00:00
parent f8d3632615
commit f5d4e55804
3 changed files with 39 additions and 39 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
docs/authentication.md
View File

@ -114,7 +114,7 @@ To disable all UI config features, including View Config, set `disableConfigurat
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)**
**[⬆️ Back to Top](#top)**
---
@ -365,4 +365,4 @@ There are also authentication services, such as [Ory.sh](https://www.ory.sh/), [
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)**
**[⬆️ Back to Top](#top)**

36
docs/configuring.md
View File

@ -63,7 +63,7 @@ The following file provides a reference of all supported configuration options.
**`sections`** | `array` | Required | An array of sections, each containing an array of items, which will be displayed as links. See [`section`](#section)
**`pages`** | `array` | _Optional_ | An array additional config files, used for multi-page dashboards. See [`pages`](#pages-optional)
**[⬆️ Back to Top](#configuring)**
**[⬆️ Back to Top](#top)**
## `PageInfo`
@ -75,7 +75,7 @@ The following file provides a reference of all supported configuration options.
**`footerText`** | `string` | _Optional_ | Text to display in the footer (note that this will override the default footer content). This can also include HTML and inline CSS
**`logo`** | `string` | _Optional_ | The path to an image to display in the header (to the right of the title). This can be either local, where `/` is the root of `./public`, or any remote image, such as `https://i.ibb.co/yhbt6CY/dashy.png`. It's recommended to scale your image down, so that it doesn't impact load times
**[⬆️ Back to Top](#configuring)**
**[⬆️ Back to Top](#top)**
## `pageInfo.navLinks` _(optional)_
@ -85,7 +85,7 @@ The following file provides a reference of all supported configuration options.
**`path`** | `string` | Required | The URL to navigate to when clicked. Can be relative (e.g. `/about`) or absolute (e.g. `https://example.com` or `http://192.168.1.1`)
**`target`** | `string` | _Optional_ | The opening method (external links only). Can be either `newtab`, `sametab`, `top` or `parent`. Defaults to `newtab`
**[⬆️ Back to Top](#configuring)**
**[⬆️ Back to Top](#top)**
## `pages[]` _(optional)_
@ -94,7 +94,7 @@ The following file provides a reference of all supported configuration options.
**`name`** | `string` | Required | A unique name for that page
**`path`** | `string` | Required | The path (local or remote) to the config file to use.<br />For files located within `/public`, you only need to specify filename, for externally hosted files you must include the full URL
**[⬆️ Back to Top](#configuring)**
**[⬆️ Back to Top](#top)**
## `appConfig` _(optional)_
@ -138,7 +138,7 @@ The following file provides a reference of all supported configuration options.
**`enableServiceWorker`** | `boolean` | _Optional_ | Service workers cache web applications to improve load times and offer basic offline functionality, and are enabled by default in Dashy. The service worker can sometimes cause older content to be cached, requiring the app to be hard-refreshed. If you do not want SW functionality, or are having issues with caching, set this property to `false` to disable all service workers.
**`disableContextMenu`** | `boolean` | _Optional_ | If set to `true`, the custom right-click context menu will be disabled. Defaults to `false`.
**[⬆️ Back to Top](#configuring)**
**[⬆️ Back to Top](#top)**
## `appConfig.auth` _(optional)_
@ -151,7 +151,7 @@ The following file provides a reference of all supported configuration options.
For more info, see the **[Authentication Docs](/docs/authentication)**
**[⬆️ Back to Top](#configuring)**
**[⬆️ Back to Top](#top)**
## `appConfig.auth.users` _(optional)_
@ -161,7 +161,7 @@ For more info, see the **[Authentication Docs](/docs/authentication)**
**`hash`** | `string` | Required | A SHA-256 hashed password
**`type`** | `string` | _Optional_ | The user type, either admin or normal
**[⬆️ Back to Top](#configuring)**
**[⬆️ Back to Top](#top)**
## `appConfig.auth.keycloak` _(optional)_
@ -172,7 +172,7 @@ For more info, see the **[Authentication Docs](/docs/authentication)**
**`clientId`** | `string` | Required | The Client ID of the client you created for use with Dashy
**`legacySupport`** | `boolean` | _Optional_ | If using Keycloak 17 or older, then set this to `true`
**[⬆️ Back to Top](#configuring)**
**[⬆️ Back to Top](#top)**
## `appConfig.webSearch` _(optional)_
@ -184,7 +184,7 @@ For more info, see the **[Authentication Docs](/docs/authentication)**
**`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)**
**[⬆️ Back to Top](#top)**
## `appConfig.hideComponents` _(optional)_
@ -196,7 +196,7 @@ For more info, see the **[Authentication Docs](/docs/authentication)**
**`hideSettings`** | `boolean` | _Optional_ | If set to `true`, the settings menu will be initially collapsed. Defaults to `false`
**`hideFooter`** | `boolean` | _Optional_ | If set to `true`, the footer will not be visible. Defaults to `false`
**[⬆️ Back to Top](#configuring)**
**[⬆️ Back to Top](#top)**
## `section`
@ -208,7 +208,7 @@ For more info, see the **[Authentication Docs](/docs/authentication)**
**`widgets`** | `array` | _Optional_ | An array of widgets to be displayed within the section. See [`widget`](#sectionwidget-optional)
**`displayData`** | `object` | _Optional_ | Meta-data to optionally override display settings for a given section. See [`displayData`](#sectiondisplaydata-optional)
**[⬆️ Back to Top](#configuring)**
**[⬆️ Back to Top](#top)**
## `section.item`
@ -233,7 +233,7 @@ For more info, see the **[Authentication Docs](/docs/authentication)**
**`provider`** | `string` | _Optional_ | The name of the provider for a given service, useful for when including hosted apps. In some themes, this is visible under the item name
**`displayData`** | `object` | _Optional_ | Meta-data to optionally override display settings for a given item. See [`displayData`](#itemdisplaydata-optional)
**[⬆️ Back to Top](#configuring)**
**[⬆️ Back to Top](#top)**
## `item.displayData` _(optional)_
@ -245,7 +245,7 @@ For more info, see the **[Authentication Docs](/docs/authentication)**
**`hideForKeycloakUsers`** | `object` | _Optional_ | Current item will be visible to all keycloak users, except for those configured via these groups and roles. See `hideForKeycloakUsers`
**`showForKeycloakUsers`** | `object` | _Optional_ | Current item will be hidden from all keycloak users, except for those configured via these groups and roles. See `showForKeycloakUsers`
**[⬆️ Back to Top](#configuring)**
**[⬆️ Back to Top](#top)**
## `section.widgets` _(optional)_
@ -259,7 +259,7 @@ For more info, see the **[Authentication Docs](/docs/authentication)**
**`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
**[⬆️ Back to Top](#configuring)**
**[⬆️ Back to Top](#top)**
## `section.displayData` _(optional)_
@ -282,7 +282,7 @@ For more info, see the **[Authentication Docs](/docs/authentication)**
**`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 keycloak users, except for those configured via these groups and roles. See `showForKeycloakUsers`
**[⬆️ Back to Top](#configuring)**
**[⬆️ Back to Top](#top)**
## `section.icon` and `section.item.icon`
@ -290,7 +290,7 @@ For more info, see the **[Authentication Docs](/docs/authentication)**
--- | --- | --- | ---
**`icon`** | `string` | _Optional_ | The icon for a given item or section. <br />See [Icon Docs](/docs/icons) for all available supported icon types, including: auto-fetched favicons, generative icons, emoji icons, home-lab service logos, font-awesome, simple-icons, material icons, and icons specified by URL
**[⬆️ Back to Top](#configuring)**
**[⬆️ Back to Top](#top)**
## `section.displayData.hideForKeycloakUsers`, `section.displayData.showForKeycloakUsers`, `item.displayData.hideForKeycloakUsers` and `item.displayData.showForKeycloakUsers`
@ -299,7 +299,7 @@ For more info, see the **[Authentication Docs](/docs/authentication)**
**`groups`** | `string[]` | _Optional_ | Current Section or Item will be hidden or shown based on the user having any of the groups in this list
**`roles`** | `string[]` | _Optional_ | Current Section or Item will be hidden or shown based on the user having any of the roles in this list
**[⬆️ Back to Top](#configuring)**
**[⬆️ Back to Top](#top)**
---
@ -377,4 +377,4 @@ If you need any help, feel free to [Raise an Issue](https://github.com/Lissy93/d
Happy Configuring 🤓🔧
**[⬆️ Back to Top](#configuring)**
**[⬆️ Back to Top](#top)**

38
docs/management.md
View File

@ -39,7 +39,7 @@ In Dashy, commonly configured resources include:
- Also within `./public` you'll find standard website assets, including `favicon.ico`, `manifest.json`, `robots.txt`, etc. There's no need to pass these in, but you can do so if you wish
- `/src/styles/user-defined-themes.scss` - A stylesheet for applying custom CSS to your app. You can also write your own themes here.
**[⬆️ Back to Top](#management)**
**[⬆️ Back to Top](#top)**
---
@ -49,7 +49,7 @@ If you're running an app in Docker, then commands will need to be passed to the
Dashy has several commands that can be used for various tasks, you can find a list of these either in the [Developing Docs](/docs/developing#project-commands), or by looking at the [`package.json`](https://github.com/Lissy93/dashy/blob/master/package.json#L5). These can be used by running `yarn [command-name]`.
**[⬆️ Back to Top](#management)**
**[⬆️ Back to Top](#top)**
---
@ -68,7 +68,7 @@ docker run -d \
willfarrell/autoheal
```
**[⬆️ Back to Top](#management)**
**[⬆️ Back to Top](#top)**
---
@ -90,7 +90,7 @@ You can also view logs, resource usage and other info as well as manage your ent
Docker supports using [Prometheus](https://prometheus.io/) to collect logs, which can then be visualized using a platform like [Grafana](https://grafana.com/). For more info, see [this guide](https://docs.docker.com/config/daemon/prometheus/). If you need to route your logs to a remote syslog, then consider using [logspout](https://github.com/gliderlabs/logspout). For enterprise-grade instances, there are managed services, that make monitoring container logs and metrics very easy, such as [Sematext](https://sematext.com/blog/docker-container-monitoring-with-sematext/) with [Logagent](https://github.com/sematext/logagent-js).
**[⬆️ Back to Top](#management)**
**[⬆️ Back to Top](#top)**
---
@ -102,7 +102,7 @@ For Podman, you can use `systemd` to create a service that launches your contain
To restart the container after something within it has crashed, consider using [`docker-autoheal`](https://github.com/willfarrell/docker-autoheal) by @willfarrell, a service that monitors and restarts unhealthy containers. For more info, see the [Healthchecks](#healthchecks) section above.
**[⬆️ Back to Top](#management)**
**[⬆️ Back to Top](#top)**
---
@ -139,7 +139,7 @@ For more information, see the [Watchtower Docs](https://containrrr.dev/watchtowe
Stop your current instance of Dashy, then navigate into the source directory. Pull down the latest code, with `git pull origin master`, then update dependencies with `yarn`, rebuild with `yarn build`, and start the server again with `yarn start`.
**[⬆️ Back to Top](#management)**
**[⬆️ Back to Top](#top)**
---
@ -201,7 +201,7 @@ Since Dashy is open source, and freely available, providing you're configuration
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)
**[⬆️ Back to Top](#management)**
**[⬆️ Back to Top](#top)**
---
@ -210,7 +210,7 @@ Dashy also has a built-in cloud backup feature, which is free for personal users
If you need to periodically schedule the running of a given command on Dashy (or any other container), then a useful tool for doing so it [ofelia](https://github.com/mcuadros/ofelia). This runs as a Docker container and is really useful for things like backups, logging, updating, notifications, etc. Crons are specified using Go's crontab format, and a useful tool for visualizing this is [crontab.guru](https://crontab.guru/). This can also be done natively with Alpine: `docker run -it alpine ls /etc/periodic`.
I recommend combining this with [healthchecks](https://github.com/healthchecks/healthchecks) for easy monitoring of jobs, and failure notifications.
**[⬆️ Back to Top](#management)**
**[⬆️ Back to Top](#top)**
---
@ -248,7 +248,7 @@ By default the SSL port is `443` within a Docker container, or `4001` if running
Once everything is setup, you can verify your site is secured using a tool like [SSL Checker](https://www.sslchecker.com/sslchecker).
**[⬆️ Back to Top](#management)**
**[⬆️ Back to Top](#top)**
---
@ -256,7 +256,7 @@ Once everything is setup, you can verify your site is secured using a tool like
Dashy natively supports secure authentication using KeyCloak. There is also a Simple Auth feature that doesn't require any additional setup. Usage instructions for both, as well as alternative auth methods, has now moved to the **[Authentication Docs](/docs/authentication)** page.
**[⬆️ Back to Top](#management)**
**[⬆️ Back to Top](#top)**
---
@ -290,7 +290,7 @@ services:
start_period: 40s
```
**[⬆️ Back to Top](#management)**
**[⬆️ Back to Top](#top)**
---
@ -308,7 +308,7 @@ environment:
You can also do the same thing with the docker run command, using the [`--env`](https://docs.docker.com/engine/reference/commandline/run/#set-environment-variables--e---env---env-file) flag.
If you've got many environmental variables, you might find it useful to put them in a [`.env` file](https://docs.docker.com/compose/env-file/). Similarly, for Docker run you can use [`--env-file`](https://docs.docker.com/engine/reference/commandline/run/#set-environment-variables--e---env---env-file) if you'd like to pass in a file containing all your environmental variables.
**[⬆️ Back to Top](#management)**
**[⬆️ Back to Top](#top)**
---
@ -393,7 +393,7 @@ Header always set Access-Control-Allow-Origin "*"
request_header_access Authorization allow all
```
**[⬆️ Back to Top](#management)**
**[⬆️ Back to Top](#top)**
---
@ -523,7 +523,7 @@ There's so much more you can do with Ngrok, such as exposing a directory as a fi
It's worth noting that Ngrok isn't the only option here, other options include: [FRP](https://github.com/fatedier/frp), [Inlets](https://inlets.dev), [Local Tunnel](https://localtunnel.me/), [TailScale](https://tailscale.com/), etc. Check out [Awesome Tunneling](https://github.com/anderspitman/awesome-tunneling) for a list of alternatives.
**[⬆️ Back to Top](#management)**
**[⬆️ Back to Top](#top)**
---
@ -583,7 +583,7 @@ dashy.example.com {
For more info, [this guide](https://thehomelab.wiki/books/dns-reverse-proxy/page/create-domain-records-to-point-to-your-home-server-on-cloudflare-using-nginx-progy-manager) on Setting up Domains with NGINX Proxy Manager and CloudFlare may be useful.
**[⬆️ Back to Top](#management)**
**[⬆️ Back to Top](#top)**
---
@ -744,7 +744,7 @@ Docker supports several modules that let you write your own security profiles.
[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)**
**[⬆️ Back to Top](#top)**
---
@ -878,7 +878,7 @@ Create a file names `firebase.json`, and populate it with something similar to:
8. If you need to change the port, click 'Add environmental variable', give it the name 'PORT', choose a port number and press 'Save'.
9. Dashy should now be running at your selected path an on a given port
**[⬆️ Back to Top](#management)**
**[⬆️ Back to Top](#top)**
---
@ -888,7 +888,7 @@ If you'd like to make any code changes to the app, and deploy your modified vers
The first step is to fork the project on GitHub, and clone it to your local system. Next, install the dependencies (`yarn`), and start the development server (`yarn dev`) and visit `localhost:8080` in your browser. You can then make changes to the codebase, and see the live app update in real-time. Once you've finished, running `yarn build` will build the app for production, and output the assets into `./dist` which can then be deployed using a web server, CDN or the built-in Node server with `yarn start`. For more info on all of this, take a look at the [Developing Docs](/docs/developing). To build your own Docker container from the modified app, see [Building your Own Container](#building-your-own-container)
**[⬆️ Back to Top](#management)**
**[⬆️ Back to Top](#top)**
---
@ -905,6 +905,6 @@ Your container should now be running, and will appear in the list when you run `
You may wish to upload your image to a container registry for easier access. Note that if you choose to do this on a public registry, please name your container something other than just 'dashy', to avoid confusion with the official image.
You can push your build image, by running: `docker push ghcr.io/OWNER/IMAGE_NAME:latest`. You will first need to authenticate, this can be done by running `echo $CR_PAT | docker login ghcr.io -u USERNAME --password-stdin`, where `CR_PAT` is an environmental variable containing a token generated from your GitHub account. For more info, see the [Container Registry Docs](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-container-registry).
**[⬆️ Back to Top](#management)**
**[⬆️ Back to Top](#top)**
---