mirror of
https://github.com/Lissy93/dashy.git
synced 2024-12-23 17:03:59 +03:00
Update documentation
This commit is contained in:
Liss-Bot
parent
63a1dc928a
commit
fe45bfd99c
@ -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.
|
||||
@ -263,7 +268,7 @@ In NGINX you can specify [control access](https://docs.nginx.com/nginx/admin-gui
|
||||
|
||||
```text
|
||||
server {
|
||||
listen 80;
|
||||
listen 8080;
|
||||
server_name www.dashy.example.com;
|
||||
location / {
|
||||
root /path/to/dashy/;
|
||||
|
||||
@ -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#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.
|
||||
|
||||
@ -1,6 +1,6 @@
|
||||
# Configuring
|
||||
|
||||
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.
|
||||
All app configuration is specified in [`/user-data/conf.yml`](https://github.com/Lissy93/dashy/blob/master/user-data/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
|
||||
|
||||
@ -36,6 +36,7 @@ The following file provides a reference of all supported configuration options.
|
||||
- [`auth`](#appconfigauth-optional) - Built-in authentication setup
|
||||
- [`users`](#appconfigauthusers-optional) - List or users (for simple auth)
|
||||
- [`keycloak`](#appconfigauthkeycloak-optional) - Auth config for Keycloak
|
||||
- [`headerAuth`](#appconfigauthheaderauth-optional) - Auth config for HeaderAuth
|
||||
- [**`sections`**](#section) - List of sections
|
||||
- [`displayData`](#sectiondisplaydata-optional) - Section display settings
|
||||
- [`show/hideForKeycloakUsers`](#sectiondisplaydatahideforkeycloakusers-sectiondisplaydatashowforkeycloakusers-itemdisplaydatahideforkeycloakusers-and-itemdisplaydatashowforkeycloakusers) - Set user controls
|
||||
@ -101,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`
|
||||
@ -142,11 +143,21 @@ 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#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). <br />**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#alternative-authentication-methods).
|
||||
**`enableKeycloak`** | `boolean` | _Optional_ | If set to `true`, then authentication using Keycloak will be enabled. Note that you need to have an instance running, and have also configured `auth.keycloak`. Defaults to `false`
|
||||
**`keycloak`** | `object` | _Optional_ | Config options to point Dashy to your Keycloak server. Requires `enableKeycloak: true`. See [`auth.keycloak`](#appconfigauthkeycloak-optional) for more info
|
||||
**`enableHeaderAuth`** | `boolean` | _Optional_ | If set to `true`, then authentication using HeaderAuth will be enabled. Note that you need to have your web server/reverse proxy running, and have also configured `auth.headerAuth`. Defaults to `false`
|
||||
**`headerAuth`** | `object` | _Optional_ | Config options to point Dashy to your headers for authentication. Requires `enableHeaderAuth: true`. See [`auth.headerAuth`](#appconfigauthheaderauth-optional) for more info
|
||||
**`enableGuestAccess`** | `boolean` | _Optional_ | When set to `true`, an unauthenticated user will be able to access the dashboard, with read-only access, without having to login. Requires `auth.users` to be configured. Defaults to `false`.
|
||||
|
||||
For more info, see the **[Authentication Docs](/docs/authentication)**
|
||||
@ -174,6 +185,15 @@ For more info, see the **[Authentication Docs](/docs/authentication)**
|
||||
|
||||
**[⬆️ Back to Top](#top)**
|
||||
|
||||
## `appConfig.auth.headerAuth` _(optional)_
|
||||
|
||||
**Field** | **Type** | **Required**| **Description**
|
||||
--- | --- | --- | ---
|
||||
**`userHeader`** | `string` | _Optional_ | The Header name which contains username (default: REMOTE_USER). Case insensitive
|
||||
**`proxyWhitelist`** | `array` | Required | An array of Upstream proxy servers to expect authencticated requests from
|
||||
|
||||
**[⬆️ Back to Top](#top)**
|
||||
|
||||
## `appConfig.webSearch` _(optional)_
|
||||
|
||||
**Field** | **Type** | **Required**| **Description**
|
||||
|
||||
@ -7,7 +7,7 @@ Welcome to Dashy, so glad you're here :) Deployment is super easy, and there are
|
||||
If you want to skip the fuss, and [get straight down to it](/docs/quick-start), then you can spin up a new instance of Dashy by running:
|
||||
|
||||
```bash
|
||||
docker run -p 8080:80 lissy93/dashy
|
||||
docker run -p 8080:8080 lissy93/dashy
|
||||
```
|
||||
|
||||
See [Management Docs](/docs/management) for info about securing, monitoring, updating, health checks, auto starting, web server configuration, etc
|
||||
@ -67,8 +67,8 @@ Dashy has a built container image hosted on [Docker Hub](https://hub.docker.com/
|
||||
|
||||
```bash
|
||||
docker run -d \
|
||||
-p 8080:80 \
|
||||
-v /root/my-local-conf.yml:/app/public/conf.yml \
|
||||
-p 8080:8080 \
|
||||
-v /root/my-local-conf.yml:/app/user-data/conf.yml \
|
||||
--name my-dashboard \
|
||||
--restart=always \
|
||||
lissy93/dashy:latest
|
||||
@ -110,9 +110,9 @@ services:
|
||||
container_name: Dashy
|
||||
# Pass in your config file below, by specifying the path on your host machine
|
||||
# volumes:
|
||||
# - /root/my-config.yml:/app/public/conf.yml
|
||||
# - /root/my-config.yml:/app/user-data/conf.yml
|
||||
ports:
|
||||
- 4000:80
|
||||
- 4000:8080
|
||||
# Set any environmental variables
|
||||
environment:
|
||||
- NODE_ENV=production
|
||||
@ -166,8 +166,8 @@ Installing dashy is really simply and fast:
|
||||
|
||||
```bash
|
||||
docker run -d \
|
||||
-p 4000:80 \
|
||||
-v /volume1/docker/dashy/my-local-conf.yml:/app/public/conf.yml \
|
||||
-p 4000:8080 \
|
||||
-v /volume1/docker/dashy/my-local-conf.yml:/app/user-data/conf.yml \
|
||||
--name dashy \
|
||||
--restart=always \
|
||||
lissy93/dashy:latest
|
||||
@ -182,7 +182,7 @@ dashy should be up within 1-2min after you've started the install task procedure
|
||||
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/)
|
||||
|
||||
1. Get Code: `git clone https://github.com/Lissy93/dashy.git` and `cd dashy`
|
||||
2. Configuration: Fill in you're settings in `./public/conf.yml`
|
||||
2. Configuration: Fill in you're settings in `./user-data/conf.yml`
|
||||
3. Install dependencies: `yarn`
|
||||
4. Build: `yarn build`
|
||||
5. Run: `yarn start`
|
||||
|
||||
@ -51,7 +51,7 @@ Dashy should now be being served on <http://localhost:8080/>. Hot reload is enab
|
||||
|
||||
#### 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 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 `/user-data/conf.yml` (or within your Docker container at `/app/user-data/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
|
||||
|
||||
@ -104,7 +104,7 @@ If you are not comfortable with making pull requests, or do not want to modify t
|
||||
|
||||
This section is for, adding a new setting to the config file.
|
||||
|
||||
All of the users config is specified in `./public/conf.yml` - see [Configuring Docs](./configuring) for info.
|
||||
All of the users config is specified in `./user-data/conf.yml` - see [Configuring Docs](./configuring) for info.
|
||||
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
|
||||
|
||||
@ -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
|
||||
|
||||
@ -30,11 +30,11 @@ _The following article is a primer on managing self-hosted apps. It covers every
|
||||
|
||||
Although not essential, you will most likely want to provide several assets to your running app.
|
||||
|
||||
This is easy to do using [Docker Volumes](https://docs.docker.com/storage/volumes/), which lets you share a file or directory between your host system, and the container. Volumes are specified in the Docker run command, or Docker compose file, using the `--volume` or `-v` flags. The value of which consists of the path to the file / directory on your host system, followed by the destination path within the container. Fields are separated by a colon (`:`), and must be in the correct order. For example: `-v ~/alicia/my-local-conf.yml:/app/public/conf.yml`
|
||||
This is easy to do using [Docker Volumes](https://docs.docker.com/storage/volumes/), which lets you share a file or directory between your host system, and the container. Volumes are specified in the Docker run command, or Docker compose file, using the `--volume` or `-v` flags. The value of which consists of the path to the file / directory on your host system, followed by the destination path within the container. Fields are separated by a colon (`:`), and must be in the correct order. For example: `-v ~/alicia/my-local-conf.yml:/app/user-data/conf.yml`
|
||||
|
||||
In Dashy, commonly configured resources include:
|
||||
|
||||
- `./public/conf.yml` - Your main application config file
|
||||
- `./user-data/conf.yml` - Your main application config file
|
||||
- `./public/item-icons` - A directory containing your own icons. This allows for offline access, and better performance than fetching from a CDN
|
||||
- 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.
|
||||
@ -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)
|
||||
|
||||
@ -238,7 +240,7 @@ Once you've generated your SSL cert, you'll need to pass it to Dashy. This can b
|
||||
|
||||
```bash
|
||||
docker run -d \
|
||||
-p 8080:80 \
|
||||
-p 8080:8080 \
|
||||
-v ~/my-private-key.key:/etc/ssl/certs/dashy-priv.key:ro \
|
||||
-v ~/my-public-key.pem:/etc/ssl/certs/dashy-pub.pem:ro \
|
||||
lissy93/dashy:latest
|
||||
@ -276,9 +278,9 @@ services:
|
||||
container_name: Dashy
|
||||
image: lissy93/dashy
|
||||
volumes:
|
||||
- /root/my-config.yml:/app/public/conf.yml
|
||||
- /root/my-config.yml:/app/user-data/conf.yml
|
||||
ports:
|
||||
- 4000:80
|
||||
- 4000:8080
|
||||
environment:
|
||||
- BASE_URL=/my-dashboard
|
||||
restart: unless-stopped
|
||||
@ -550,7 +552,7 @@ upstream dashy {
|
||||
}
|
||||
|
||||
server {
|
||||
listen 80;
|
||||
listen 8080;
|
||||
server_name dashy.mydomain.com;
|
||||
|
||||
# Setup SSL
|
||||
@ -577,7 +579,7 @@ Similarly, a basic `Caddyfile` might look like:
|
||||
|
||||
```text
|
||||
dashy.example.com {
|
||||
reverse_proxy / nginx:80
|
||||
reverse_proxy / nginx:8080
|
||||
}
|
||||
```
|
||||
|
||||
@ -614,7 +616,7 @@ To prevent known container escape vulnerabilities, which typically end in escala
|
||||
Docker enables you to limit resource consumption (CPU, memory, disk) on a per-container basis. This not only enhances system performance, but also prevents a compromised container from consuming a large amount of resources, in order to disrupt service or perform malicious activities. To learn more, see the [Resource Constraints Docs](https://docs.docker.com/config/containers/resource_constraints/)
|
||||
|
||||
For example, to run Dashy with max of 1GB ram, and max of 50% of 1 CP core:
|
||||
`docker run -d -p 8080:80 --cpus=".5" --memory="1024m" lissy93/dashy:latest`
|
||||
`docker run -d -p 8080:8080 --cpus=".5" --memory="1024m" lissy93/dashy:latest`
|
||||
|
||||
### Don't Run as Root
|
||||
|
||||
@ -629,7 +631,7 @@ One of the best ways to prevent privilege escalation attacks, is to configure th
|
||||
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`.
|
||||
|
||||
With Docker run, you specify it like:
|
||||
`docker run --user 1000:1000 -p 8080:80 lissy93/dashy`
|
||||
`docker run --user 1000:1000 -p 8080:8080 lissy93/dashy`
|
||||
|
||||
Of if you're using Docker-compose, you could use an environmental variable
|
||||
|
||||
@ -639,7 +641,7 @@ services:
|
||||
dashy:
|
||||
image: lissy93/dashy
|
||||
user: ${CURRENT_UID}
|
||||
ports: [ 4000:80 ]
|
||||
ports: [ 4000:8080 ]
|
||||
```
|
||||
|
||||
And then to set the variable, and start the container, run: `CURRENT_UID=$(id -u):$(id -g) docker-compose up`
|
||||
@ -659,7 +661,7 @@ version: "3.8"
|
||||
services:
|
||||
dashy:
|
||||
image: lissy93/dashy
|
||||
ports: [ 4000:80 ]
|
||||
ports: [ 4000:8080 ]
|
||||
cap_drop:
|
||||
- ALL
|
||||
cap_add:
|
||||
@ -675,7 +677,7 @@ services:
|
||||
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)).
|
||||
|
||||
Run Command:
|
||||
`docker run --security-opt=no-new-privileges:true -p 8080:80 lissy93/dashy`
|
||||
`docker run --security-opt=no-new-privileges:true -p 8080:8080 lissy93/dashy`
|
||||
|
||||
Docker Compose
|
||||
|
||||
@ -701,14 +703,14 @@ You can specify that a specific volume should be read-only by appending `:ro` to
|
||||
|
||||
```bash
|
||||
docker run -d \
|
||||
-p 8080:80 \
|
||||
-v ~/dashy-conf.yml:/app/public/conf.yml \
|
||||
-p 8080:8080 \
|
||||
-v ~/dashy-conf.yml:/app/user-data/conf.yml \
|
||||
-v ~/dashy-icons:/app/public/item-icons:ro \
|
||||
-v ~/dashy-theme.scss:/app/src/styles/user-defined-themes.scss:ro \
|
||||
lissy93/dashy:latest
|
||||
```
|
||||
|
||||
You can also prevent a container from writing any changes to volumes on your host's disk, using the `--read-only` flag. Although, for Dashy, you will not be able to write config changes to disk, when edited through the UI with this method. You could make this work, by specifying the config directory as a temp write location, with `--tmpfs /app/public/conf.yml` - but that this will not write the volume back to your host.
|
||||
You can also prevent a container from writing any changes to volumes on your host's disk, using the `--read-only` flag. Although, for Dashy, you will not be able to write config changes to disk, when edited through the UI with this method. You could make this work, by specifying the config directory as a temp write location, with `--tmpfs /app/user-data/conf.yml` - but that this will not write the volume back to your host.
|
||||
|
||||
### Set the Logging Level
|
||||
|
||||
@ -778,8 +780,8 @@ Create a new file in `/etc/nginx/sites-enabled/dashy`
|
||||
|
||||
```text
|
||||
server {
|
||||
listen 80;
|
||||
listen [::]:80;
|
||||
listen 8080;
|
||||
listen [::]:8080;
|
||||
|
||||
root /var/www/dashy/html;
|
||||
index index.html;
|
||||
@ -898,7 +900,7 @@ Similar to above, you'll first need to fork and clone Dashy to your local system
|
||||
|
||||
Then, either use Dashy's default [`Dockerfile`](https://github.com/Lissy93/dashy/blob/master/Dockerfile) as is, or modify it according to your needs.
|
||||
|
||||
To build and deploy locally, first build the app with: `docker build -t dashy .`, and then start the app with `docker run -p 8080:80 --name my-dashboard dashy`. Or modify the `docker-compose.yml` file, replacing `image: lissy93/dashy` with `build: .` and run `docker compose up`.
|
||||
To build and deploy locally, first build the app with: `docker build -t dashy .`, and then start the app with `docker run -p 8080:8080 --name my-dashboard dashy`. Or modify the `docker-compose.yml` file, replacing `image: lissy93/dashy` with `build: .` and run `docker compose up`.
|
||||
|
||||
Your container should now be running, and will appear in the list when you run `docker container ls –a`. If you'd like to enter the container, run `docker exec -it [container-id] /bin/ash`.
|
||||
|
||||
|
||||
@ -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
|
||||
|
||||
@ -2,7 +2,7 @@
|
||||
|
||||
Welcome to Dashy! So glad you're here 😊 In a couple of minutes, you'll have your new dashboard up and running 🚀
|
||||
|
||||
**TLDR;** Run `docker run -p 8080:80 lissy93/dashy`, then open `http://localhost:8080`
|
||||
**TLDR;** Run `docker run -p 8080:8080 lissy93/dashy`, then open `http://localhost:8080`
|
||||
|
||||
---
|
||||
|
||||
@ -19,8 +19,8 @@ To pull the latest image, and build and start the app run:
|
||||
|
||||
```bash
|
||||
docker run -d \
|
||||
-p 8080:80 \
|
||||
-v ~/my-conf.yml:/app/public/conf.yml \
|
||||
-p 8080:8080 \
|
||||
-v ~/my-conf.yml:/app/user-data/conf.yml \
|
||||
--name my-dashboard \
|
||||
--restart=always \
|
||||
lissy93/dashy:latest
|
||||
@ -35,7 +35,7 @@ Your dashboard should now be up and running at `http://localhost:8080` (or your
|
||||
## 3. 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 [`/public/conf.yml`](https://github.com/Lissy93/dashy/blob/master/public/conf.yml).
|
||||
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).
|
||||
The format on the config file is pretty straight forward. There are three root attributes:
|
||||
|
||||
- [`pageInfo`](https://github.com/Lissy93/dashy/blob/master/docs/configuring.md#pageinfo) - Dashboard meta data, like title, description, nav bar links and footer text
|
||||
@ -72,7 +72,7 @@ sections: # An array of sections
|
||||
Notes:
|
||||
|
||||
- You can use a Docker volume to pass a config file from your host system to the container
|
||||
- E.g. `-v ./host-system/my-local-conf.yml:/app/public/conf.yml`
|
||||
- E.g. `-v ./host-system/my-local-conf.yml:/app/user-data/conf.yml`
|
||||
- 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)
|
||||
@ -118,7 +118,7 @@ yarn build # Build the app
|
||||
yarn start # Start the app
|
||||
```
|
||||
|
||||
Then edit `./public/conf.yml` and rebuild the app with `yarn build`
|
||||
Then edit `./user-data/conf.yml` and rebuild the app with `yarn build`
|
||||
|
||||
---
|
||||
|
||||
@ -129,7 +129,7 @@ Don't have a server? No problem! You can run Dashy for free on Netlify (as well
|
||||
1. Fork Dashy's repository on GitHub
|
||||
2. [Log in](app.netlify.com/login/) to Netlify with GitHub
|
||||
3. Click "New site from Git" and select your forked repo, then click **Deploy**!
|
||||
4. You can then edit the config in `./public/conf.yml` in your repo, and Netlify will rebuild the app
|
||||
4. You can then edit the config in `./user-data/conf.yml` in your repo, and Netlify will rebuild the app
|
||||
|
||||
---
|
||||
|
||||
|
||||
@ -156,7 +156,7 @@ If you're getting an error about scenarios, then you've likely installed the wro
|
||||
Alternatively, as a workaround, you have several options:
|
||||
|
||||
- Try using [NPM](https://www.npmjs.com/get-npm) instead: So clone, cd, then run `npm install`, `npm run build` and `npm start`
|
||||
- Try using [Docker](https://www.docker.com/get-started) instead, and all of the system setup and dependencies will already be taken care of. So from within the directory, just run `docker build -t lissy93/dashy .` to build, and then use docker start to run the project, e.g: `docker run -it -p 8080:80 lissy93/dashy` (see the [deploying docs](https://github.com/Lissy93/dashy/blob/master/docs/deployment.md#deploy-with-docker) for more info)
|
||||
- Try using [Docker](https://www.docker.com/get-started) instead, and all of the system setup and dependencies will already be taken care of. So from within the directory, just run `docker build -t lissy93/dashy .` to build, and then use docker start to run the project, e.g: `docker run -it -p 8080:8080 lissy93/dashy` (see the [deploying docs](https://github.com/Lissy93/dashy/blob/master/docs/deployment.md#deploy-with-docker) for more info)
|
||||
|
||||
---
|
||||
|
||||
@ -234,7 +234,7 @@ Version 2.0.4 introduced changes to how the config is read, and the app is build
|
||||
|
||||
```yaml
|
||||
volumes:
|
||||
- /srv/dashy/conf.yml:/app/public/conf.yml
|
||||
- /srv/dashy/conf.yml:/app/user-data/conf.yml
|
||||
- /srv/dashy/item-icons:/app/public/item-icons
|
||||
```
|
||||
|
||||
@ -273,12 +273,12 @@ 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:
|
||||
"/app/user-data/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/user-data/conf.yml`
|
||||
|
||||
---
|
||||
|
||||
|
||||
@ -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)
|
||||
@ -1554,6 +1555,19 @@ Displays the number of queries blocked by [Pi-Hole](https://pi-hole.net/).
|
||||
apiKey: xxxxxxxxxxxxxxxxxxxxxxx
|
||||
```
|
||||
|
||||
> [!TIP]
|
||||
> In order to avoid leaking secret data, both `hostname` and `apiKey` can leverage environment variables. Simply pass the name of the variable, which MUST start with `VUE_APP_`.
|
||||
|
||||
```yaml
|
||||
- type: pi-hole-stats
|
||||
options:
|
||||
hostname: VUE_APP_pihole_ip
|
||||
apiKey: VUE_APP_pihole_key
|
||||
```
|
||||
|
||||
> [!IMPORTANT]
|
||||
> You will need to restart the server (or the docker image) if adding/editing an env var for this to be refreshed.
|
||||
|
||||
#### Info
|
||||
|
||||
- **CORS**: 🟢 Enabled
|
||||
@ -2843,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#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).
|
||||
|
||||
Loading…
Reference in New Issue
Block a user