🔀 Merge pull request #1542 from Lissy93/FEAT/3.0.1-improvements

[FEAT] Clearer error messaging and documented user-data dir (3.0.1)

.env

@@ -27,6 +27,17 @@
 # The path to the user data directory
 # USER_DATA_DIR=user-data
 
+# Enable HTTP basic auth to protect your *.yml config files
+# ENABLE_HTTP_AUTH=true
+
+# Enable basic HTTP auth to protect your *.yml config files
+# BASIC_AUTH_USERNAME
+# BASIC_AUTH_PASSWORD
+
+# If you'd like frontend to automatically authenticate when basic auth enabled, set credentials here too
+# VUE_APP_BASIC_AUTH_USERNAME
+# VUE_APP_BASIC_AUTH_PASSWORD
+
 # Override where the path to the configuration file is, can be a remote URL
 # VUE_APP_CONFIG_PATH=/conf.yml
 
@@ -52,7 +63,7 @@
 # VUE_APP_VERSION=2.0.0
 
 # Directory for conf.yml backups
-# BACKUP_DIR=./user-data/
+# BACKUP_DIR=./user-data/config-backups
 
 # Setup any other user defined vars by prepending VUE_APP_ to the var name
 # VUE_APP_pihole_ip=http://your.pihole.ip

Dockerfile

@@ -42,7 +42,7 @@ RUN apk add --no-cache tzdata
 COPY --from=BUILD_IMAGE /app ./
 
 # Finally, run start command to serve up the built application
-CMD [ "yarn", "build-and-start" ]
+CMD [ "yarn", "start" ]
 
 # Expose the port
 EXPOSE ${PORT}

README.md

@@ -8,6 +8,14 @@
   <b><a href="./docs/showcase.md">User Showcase</a></b> | <b><a href="https://demo.dashy.to">Live Demo</a></b> | <b><a href="./docs/quick-start.md">Getting Started</a></b> | <b><a href="https://dashy.to/docs">Documentation</a></b> | <b><a href="https://github.com/Lissy93/dashy">GitHub</a></b>
 </p>
 
+<p align="center">
+<br>
+<sup>Dashy is kindly sponsored by <a href="https://umbrel.com?ref=dashy">Umbrel</a> - the personal home cloud and OS for self-hosting</sup><br>
+<a href="https://umbrel.com?ref=dashy">
+<img width="400" src="https://github.com/Lissy93/dashy/blob/WEBSITE/docs-site-source/static/umbrel-banner.jpg?raw=true" />
+</a>
+</p>
+
 > [!NOTE]
 > Version [3.0.0](https://github.com/Lissy93/dashy/releases/tag/3.0.0) has been released, and requires some changes to your setup, see [#1529](https://github.com/Lissy93/dashy/discussions/1529) for details.
 

docker-compose.yml

@@ -20,7 +20,7 @@ services:
       # - /path/to/my-config.yml:/app/user-data/conf.yml
       # - /path/to/item-icons:/app/user-data/item-icons/
 
-    # Set port that web service will be served on. Keep container port as 80
+    # Set port that web service will be served on. Keep container port as 8080
     ports:
       - 4000:8080
 

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](#authentication)**
+
+---
+
 ## 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.

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.md#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.md#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`
 
 ---
 

package.json

@@ -1,6 +1,6 @@
 {
   "name": "dashy",
-  "version": "3.0.0",
+  "version": "3.0.1",
   "license": "MIT",
   "main": "server",
   "author": "Alicia Sykes <[email protected]> (https://aliciasykes.com)",
@@ -26,6 +26,7 @@
     "connect-history-api-fallback": "^1.6.0",
     "crypto-js": "^4.2.0",
     "express": "^4.17.2",
+    "express-basic-auth": "^1.2.1",
     "frappe-charts": "^1.6.2",
     "js-yaml": "^4.1.0",
     "keycloak-js": "^20.0.3",

public/initialization.html

@@ -50,6 +50,14 @@ <h2 id="status-text">Initializing</h2>
 
   <p class="time-note" id="note">This may take a minute or two</p>
 
+  <div class="why-am-i-seeing-this">
+    <h3>Why are you seeing this screen?</h3>
+    <p>
+      The app's built files aren't yet present in the /dist directory,
+      so this page is displayed while we compile the source.
+    </p>
+  </div>
+
   <style lang="css">
     /* Page Layout Styles */
     body,
@@ -60,7 +68,7 @@ <h2 id="status-text">Initializing</h2>
     }
 
     body {
-      background: #141b33;
+      background: #0d1220;
       display: flex;
       flex-direction: column;
       justify-content: center;
@@ -194,15 +202,34 @@ <h2 id="status-text">Initializing</h2>
     }
 
     .hide { display: none; }
+
+    .why-am-i-seeing-this {
+      color: #808080a6;
+      font-family: Tahoma, 'Trebuchet MS', sans-serif;
+      max-width: 25rem;
+      border: 2px solid #808080a6;
+      border-radius: 6px;
+      padding: 0.5rem;
+      position: absolute;
+      bottom: 1rem;
+      background: #8080800d;
+      font-size: 0.9rem;
+    }
+    .why-am-i-seeing-this h3 {
+      margin: 0 0 0.5rem 0;
+    }
+    .why-am-i-seeing-this p {
+      margin: 0;
+    }
   </style>
 
   <script>
-    const refreshRate = 8000;
-    // Refresh at interval
+    // Refresh the page every 10 seconds
+    const refreshRate = 10000;
     setTimeout(() => { location.reload(); }, refreshRate);
 
-     // Get current stage
-     let initStage = parseInt(sessionStorage.getItem('initStage') || 0);
+    // Get current stage
+    let initStage = parseInt(sessionStorage.getItem('initStage') || 0);
 
     // Check if stage in session storage is old, and if so, reset it
     const now = Math.round(Date.now()/1000);
@@ -262,4 +289,4 @@ <h2 id="status-text">Initializing</h2>
   </script>
 </body>
 
-</html>
+</html>