Skip to content

armgit / dashy

Public Imported from GitHub
0

πŸš€ A self-hostable personal dashboard built for you. Includes status-checking, widgets, themes, icon packs, a UI editor and tons more!

πŸ“ Updates auth docs with latest changes

Alicia Sykes7dc5c103c2a0
diff --git a/docs/authentication.md b/docs/authentication.md
index 252e1d79..578710dc 100644
--- a/docs/authentication.md
+++ b/docs/authentication.md
@@ -10,6 +10,8 @@
- [Adding HTTP Auth to Configuration](#adding-http-auth-to-configuration)
- [Security Considerations](#security)
- [HTTP Auth](#http-auth)
+ - [Using Config-File Users](#using-config-file-users-recommended)
+ - [Using Static Credentials](#using-static-credentials)
- [Keycloak Auth](#keycloak)
- [Deploying Keycloak](#1-deploy-keycloak)
- [Setting up Keycloak](#2-setup-keycloak-users)
@@ -28,16 +30,11 @@
> [!IMPORTANT]
> Dashy's built-in auth is not intended 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.
+> If Dashy is only accessible within your home network and you just want a login page, then the built-in auth may be sufficient. To also protect server-side endpoints and config files, set `ENABLE_HTTP_AUTH=true` (see [Adding HTTP Auth to Configuration](#adding-http-auth-to-configuration)).
## Built-In Auth
-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.
-
+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. To also enable HTTP Authorization, set the `ENABLE_HTTP_AUTH` env var to `true`.
### Setting Up Authentication
@@ -58,7 +55,7 @@ appConfig:
### Hash Password
-Dashy uses [SHA-256 Hash](https://en.wikipedia.org/wiki/Sha-256), a 64-character string, which you can generate using an online tool, such as [this one](https://passwordsgenerator.net/sha256-hash-generator/) or [CyberChef](https://gchq.github.io/CyberChef/) (which can be self-hosted/ ran locally).
+Dashy uses [SHA-256 Hash](https://en.wikipedia.org/wiki/Sha-256), a 64-character string, which you can generate by running `echo -n "my-super-secure-password" | sha256sum`, or using an online tool, such as [this one](https://passwordsgenerator.net/sha256-hash-generator/) or [CyberChef](https://gchq.github.io/CyberChef/) (which can be self-hosted/ ran locally).
A hash is a one-way cryptographic function, meaning that it is easy to generate a hash for a given password, but very hard to determine the original password for a given hash. This means, that so long as your password is long, strong and unique, it is safe to store its hash in the clear. Having said that, you should never reuse passwords, hashes can be cracked by iterating over known password lists, generating a hash of each.
@@ -140,11 +137,32 @@ 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.
+Without this, the built-in auth is just a client-side login page β€” your config and API endpoints can still be accessed directly. Set `ENABLE_HTTP_AUTH=true` to protect them.
+
+> [!NOTE]
+> HTTP Auth and guest access (`enableGuestAccess`) are incompatible. Guests have no credentials, so they can't fetch the config file when HTTP auth is active.
+
+This uses the same users you've already defined in `appConfig.auth.users` to authenticate all server-side requests (config files, status checks, system info, CORS proxy, etc.) via HTTP Basic Auth.
+
+**How it works:** When a user logs in through the Dashy UI, a session token is stored in a cookie. The frontend automatically includes this token in requests to local API endpoints. On the server side, the token is validated against your configured users. If someone tries to access an endpoint directly (e.g. with curl), the server will respond with a `401` and a Basic Auth challenge β€” they'll need to provide a valid username and password.
+
+**Setup:**
+
+1. Make sure you have users configured in your `conf.yml` (see [Setting Up Authentication](#setting-up-authentication) above)
+2. Set the `ENABLE_HTTP_AUTH=true` environment variable (e.g. in your `docker-compose.yml` or `.env` file)
+3. Restart the container - the auth mode is determined at startup, so env var changes need a restart
+
+Adding or removing users in `conf.yml` takes effect immediately without a restart, since the user list is read from disk on each request.
+
+For full protection, you'll want both the client-side login page (via `appConfig.auth.users`) and server-side auth (via `ENABLE_HTTP_AUTH=true`).
### 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.
+With basic auth (and without HTTP auth), the login logic runs on the client-side. A technical user could inspect the code and view parts of your configuration, including password hashes. If the SHA-256 hash is of a common password, it may be possible to determine it using a lookup table, and then use that to generate a valid auth token. Therefore, you should always use a long, strong and unique password.
+
+If your instance is exposed to the internet, the built-in auth alone is not sufficient - use a reverse proxy with its own authentication layer (see [Alternative Authentication Methods](#alternative-authentication-methods)), or access Dashy over a VPN. See the [Network Exposure](/docs/management.md#network-exposure) section in the management docs for more on this.
+
+The built-in login page prevents casual unauthorized access on a private network. It's not a security perimeter.
**[⬆️ Back to Top](#authentication)**
@@ -152,9 +170,24 @@ 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.
+If you'd like to protect server-side endpoints with HTTP Basic Auth, there are two approaches. They protect the same endpoints but use different credential sources, so pick one - don't combine them.
+
+### Using config-file users (recommended)
+
+This is the approach described in [Adding HTTP Auth to Configuration](#adding-http-auth-to-configuration) above. Set `ENABLE_HTTP_AUTH=true` and it uses the same `appConfig.auth.users` from your `conf.yml`. The frontend handles authentication automatically using the session token from the login page, so no extra setup is needed.
+
+This is the recommended approach because it keeps credentials in one place and works together with the client-side login page. But the drawback is that your credentials will be stored in your config file.
+
+### Using static credentials
+
+If you don't have users in your `conf.yml` (e.g. you handle user management externally, or just want a single shared password for server-side access), you can set the `BASIC_AUTH_USERNAME` and `BASIC_AUTH_PASSWORD` environmental variables instead.
+
+With this approach, there is no Dashy login page. When the browser first requests the config file, the server responds with a `401` and the browser shows its native HTTP auth prompt. Once the user enters the correct credentials, the browser caches them for the session and all subsequent requests work.
+
+To skip the browser prompt and have the frontend authenticate automatically, also set `VUE_APP_BASIC_AUTH_USERNAME` and `VUE_APP_BASIC_AUTH_PASSWORD` to the same values. These are baked in at build time, so a rebuild is required, and you should only do this on a trusted network.
-Then, if you'd like your frontend to automatically log you in, without prompting you for credentials (insecure, so only use on a trusted environment), 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 just want to use auth for user management and to prevent direct 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.
+> [!WARNING]
+> Do not combine `BASIC_AUTH_USERNAME`/`BASIC_AUTH_PASSWORD` with conf.yml users. If both are present, the server will log a warning at startup. With `ENABLE_HTTP_AUTH` set, config-file users take priority and the static credentials are ignored. Without it, the static credentials protect the server but the Dashy login page will use conf.yml credentials, and the frontend will send the wrong credentials to server endpoints. Pick one approach or the other.
**[⬆️ Back to Top](#authentication)**
diff --git a/docs/management.md b/docs/management.md
index a626ccb0..3f679d1b 100644
--- a/docs/management.md
+++ b/docs/management.md
@@ -14,6 +14,7 @@ _The following article is a primer on managing self-hosted apps. It covers every
- [Scheduling](#scheduling)
- [SSL Certificates](#ssl-certificates)
- [Authentication](#authentication)
+- [Network Exposure](#network-exposure)
- [Managing with Compose](#managing-containers-with-docker-compose)
- [Environmental Variables](#passing-in-environmental-variables)
- [Setting Headers](#setting-headers)
@@ -163,7 +164,6 @@ Note that this will not include any data in docker volumes, and the process here
To get started, create a docker-compose similar to the example below, and then start the container. For more info, check out their [documentation](https://github.com/offen/docker-volume-backup), which is very clear.
```yaml
-version: '3'
services:
backup:
image: offen/docker-volume-backup:latest
@@ -199,6 +199,8 @@ docker run --rm -v some_volume:/volume -v /tmp:/backup alpine sh -c "rm -rf /vol
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.
+When you save config through the UI, Dashy automatically creates a timestamped backup in `user-data/config-backups/` (configurable via the `BACKUP_DIR` env var). If you break your config, check that directory for a recent copy.
+
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)
@@ -262,6 +264,20 @@ Dashy natively supports secure authentication using KeyCloak. There is also a Si
---
+## Network Exposure
+
+Dashy is designed to run on your local network, behind your firewall. If you only access it from within your home or over a VPN, the defaults are fine.
+
+If you do need to expose Dashy to the internet, you should put it behind a reverse proxy with its own authentication layer (e.g. Authelia, Authentik, Cloudflare Access, or your proxy's built-in auth). Don't rely solely on Dashy's built-in auth for internet-facing instances - it's a convenience feature for private networks, not a hardened perimeter control. See the [Authentication Docs](/docs/authentication.md) for setup options.
+
+When Dashy runs in server mode (the default Docker setup), it exposes several API endpoints for things like status checks, config saving, system info, and a CORS proxy used by widgets. When authentication is enabled (via `ENABLE_HTTP_AUTH=true` or `BASIC_AUTH_USERNAME`/`BASIC_AUTH_PASSWORD` env vars), all of these endpoints require valid credentials. Without auth configured, they are open. That's fine for private networks, but not appropriate for public access.
+
+The CORS proxy (`/cors-proxy`) is worth calling out specifically: it forwards requests from the Dashy server to external URLs, so widgets can reach APIs that don't set CORS headers. On a private network this is harmless, but on an internet-exposed instance without auth, it could be abused as an open proxy. Always enable authentication if your instance is reachable from untrusted networks.
+
+**[⬆️ Back to Top](#management)**
+
+---
+
## Managing Containers with Docker Compose
When you have a lot of containers, it quickly becomes hard to manage with `docker run` commands. The solution to this is [docker compose](https://docs.docker.com/compose/), a handy tool for defining all a containers run settings in a single YAML file, and then spinning up that container with a single short command - `docker compose up`. A good example of which can be seen in [@abhilesh's docker compose collection](https://github.com/abhilesh/self-hosted_docker_setups).
@@ -272,7 +288,6 @@ An example Docker compose, using the default base image from DockerHub, might lo
```yaml
---
-version: "3.8"
services:
dashy:
container_name: Dashy
@@ -531,8 +546,8 @@ It's worth noting that Ngrok isn't the only option here, other options include:
## Custom Domain
-- [Using DNS](#using-nginx)
-- [Using NGINX](#using-dns)
+- [Using DNS](#using-dns)
+- [Using NGINX](#using-nginx)
### Using DNS
@@ -558,7 +573,7 @@ server {
# Setup SSL
ssl_certificate /var/www/mydomain/sslcert.pem;
ssl_certificate_key /var/www/mydomain/sslkey.pem;
- ssl_protocols TLSv1 TLSv1.1 TLSv1.2;
+ ssl_protocols TLSv1.2 TLSv1.3;
ssl_ciphers 'EECDH+AESGCM:EDH+AESGCM:AES256+EECDH:AES256+EDH';
ssl_session_timeout 5m;
ssl_prefer_server_ciphers on;
@@ -620,23 +635,21 @@ For example, to run Dashy with max of 1GB ram, and max of 50% of 1 CP core:
### Don't Run as Root
-Running a container with admin privileges gives it more power than it needs, and can be abused. Dashy does not need any root privileges, and Docker by default doesn't run containers as root, so providing you don't specifically type sudo, you should be all good here.
+Running Docker commands with `sudo` gives the container more host-level access than it needs. You should run Docker as a non-root host user instead.
-Note that if you're facing permission issues on Debian-based systems, you may need to add your user to the Docker group. First create the group: `sudo groupadd docker`, then add your (non-root) user: `sudo usermod βˆ’aG docker [my-username]`, finally `newgrp docker` to refresh.
+If you're facing permission issues on Debian-based systems when running Docker commands without `sudo`, you may need to add your user to the Docker group. First create the group: `sudo groupadd docker`, then add your (non-root) user: `sudo usermod βˆ’aG docker [my-username]`, finally `newgrp docker` to refresh.
### Specify a User
-One of the best ways to prevent privilege escalation attacks, is to configure the container to use an unprivileged user. This also means that any files created by the container and mounted, will be owned by the specified user (and not root), which makes things much easier.
+For containers in general, running as an unprivileged user is one of the best ways to prevent privilege escalation attacks. You can specify a user with the [`--user` param](https://docs.docker.com/engine/reference/run/#user), using the user ID (`UID`) from `id -u` and group ID (`GID`) from `id -g`.
-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`.
+**Note for Dashy:** If you use features that write to disk (saving config through the UI, triggering a rebuild), the process needs write access to `/app/user-data/` and `/app/dist/`. Since the default image creates these directories as root, running with `--user` will cause those features to fail with permission errors unless you also fix ownership of the mounted volumes. If you only use Dashy in read-only mode, running as a non-root user works fine:
-With Docker run, you specify it like:
`docker run --user 1000:1000 -p 8080:8080 lissy93/dashy`
-Of if you're using Docker-compose, you could use an environmental variable
+Or with Docker Compose, using an environmental variable:
```yaml
-version: "3.8"
services:
dashy:
image: lissy93/dashy
@@ -657,7 +670,6 @@ Note that dropping privileges and capabilities on runtime is not fool-proof, and
Here's an example using docker-compose, removing privileges that are not required for Dashy to run:
```yaml
-version: "3.8"
services:
dashy:
image: lissy93/dashy