diff --git a/docs/alternate-views.md b/docs/alternate-views.md
index 268ddfb2..57f756c9 100644
--- a/docs/alternate-views.md
+++ b/docs/alternate-views.md
@@ -3,6 +3,7 @@
## Views
Dashy has three different views:
+
- Default View - This is the main homepage with sections in a grid layout
- Workspace View - Items displayed on the side, and are launched within Dashy
- Minimal View - A clean + simple tabbed view
@@ -10,6 +11,7 @@ Dashy has three different views:
You can switch between views using the dropdown in the top-right corner. Set your chosen Starting View with `appConfig.startingView`. Click the page title at any time to go back to your selected starting view.
### Default
+
This is the main page that you will land on when you first launch the application. Here all of your sections (with items + widgets) are visible in a grid layout.
@@ -18,6 +20,7 @@ This is the main page that you will land on when you first launch the applicatio
### Workspace
+
The workspace view displays your links in a sidebar on the left-hand side, and apps are launched inside an iframe without having to leave Dashy. This enables you to use all of your self-hosted apps from one place, and makes multi-tasking easy.
You can specify a default app to be opened when you land on the workspace, by setting `appConfig.workspaceLandingUrl: https://app-to-open/`. If this app exists within your sections.items, then the corresponding section will also be expanded.
@@ -30,6 +33,7 @@ You can also opt to keep previously opened websites/ apps open in the background
### Minimal View
+
The minimal view aims to be super fast and simple, and can be used as a browser startpage. Items are grouped into a tab view, and the last opened tab will be remembered. Similar to the main view, you can search and launch items just by typing, and right-clicking will show more options (like open in modal, workspace or new tab).
diff --git a/docs/authentication.md b/docs/authentication.md
index cdcc782d..2ce80cd8 100644
--- a/docs/authentication.md
+++ b/docs/authentication.md
@@ -1,30 +1,33 @@
# Authentication
- [Basic Auth](#built-in-auth)
- - [Setting Up Authentication](#setting-up-authentication)
- - [Hash Password](#hash-password)
- - [Logging In and Out](#logging-in-and-out)
- - [Guest Access](#enabling-guest-access)
- - [Per-User Access](#granular-access)
- - [Security Considerations](#security)
+ - [Setting Up Authentication](#setting-up-authentication)
+ - [Hash Password](#hash-password)
+ - [Logging In and Out](#logging-in-and-out)
+ - [Guest Access](#enabling-guest-access)
+ - [Per-User Access](#granular-access)
+ - [Security Considerations](#security)
- [Keycloak Auth](#keycloak)
- [Deploying Keycloak](#1-deploy-keycloak)
- [Setting up Keycloak](#2-setup-keycloak-users)
- [Configuring Dashy for Keycloak](#3-enable-keycloak-in-dashy-config-file)
- [Alternative Authentication Methods](#alternative-authentication-methods)
- - [VPN](#vpn)
- - [IP-Based Access](#ip-based-access)
- - [Web Server Authentication](#web-server-authentication)
- - [OAuth Services](#oauth-services)
- - [Auth on Cloud Hosting Services](#static-site-hosting-providers)
+ - [VPN](#vpn)
+ - [IP-Based Access](#ip-based-access)
+ - [Web Server Authentication](#web-server-authentication)
+ - [OAuth Services](#oauth-services)
+ - [Auth on Cloud Hosting Services](#static-site-hosting-providers)
## 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 it the homepage will resolve to your dashboard.
### 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.
For example:
+
```yaml
appConfig:
auth:
@@ -37,18 +40,23 @@ 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).
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 it's 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.
### Logging In and Out
+
Once authentication is enabled, so long as there is no valid token in cookie storage, the application will redirect the user to the login page. When the user enters credentials in the login page, they will be checked, and if valid, then a token will be generated, and they can be redirected to the home page. If credentials are invalid, then an error message will be shown, and they will remain on the login page. Once in the application, to log out the user can click the logout button (in the top-right), which will clear cookie storage, causing them to be redirected back to the login page.
### Enabling Guest Access
+
With authentication setup, by default no access is allowed to your dashboard without first logging in with valid credentials. Guest mode can be enabled to allow for read-only access to a secured dashboard by any user, without the need to log in. A guest user cannot write any changes to the config file, but can apply modifications locally (stored in their browser). You can enable guest access, by setting `appConfig.auth.enableGuestAccess: true`.
### Granular Access
+
You can use the following properties to make certain sections or items only visible to some users, or hide sections and items from guests.
+
- `hideForUsers` - Section or Item will be visible to all users, except for those specified in this list
- `showForUsers` - Section or Item will be hidden from all users, except for those specified in this list
- `hideForGuests` - Section or Item will be visible for logged in users, but not for guests
@@ -77,6 +85,7 @@ For Example:
```
### Permissions
+
Any user who is not an admin (with `type: admin`) will not be able to write changes to disk.
You can also prevent any user from writing changes to disk, using `preventWriteToDisk`. Or prevent any changes from being saved locally in browser storage, using `preventLocalSave`. Both properties can be found under [`appConfig`](./docs/configuring.md#appconfig-optional).
@@ -84,6 +93,7 @@ You can also prevent any user from writing changes to disk, using `preventWriteT
To disable all UI config features, including View Config, set `disableConfiguration`.
### 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.
**[⬆️ Back to Top](#authentication)**
@@ -119,21 +129,25 @@ You should now be able to access the Keycloak web interface, using the port spec
### 2. Setup Keycloak Users
Before we can use Keycloak, we must first set it up with some users. Keycloak uses Realms (similar to tenants) to create isolated groups of users. You must create a Realm before you will be able to add your first user.
+
1. Head over to the admin console
2. In the top-left corner there is a dropdown called 'Master', hover over it and then click 'Add Realm'
3. Give your realm a name, and hit 'Create'
You can now create your first user.
+
1. In the left-hand menu, click 'Users', then 'Add User'
2. Fill in the form, including username and hit 'Save'
3. Under the 'Credentials' tab, give the new user an initial password. They will be prompted to change this after first login
The last thing we need to do in the Keycloak admin console is to create a new client
+
1. Within your new realm, navigate to 'Clients' on the left-hand side, then click 'Create' in the top-right
2. Choose a 'Client ID', set 'Client Protocol' to 'openid-connect', and for 'Valid Redirect URIs' put a URL pattern to where you're hosting Dashy (if you're just testing locally, then * is fine), and do the same for the 'Web Origins' field
3. Make note of your client-id, and click 'Save'
### 3. Enable Keycloak in Dashy Config File
+
Now that your Keycloak instance is up and running, all that's left to do is to configure Dashy to use it. Under `appConfig`, set `auth.enableKeycloak: true`, then fill in the details in `auth.keycloak`, including: `serverUrl` - the URL where your Keycloak instance is hosted, `realm` - the name you gave your Realm, and `clientId` - the Client ID you chose.
For example:
@@ -151,10 +165,12 @@ appConfig:
Note that if you are using Keycloak V 17 or older, you will also need to set `legacySupport: true` (also under `appConfig.auth.keycloak`). This is because the API endpoint was updated in later versions.
### 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 or items 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 section or item `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
@@ -181,6 +197,7 @@ From within the Keycloak console, you can then configure things like time-outs,
## Alternative Authentication Methods
If you are self-hosting Dashy, and require secure authentication to prevent unauthorized access, then you can either use Keycloak, or one of the following options:
+
- [Authentication Server](#authentication-server) - Put Dashy behind a self-hosted auth server
- [VPN](#vpn) - Use a VPN to tunnel into the network where Dashy is running
- [IP-Based Access](#ip-based-access) - Disallow access from all IP addresses, except your own
@@ -189,7 +206,9 @@ If you are self-hosting Dashy, and require secure authentication to prevent unau
- [Password Protection (for cloud providers)](#static-site-hosting-providers) - Enable password-protection on your site
### Authentication Server
-##### Authelia
+
+#### Authelia
+
[Authelia](https://www.authelia.com/) is an open-source full-featured authentication server, which can be self-hosted and either on bare metal, in a Docker container or in a Kubernetes cluster. It allows for fine-grained access control rules based on IP, path, users etc, and supports 2FA, simple password access or bypass policies for your domains.
- `git clone https://github.com/authelia/authelia.git`
@@ -201,22 +220,28 @@ If you are self-hosting Dashy, and require secure authentication to prevent unau
For more information, see the [Authelia docs](https://www.authelia.com/docs/)
### VPN
+
A catch-all solution to accessing services running from your home network remotely is to use a VPN. It means you do not need to worry about implementing complex authentication rules, or trusting the login implementation of individual applications. However it can be inconvenient to use on a day-to-day basis, and some public and corporate WiFi block VPN connections. Two popular VPN protocols are [OpenVPN](https://openvpn.net/) and [WireGuard](https://www.wireguard.com/)
### IP-Based Access
+
If you have a static IP or use a VPN to access your running services, then you can use conditional access to block access to Dashy from everyone except users of your pre-defined IP address. This feature is offered by most cloud providers, and supported by most web servers.
-##### Apache
+#### Apache
+
In Apache, this is configured in your `.htaccess` file in Dashy's root folder, and should look something like:
-```
+
+```text
Order Deny,Allow
Deny from all
Allow from [your-ip]
```
-##### NGINX
+#### NGINX
+
In NGINX you can specify [control access](https://docs.nginx.com/nginx/admin-guide/security-controls/controlling-access-proxied-http/) rules for a given site in your `nginx.conf` or hosts file. For example:
-```
+
+```text
server {
listen 80;
server_name www.dashy.example.com;
@@ -229,9 +254,11 @@ server {
}
```
-##### Caddy
+#### Caddy
+
In Caddy, [Request Matchers](https://caddyserver.com/docs/caddyfile/matchers) can be used to filter requests
-```
+
+```text
dashy.site {
@public_networks not remote_ip [your-ip]
respond @public_networks "Access denied" 403
@@ -239,11 +266,14 @@ dashy.site {
```
### Web Server Authentication
+
Most web servers make password protecting certain apps very easy. Note that you should also set up HTTPS and have a valid certificate in order for this to be secure.
-##### Apache
+#### Apache
+
First crate a `.htaccess` file in Dashy's route directory. Specify the auth type and path to where you want to store the password file (usually the same folder). For example:
-```
+
+```text
AuthType Basic
AuthName "Please Sign into Dashy"
AuthUserFile /path/dashy/.htpasswd
@@ -251,21 +281,27 @@ require valid-user
```
Then create a `.htpasswd` file in the same directory. List users and their hashed passwords here, with one user on each line, and a colon between username and password (e.g. `[username]:[hashed-password]`). You will need to generate an MD5 hash of your desired password, this can be done with an [online tool](https://www.web2generators.com/apache-tools/htpasswd-generator). Your file will look something like:
-```
+
+```text
alicia:$apr1$jv0spemw$RzOX5/GgY69JMkgV6u16l0
```
-##### NGINX
+#### NGINX
+
NGINX has an [authentication module](https://nginx.org/en/docs/http/ngx_http_auth_basic_module.html) which can be used to add passwords to given sites, and is fairly simple to set up. Similar to above, you will need to create a `.htpasswd` file. Then just enable auth and specify the path to that file, for example:
-```
+
+```text
location / {
auth_basic "closed site";
auth_basic_user_file conf/htpasswd;
}
```
-##### Caddy
+
+#### Caddy
+
Caddy has a [basic-auth](https://caddyserver.com/docs/caddyfile/directives/basicauth) directive, where you specify a username and hash. The password hash needs to be base-64 encoded, the [`caddy hash-password`](https://caddyserver.com/docs/command-line#caddy-hash-password) command can help with this. For example:
-```
+
+```text
basicauth /secret/* {
alicia JDJhJDEwJEVCNmdaNEg2Ti5iejRMYkF3MFZhZ3VtV3E1SzBWZEZ5Q3VWc0tzOEJwZE9TaFlZdEVkZDhX
}
@@ -273,11 +309,13 @@ basicauth /secret/* {
For more info about implementing a single sign on for all your apps with Caddy, see [this tutorial](https://joshstrange.com/securing-your-self-hosted-apps-with-single-signon/)
-##### Lighttpd
+#### Lighttpd
+
You can use the [mod_auth](https://doc.lighttpd.net/lighttpd2/mod_auth.html) module to secure your site with Lighttpd. Like with Apache, you need to first create a password file listing your usersnames and hashed passwords, but in Lighttpd, it's usually called `.lighttpdpassword`.
Then in your `lighttpd.conf` file (usually in the `/etc/lighttpd/` directory), load in the mod_auth module, and configure it's directives. For example:
-```
+
+```text
server.modules += ( "mod_auth" )
auth.debug = 2
auth.backend = "plain"
@@ -296,12 +334,15 @@ $HTTP["host"] == "dashy.my-domain.net" {
)
}
```
+
Restart your web server for changes to take effect.
### OAuth Services
+
There are also authentication services, such as [Ory.sh](https://www.ory.sh/), [Okta](https://developer.okta.com/), [Auth0](https://auth0.com/), [Firebase](https://firebase.google.com/docs/auth/). Implementing one of these solutions would involve some changes to the [`Auth.js`](https://github.com/Lissy93/dashy/blob/master/src/utils/Auth.js) file, but should be fairly straight forward.
### Static Site Hosting Providers
+
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)**
diff --git a/docs/backup-restore.md b/docs/backup-restore.md
index 06d4b565..856b6564 100644
--- a/docs/backup-restore.md
+++ b/docs/backup-restore.md
@@ -1,4 +1,4 @@
-### Cloud Backup and Restore
+# Cloud Backup and Restore
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.
@@ -8,18 +8,19 @@ This is useful not only for backing up your configuration off-site, but it also
-### How it Works
+## How it Works
All data is encrypted before being sent to the backend. In Dashy, this is done in [`CloudBackup.js`](https://github.com/Lissy93/dashy/blob/master/src/utils/CloudBackup.js), using [crypto.js](https://github.com/brix/crypto-js)'s AES method, using the users chosen password as the key. The data is then sent to a [Cloudflare worker](https://developers.cloudflare.com/workers/learning/how-workers-works) (a platform for running serverless functions), and stored in a [KV](https://developers.cloudflare.com/workers/learning/how-kv-works) data store.
+## Creating a Backup
-### Creating a Backup
Once you've got Dashy configured to your preference, open the Backup & Restore menu (click the Cloud icon in the top-right corner). Here you will be prompted to choose a password, which will be used to encrypt your data. If you forget this password, there will be no way to recover your config. After clicking 'Backup' your data will be encrypted, compressed and sent to the hosted cloud service. A backup ID will be returned (in the format of xxxx-xxxx-xxxx-xxxx), this is what you use, along with your password to restore the backup on another system, so take note of it. To update a backup, return to this menu, enter your password, and click 'Update Backup'.
-### Restoring a Backup
+## Restoring a Backup
+
To restore a backup, navigate to the Backup & Restore menu, and under restore, enter your backup ID, and the password you chose. Your config file will be downloaded, decrypted and applied to local storage.
-### Privacy & Security
+## Privacy & Security
Data is only ever sent to the cloud when the user actively triggers a backup. All transmitted data is first encrypted using [AES](https://en.wikipedia.org/wiki/Advanced_Encryption_Standard). Your selected password never leaves your device, and is hashed before being compared. It is only possible to restore a configuration if you have both the backup ID and decryption password.
@@ -27,24 +28,23 @@ Because the data is encrypted on the client-side (before being sent to the cloud
Having said that, although the code uses robust security libraries and is open source- it was never intended to be a security product, and has not been audited, and therefore cannot be considered totally secure - please keep that in mind.
-
-### Fair Use Policy
+## Fair Use Policy
Maximum of 24mb of storage per user. Please do not repeatedly hit the endpoint, as if the quota is exceeded the service may become less available to other users. Abuse may result in your IP being temporarily banned by Cloudflare.
---
-### Self-Hosting the Backup Server
+## Self-Hosting the Backup Server
+### Quick Start
-#### Quick Start
- Install Wrangler CLI Tool: `npm i -g @cloudflare/wrangler`
- Log into Cloudflare account: `wrangler login`
-- Create a new project: ` wrangler generate my-project`
+- Create a new project: `wrangler generate my-project`
- Install dependencies: `cd my-project` && `npm i`
+### Populate `wrangler.toml`
-#### Populate `wrangler.toml`
- Add your `account_id` (found on the right sidebar of the Workers or Overview Dashboard)
- Add your `zone_id` (found in the Overview tab of your desired domain on Cloudflare)
- Add your `route`, which should be a domain or host, supporting a wildcard
@@ -63,10 +63,11 @@ kv_namespaces = [
]
```
-#### Complete `index.js`
+### Complete `index.js`
+
- Write code to handle your requests, and interact with any other data sources in this file
- Generally, this is done within an event listener for 'fetch', and returns a promise
- - For Example:
+ - For Example:
```javascript
addEventListener('fetch', event => {
@@ -82,28 +83,28 @@ async function handleRequest(request) {
- For the code used for Dashy's cloud service, see [here](https://gist.github.com/Lissy93/d19b43d50f30e02fa25f349cf5cb5ed8#file-index-js)
+### Commands
-#### Commands
- `wrangler dev` - To start the wrangler development server
- `wrangler publish` - To publish to your cloudflare account (first run `wrangler login`)
-### API
+## API
There are four endpoints, and to keep things simple, they all use the same base URL/ route.
- **`GET`** - Get config for a given user
- - `backupId` - The ID of the desired encrypted object
- - `subHash` - The latter half of the password hash, to verify ownership
+ - `backupId` - The ID of the desired encrypted object
+ - `subHash` - The latter half of the password hash, to verify ownership
- **`POST`** - Save a new config object, and returns `backupId`
- - `userData` - The encrypted, compressed and stringified user config
- - `subHash` - The latter half of the password hash, to verify ownership
+ - `userData` - The encrypted, compressed and stringified user config
+ - `subHash` - The latter half of the password hash, to verify ownership
- **`PUT`** - Update an existing config object
- - `backupId` - The ID of the object to update
- - `subHash` - Part of the hash, to verify ownership of said object
- - `userData` - The new data to store
+ - `backupId` - The ID of the object to update
+ - `subHash` - Part of the hash, to verify ownership of said object
+ - `userData` - The new data to store
- **`DELETE`** - Delete a specified config object
- - `backupId` - The ID of the object to be deleted
- - `subHash` - Part of the password hash, to verify ownership of the object
+ - `backupId` - The ID of the object to be deleted
+ - `subHash` - Part of the password hash, to verify ownership of the object
For more info, see the [API Docs](https://documenter.getpostman.com/view/2142819/TzXumzce).
diff --git a/docs/configuring.md b/docs/configuring.md
index e4c19ad5..148d85e5 100644
--- a/docs/configuring.md
+++ b/docs/configuring.md
@@ -2,7 +2,8 @@
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.
-#### There are three ways to edit the config
+## There are three ways to edit the config
+
- **Directly in the YAML file** _(5/5 reliability, 3/5 usability)_
- Write changes directly to the conf.yml file, optionally using one of the templates provided. This can be done in your favorite editor and uploading to your server, or directly editing the file via SSH, but the easiest method would be to use [Code Server](https://github.com/coder/code-server)
- **UI JSON Editor** _(4/5 reliability, 4/5 usability)_
@@ -12,7 +13,8 @@ All app configuration is specified in [`/public/conf.yml`](https://github.com/Li
- **REST API** _(Coming soon)_
- Programmatically edit config either through the command line, using a script or a third-party application
-#### Tips
+## Tips
+
- You may find it helpful to look at some sample config files to get you started, a collection of which can be found [here](https://gist.github.com/Lissy93/000f712a5ce98f212817d20bc16bab10)
- You can check that your config file fits the schema, by running `yarn validate-config`
- After modifying your config, the app needs to be recompiled, by running `yarn build` - this happens automatically if you're using Docker
@@ -23,7 +25,7 @@ All app configuration is specified in [`/public/conf.yml`](https://github.com/Li
The following file provides a reference of all supported configuration options.
-#### Contents
+## Contents
- [**`pageInfo`**](#pageinfo) - Header text, footer, title, navigation, etc
- [`navLinks`](#pageinfonavlinks-optional) - Links to display in the navigation bar
@@ -52,7 +54,7 @@ The following file provides a reference of all supported configuration options.
---
-### Top-Level Fields
+## Top-Level Fields
**Field** | **Type** | **Required**| **Description**
--- | --- | --- | ---
@@ -63,7 +65,7 @@ The following file provides a reference of all supported configuration options.
**[⬆️ Back to Top](#configuring)**
-### `PageInfo`
+## `PageInfo`
**Field** | **Type** | **Required**| **Description**
--- | --- | --- | ---
@@ -75,7 +77,7 @@ The following file provides a reference of all supported configuration options.
**[⬆️ Back to Top](#configuring)**
-### `pageInfo.navLinks` _(optional)_
+## `pageInfo.navLinks` _(optional)_
**Field** | **Type** | **Required**| **Description**
--- | --- | --- | ---
@@ -85,7 +87,7 @@ The following file provides a reference of all supported configuration options.
**[⬆️ Back to Top](#configuring)**
-### `pages[]` _(optional)_
+## `pages[]` _(optional)_
**Field** | **Type** | **Required**| **Description**
--- | --- | --- | ---
@@ -94,7 +96,7 @@ The following file provides a reference of all supported configuration options.
**[⬆️ Back to Top](#configuring)**
-### `appConfig` _(optional)_
+## `appConfig` _(optional)_
**Field** | **Type** | **Required**| **Description**
--- | --- | --- | ---
@@ -136,7 +138,8 @@ The following file provides a reference of all supported configuration options.
**[⬆️ Back to Top](#configuring)**
-### `appConfig.auth` _(optional)_
+## `appConfig.auth` _(optional)_
+
**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).
**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.md#alternative-authentication-methods).
@@ -148,7 +151,7 @@ For more info, see the **[Authentication Docs](/docs/authentication.md)**
**[⬆️ Back to Top](#configuring)**
-### `appConfig.auth.users` _(optional)_
+## `appConfig.auth.users` _(optional)_
**Field** | **Type** | **Required**| **Description**
--- | --- | --- | ---
@@ -158,7 +161,7 @@ For more info, see the **[Authentication Docs](/docs/authentication.md)**
**[⬆️ Back to Top](#configuring)**
-### `appConfig.auth.keycloak` _(optional)_
+## `appConfig.auth.keycloak` _(optional)_
**Field** | **Type** | **Required**| **Description**
--- | --- | --- | ---
@@ -169,7 +172,7 @@ For more info, see the **[Authentication Docs](/docs/authentication.md)**
**[⬆️ Back to Top](#configuring)**
-### `appConfig.webSearch` _(optional)_
+## `appConfig.webSearch` _(optional)_
**Field** | **Type** | **Required**| **Description**
--- | --- | --- | ---
@@ -179,10 +182,9 @@ For more info, see the **[Authentication Docs](/docs/authentication.md)**
**`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)**
-### `appConfig.hideComponents` _(optional)_
+## `appConfig.hideComponents` _(optional)_
**Field** | **Type** | **Required**| **Description**
--- | --- | --- | ---
@@ -194,7 +196,7 @@ For more info, see the **[Authentication Docs](/docs/authentication.md)**
**[⬆️ Back to Top](#configuring)**
-### `section`
+## `section`
**Field** | **Type** | **Required**| **Description**
--- | --- | --- | ---
@@ -206,7 +208,7 @@ For more info, see the **[Authentication Docs](/docs/authentication.md)**
**[⬆️ Back to Top](#configuring)**
-### `section.item`
+## `section.item`
**Field** | **Type** | **Required**| **Description**
--- | --- | --- | ---
@@ -230,8 +232,7 @@ For more info, see the **[Authentication Docs](/docs/authentication.md)**
**[⬆️ Back to Top](#configuring)**
-
-### `item.displayData` _(optional)_
+## `item.displayData` _(optional)_
**Field** | **Type** | **Required**| **Description**
--- | --- | --- | ---
@@ -243,8 +244,7 @@ For more info, see the **[Authentication Docs](/docs/authentication.md)**
**[⬆️ Back to Top](#configuring)**
-
-### `section.widget` _(optional)_
+## `section.widget` _(optional)_
**Field** | **Type** | **Required**| **Description**
--- | --- | --- | ---
@@ -258,8 +258,7 @@ For more info, see the **[Authentication Docs](/docs/authentication.md)**
**[⬆️ Back to Top](#configuring)**
-
-### `section.displayData` _(optional)_
+## `section.displayData` _(optional)_
**Field** | **Type** | **Required**| **Description**
--- | --- | --- | ---
@@ -282,7 +281,7 @@ For more info, see the **[Authentication Docs](/docs/authentication.md)**
**[⬆️ Back to Top](#configuring)**
-### `section.icon` and `section.item.icon`
+## `section.icon` and `section.item.icon`
**Field** | **Type** | **Required**| **Description**
--- | --- | --- | ---
@@ -290,7 +289,7 @@ For more info, see the **[Authentication Docs](/docs/authentication.md)**
**[⬆️ Back to Top](#configuring)**
-### `section.displayData.hideForKeycloakUsers`, `section.displayData.showForKeycloakUsers`, `item.displayData.hideForKeycloakUsers` and `item.displayData.showForKeycloakUsers`
+## `section.displayData.hideForKeycloakUsers`, `section.displayData.showForKeycloakUsers`, `item.displayData.hideForKeycloakUsers` and `item.displayData.showForKeycloakUsers`
**Field** | **Type** | **Required**| **Description**
--- |------------| --- | ---
@@ -320,10 +319,13 @@ Config can be modified directly through the UI, and then written to disk, or app
### About YAML
+
If you're new to YAML, it's pretty straight-forward. The format is exactly the same as that of JSON, but instead of using curly braces, structure is denoted using whitespace. This [quick guide](https://linuxhandbook.com/yaml-basics/) should get you up to speed in a few minutes, for more advanced topics take a look at this [Wikipedia article](https://en.wikipedia.org/wiki/YAML).
### Config Saving Methods
+
When updating the config through the JSON editor in the UI, you have two save options: **Local** or **Write to Disk**.
+
- Changes saved locally will only be applied to the current user through the browser, and will not apply to other instances - you either need to use the cloud sync feature, or manually update the conf.yml file.
- On the other-hand, if you choose to write changes to disk, then your main `conf.yml` file will be updated, and changes will be applied to all users, and visible across all devices. For this functionality to work, you must be running Dashy with using the Docker container, or the Node server. A backup of your current configuration will also be saved in the same directory.
diff --git a/docs/contributing.md b/docs/contributing.md
index aa1cf5c3..532b4a44 100644
--- a/docs/contributing.md
+++ b/docs/contributing.md
@@ -5,11 +5,13 @@ There are several ways that you can help out, and any contributions, however sma
You will be appropriately credited in the readme - huge thank you to [everyone who has helped](/docs/credits.md) so far 💞
## Take a 2-minute survey
+
Help improve Dashy by taking a very short, 6-question survey. This will give me a better understanding of what is important to you, so that I can make Dashy better in the future :)
[](https://survey.typeform.com/to/gl0L68ou)
## Share your dashboard
+
Dashy now has a [Showcase](https://github.com/Lissy93/dashy/blob/master/docs/showcase.md#dashy-showcase-) where you can show off a screenshot of your dashboard, and get inspiration from other users (and I really love seeing how people are using Dashy). To [submit your dashboard](https://github.com/Lissy93/dashy/blob/master/docs/showcase.md#submitting-your-dashboard), either open a PR or raise an issue.
[](https://github.com/Lissy93/dashy/issues/new?assignees=&labels=%F0%9F%92%AF+Showcase&template=showcase-addition.yml&title=%5BSHOWCASE%5D+%3Ctitle%3E)
@@ -36,6 +38,7 @@ Sponsoring will give you several perks - for $1 / £0.75 per month, you'll get a
- **ZEC**: `t1bw1SefijsXRDQVxC9w64XsRK8hBhtQohQ`
+
## Enable Anonymous Bug Reports
@@ -43,6 +46,7 @@ Sponsoring will give you several perks - for $1 / £0.75 per month, you'll get a
Bug reports helps me to discover bugs I was unaware of, and then fix them, in order to make Dashy more reliable long term. This is a simple, yet really helpful step you can take to help improve Dashy. [Sentry](https://github.com/getsentry/sentry) is an open source error tracking and performance monitoring tool, which enables the identification any errors which occur in the production app (only if you enable it).
To enable error reporting:
+
```yaml
appConfig:
enableErrorReporting: true
@@ -51,31 +55,38 @@ appConfig:
All reporting is **disabled** by default, and no data will ever be sent to any external endpoint without your explicit consent. All statistics are anonomized and stored securely. For more about privacy and security, see the [Sentry Security Docs](https://sentry.io/security/).
## Add Translations
+
If you speak another language, then adding translations will help make Dashy available to non-native English speakers. This is a very quick and easy task, as all application text is located in [`locales/en.json`](https://github.com/Lissy93/dashy/blob/master/src/assets/locales/en.json), so adding a new language is as simple as copying this file and translating the values. You don't have to translate it all, as any missing attributes will just fallback to English. For a full tutorial, see the [Multi-Language Support Docs](https://github.com/Lissy93/dashy/blob/master/docs/multi-language-support.md).
## Submit a PR
+
Contributing to the code or docs is super helpful. You can fix a bug, add a new feature or improve an existing one. If you've built your own custom widget, theme or view, consider sharing it in a PR. I've written [several guides](/docs/development-guides.md) to help you get started, and the steps for setting up the development environment are outlined in the [Development Docs](/docs/developing.md). Feel free to ask if you have any questions.
## Improve the Docs
+
Found a typo, or something that isn't as clear as it could be? Maybe I've missed something off altogether, or you hit a roadblock that took you a while to figure out. Submitting a pull request to add to or improve the documentation will help future users get Dashy up and running more easily.
All content is located either in the [`./README.md`](/README.md) or [`/docs/`](/docs) directory, and synced to the Wiki and website using a GH [action](/actions/workflows/wiki-sync.yml).
## Raise a bug
+
If you've found a bug, then please do raise it as an issue. This will help me know if there's something that needs fixing. Try and include as much detail as possible, such as your environment, steps to reproduce, any console output and maybe an example screenshot or recording if necessary.
[](https://github.com/Lissy93/dashy/issues/new?assignees=lissy93&labels=%F0%9F%90%9B+Bug&template=bug.yml&title=%5BBUG%5D+%3Ctitle%3E)
## Join the discussion
+
I've enabled the discussion feature on GitHub, here you can share tips and tricks, useful information, or your dashboard. You can also ask questions, and offer basic support to other users.
[](https://github.com/Lissy93/dashy/discussions)
## Request a feature via BountySource
+
BountySource is a platform for sponsoring the development of certain features on open source projects. If there is a feature you'd like implemented into Dashy, but either isn't high enough priority or is deemed to be more work than it's worth, then you can instead contribute a bounty towards it's development. You won't pay a penny until your proposal is fully built, and you are satisfied with the result. This helps support the developers, and makes Dashy better for everyone.
[](https://www.bountysource.com/teams/dashy)
## Spread the word
+
Dashy is still a relatively young project, and as such not many people know of it. It would be great to see more users, and so it would be awesome if you could consider sharing with your friends or on social platforms.
[](https://mastodon.social/?text=Check%20out%20Dashy%2C%20the%20privacy-friendly%2C%20self-hosted%20startpage%20for%20organizing%20your%20life%3A%20https%3A%2F%2Fgithub.com%2FLissy93%2Fdashy%20-%20By%20%40lissy93%40mastodon.social)
@@ -90,6 +101,7 @@ Dashy is still a relatively young project, and as such not many people know of i
[](mailto:info@example.com?&subject=Check%20out%20Dashy%20-%20The%20self-hosted%20dashboard%20for%20your%20homelab%20%F0%9F%9A%80&cc=&bcc=&body=https://github.com/lissy93/dashy)
## Star, Upvote or Leave a Review
+
Dashy is on the following platforms, and if you could spare a few seconds to give it an upvote or review, this will also help new users discover Dashy
[](https://www.producthunt.com/posts/dashy)
@@ -99,6 +111,7 @@ Dashy is on the following platforms, and if you could spare a few seconds to giv
[](https://hub.docker.com/r/lissy93/dashy)
## Follow for More
+
If you've enjoyed Dashy, you can follow the me to get updates about other projects that I am working on.
[](https://twitter.com/Lissy_Sykes)
diff --git a/docs/credits.md b/docs/credits.md
index 5d7f6bcc..633eb659 100644
--- a/docs/credits.md
+++ b/docs/credits.md
@@ -1,6 +1,6 @@
# Credits
-### Sponsors
+## Sponsors
-### Contributors
+## Contributors
-
-### Helpful Users
+## Helpful Users
-### Bots
+## Bots
@@ -458,7 +457,7 @@
> The above section is auto-generated, using [contribute-list](https://github.com/marketplace/actions/contribute-list) by @akhilmhdh.
-### Newest Stargazers
+## Newest Stargazers
[](https://github.com/Lissy93/dashy/stargazers)
@@ -470,17 +469,20 @@
This app definitely wouldn't have been quite so possible without the making use of the following package and components. Full credit and big kudos to their respective authors, who've done an amazing job in building and maintaining them. For a full breakdown of dependency licenses, please see [Legal](https://github.com/Lissy93/dashy/blob/master/.github/LEGAL.md)
-#### Core
+### Core
+
At it's core, the application uses [**Vue.js**](https://github.com/vuejs/vue), as well as it's services with [**VueX**](https://vuex.vuejs.org/) for state management. Styling is done with [**SCSS**](https://github.com/sass/sass), JavaScript is currently [**Babel**](https://github.com/babel/babel), (but I am in the process of converting to [**TypeScript**](https://github.com/Microsoft/TypeScript)). Linting is done with [**ESLint**](https://github.com/eslint/eslint) and [**Prettier**](https://prettier.io/), both following the [**AirBnB Styleguide**](https://github.com/airbnb/javascript). The config is defined in [**YAML**](https://github.com/yaml/yaml), with a simple [**Node.js**](https://github.com/nodejs/node) server to serve up the static app and the optional API endpoints, and container deployment is done with [**Docker**](https://www.docker.com/).
-#### Utilities
+### Utilities
+
- [`crypto-js`](https://github.com/brix/crypto-js) - Encryption implementations by @evanvosberg and community `MIT`
- [`axios`](https://github.com/axios/axios) - Promise based HTTP client by @mzabriskie and community `MIT`
- [`ajv`](https://github.com/ajv-validator/ajv) - JSON schema Validator by @epoberezkin and community `MIT`
- [`i18n`](https://github.com/kazupon/vue-i18n) - Internationalization plugin by @kazupon and community `MIT`
- [`frappe-charts`](https://github.com/frappe/charts) - Lightweight charting library by @frappe `MIT`
-#### Frontend Components
+### Frontend Components
+
- [`vue-select`](https://github.com/sagalbot/vue-select) - Dropdown component by @sagalbot `MIT`
- [`vue-js-modal`](https://github.com/euvl/vue-js-modal) - Modal component by @euvl `MIT`
- [`v-tooltip`](https://github.com/Akryum/v-tooltip) - Tooltip component by @Akryum `MIT`
@@ -490,13 +492,16 @@ At it's core, the application uses [**Vue.js**](https://github.com/vuejs/vue), a
- [`vue-toasted`](https://github.com/shakee93/vue-toasted) - Toast notification component by @shakee93 `MIT`
- [`vue-swatches`](https://github.com/saintplay/vue-swatches) - Color palete picker by @saintplay `MIT`
-#### Backup & Sync Server
+### Backup & Sync Server
+
Although the app is purely frontend, there is an optional cloud sync feature, for off-site backup and restore. This is built as a serverless function on [Cloudflare workers](https://workers.cloudflare.com/) using [KV](https://developers.cloudflare.com/workers/runtime-apis/kv) and [web crypto](https://developers.cloudflare.com/workers/runtime-apis/web-crypto)
-#### External Services
+### External Services
+
The 1-Click deploy demo uses [Play-with-Docker Labs](https://play-with-docker.com/). Code is hosted on [GitHub](https://github.com), Docker images are hosted on [DockerHub](https://hub.docker.com/), and the demos are hosted on [Netlify](https://www.netlify.com/).
-#### Actions
+### Actions
+
This repo makes heavy use of [GitHub actions](https://github.com/features/actions) to run automated workflows. The following base actions are totally awesome, and have been extremely useful. Full credit to their respective authors
- [`action-autotag`](https://github.com/butlerlogic/action-autotag) by @butlerlogic - Tags new versions when app version changes
@@ -518,5 +523,6 @@ This repo makes heavy use of [GitHub actions](https://github.com/features/action
---
-## You!
+## You
+
Would you like to be listed here? Whatever your skill set, Dashy needs people like you to help support future development. Check out the [Contributing Page](/docs/contributing.md) for ways that you can get involved. Huge thank you to everyone who has already contributed! 💖
diff --git a/docs/deployment.md b/docs/deployment.md
index 02b74906..6a957cdb 100644
--- a/docs/deployment.md
+++ b/docs/deployment.md
@@ -2,9 +2,11 @@
Welcome to Dashy, so glad you're here :) Deployment is super easy, and there are several methods available depending on what type of system you're using. If you're self-hosting, then deploying with Docker (or similar container engine) is the recommended approach.
-#### Quick Start
+## Quick Start
+
If you want to skip the fuss, and [get straight down to it](/docs/quick-start.md), then you can spin up a new instance of Dashy by running:
-```
+
+```bash
docker run -p 8080:80 lissy93/dashy
```
@@ -44,8 +46,7 @@ Once you've got Dashy up and running, you'll want to configure it with your own
Dashy has a built container image hosted on [Docker Hub](https://hub.docker.com/r/lissy93/dashy). You will need [Docker](https://docs.docker.com/get-docker/) installed on your system.
-
-```docker
+```bash
docker run -d \
-p 8080:80 \
-v /root/my-local-conf.yml:/app/public/conf.yml \
@@ -55,6 +56,7 @@ docker run -d \
```
Explanation of the above options:
+
- `-d` Detached mode (not running in the foreground of your terminal)
- `-p` The port that should be exposed, and the port it should be mapped to in your host system `[host-port][container-port]`, leave the container port as is
- `-v` Specify volumes, to pass data from your host system to the container, in the format of `[host-path]:[container-path]`, you can use this to pass your config file, directory of assets (like icons), custom CSS or web assets (like favicon.ico, manifest.json etc)
@@ -108,6 +110,7 @@ services:
retries: 3
start_period: 40s
```
+
You can use a different tag, by for example setting `image: lissy93/dashy:arm64v8`, or pull from GHCR instead by setting `image: ghcr.io/lissy93/dashy`.
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`
@@ -126,7 +129,9 @@ Installing dashy is really simply and fast:
1. Install Docker via Synology ```Package Center```.
2. Go to ```File Station``` and open the ```docker``` folder. Inside the docker folder, create one new folder and name it ```dashy```.
- > Note: Be careful to enter only lowercase, not uppercase letters.
+
+ > Note: Be careful to enter only lowercase, not uppercase letters.
+
3. Go to Control Panel / Task Scheduler / Create / Scheduled Task / User-defined script.
4. Once you click on ```User-defined``` script a new window will open.
5. Follow the instructions below:
@@ -134,7 +139,7 @@ Installing dashy is really simply and fast:
7. Schedule: Select Run on the following date then select "Do not repeat".
8. Task Settings: Check "Send run details by email", add your email then copy paste the code below in the Run command area. After that click OK.
-```
+```bash
docker run -d \
-p 4000:80 \
-v /volume1/docker/dashy/my-local-conf.yml:/app/public/conf.yml \
@@ -142,7 +147,9 @@ docker run -d \
--restart=always \
lissy93/dashy:latest
```
+
dashy should be up within 1-2min after you've started the install task procedure
+
---
## Build from Source
@@ -157,7 +164,7 @@ If you do not want to use Docker, you can run Dashy directly on your host system
---
-### Deploy to cloud service
+## 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.
@@ -165,113 +172,134 @@ Some hosting providers required a bit of extra configuration, which was why I've
**Note** If you use a static hosting provider, then status checks, writing new config changes to disk from the UI, and triggering a rebuild through the UI will not be availible. This is because these features need endpoints provided by Dashy's local Node server. Everything else should work just the same though.
-#### Netlify
+### Netlify
+
[](https://app.netlify.com/start/deploy?repository=https://github.com/lissy93/dashy)
[Netlify](https://www.netlify.com/) offers Git-based serverless cloud hosting for web applications. Their services are free to use for personal use, and they support deployment from both public and private repos, as well as direct file upload. The free plan also allows you to use your own custom domain or sub-domain, and is easy to setup.
To deploy Dashy to Netlify, use the following link
-```
+
+```text
https://app.netlify.com/start/deploy?repository=https://github.com/lissy93/dashy
```
-#### Heroku
+### Heroku
+
[](https://heroku.com/deploy?template=https://github.com/Lissy93/dashy)
[Heroku](https://www.heroku.com/) is a fully managed cloud platform as a service. You define app settings in a Procfile and app.json, which specifying how the app should be build and how the server should be started. Heroku is free to use for unlimited, non-commercial, single dyno apps, and supports custom domains. Heroku's single-dyno service is not as quite performant as some other providers, and the app will have a short wake-up time when not visited for a while
To deploy Dashy to Heroku, use the following link
-```
+
+```text
https://heroku.com/deploy?template=https://github.com/Lissy93/dashy
```
-#### Cloudflare Workers
+### Cloudflare Workers
+
[](https://deploy.workers.cloudflare.com/?url=https://github.com/lissy93/dashy/tree/deploy_cloudflare)
[Cloudflare Workers](https://workers.cloudflare.com/) is a simple yet powerful service for running cloud functions and hosting web content. It requires a Cloudflare account, but is completely free for smaller projects, and very reasonably priced ($0.15/million requests per month) for large applications. You can use your own domain, and applications are protected with Cloudflare's state of the art DDoS protection. For more info, see the docs on [Worker Sites](https://developers.cloudflare.com/workers/platform/sites)
To deploy Dashy to Cloudflare, use the following link
-```
+
+```text
https://deploy.workers.cloudflare.com/?url=https://github.com/lissy93/dashy/tree/deploy_cloudflare
```
-#### Vercel
+### Vercel
+
[](https://vercel.com/new/project?template=https://github.com/lissy93/dashy)
[Vercel](https://vercel.com/) is a performance-focused platform for hosting static frontend apps. It comes bundled with some useful tools for monitoring and anaylzing application performance and other metrics. Vercel is free for personal use, allows for custom domains and has very reasonable limits.
To deploy Dashy to Vercel, use the following link
-```
+
+```text
https://vercel.com/new/project?template=https://github.com/lissy93/dashy
```
-#### DigitalOcean
+### DigitalOcean
+
[](https://cloud.digitalocean.com/apps/new?repo=https://github.com/lissy93/dashy/tree/deploy_digital-ocean&refcode=3838338e7f79)
[DigitalOcean](https://www.digitalocean.com/) is a cloud service providing affordable developer-friendly virtual machines from $5/month. But they also have an app platform, where you can run web apps, static sites, APIs and background workers. CDN-backed static sites are free for personal use.
-```
+```text
https://cloud.digitalocean.com/apps/new?repo=https://github.com/lissy93/dashy/tree/deploy_digital-ocean
```
-#### Google Cloud Platform
+### Google Cloud Platform
+
[](https://deploy.cloud.run/?git_repo=https://github.com/lissy93/dashy.git)
[Cloud Run](https://cloud.google.com/run/) is a service offered by [Google Cloud](https://cloud.google.com/). It's a fully managed serverless platform, for developing and deploying highly scalable containerized applications. Similar to AWS and Azure, GCP offers a wide range of cloud services, which are billed on a pay‐per‐use basis, but Cloud Run has a [free tier](https://cloud.google.com/run/pricing) offering 180,000 vCPU-seconds, 360,000 GiB-seconds, and 2 million requests per month.
To deploy Dashy to GCP, use the following link
-```
+
+```text
https://deploy.cloud.run/?git_repo=https://github.com/lissy93/dashy.git
```
-#### Platform.sh
+### Platform.sh
+
[](https://console.platform.sh/projects/create-project/?template=https://github.com/lissy93/dashy&utm_campaign=deploy_on_platform?utm_medium=button&utm_source=affiliate_links&utm_content=https://github.com/lissy93/dashy)
[Platform.sh](https://platform.sh) is an end-to-end solution for developing and deploying applications. It is geared towards enterprise users with large teams, and focuses on allowing applications to scale up and down. Unlike the above providers, Platform.sh is not free, although you can deploy a test app to it without needing a payment method
To deploy Dashy to Platform.sh, use the following link
-```
+
+```text
https://console.platform.sh/projects/create-project/?template=https://github.com/lissy93/dashy
```
-#### Render
+### Render
+
[](https://render.com/deploy?repo=https://github.com/lissy93/dashy/tree/deploy_render)
[Render](https://render.com) is cloud provider that provides easy deployments for static sites, Docker apps, web services, databases and background workers. Render is great for developing applications, and very easy to use. Static sites are free, and services start at $7/month. Currently there are only 2 server locations - Oregon, USA and Frankfurt, Germany. For more info, see the [Render Docs](https://render.com/docs)
To deploy Dashy to Render, use the following link
-```
+
+```text
https://render.com/deploy?repo=https://github.com/lissy93/dashy/tree/deploy_render
```
-#### Scalingo
+### Scalingo
+
[](https://my.scalingo.com/deploy?source=https://github.com/lissy93/dashy#master)
[Scalingo](https://scalingo.com/) is a scalable container-based cloud platform as a service. It's focus is on compliance and uptime, and is geared towards enterprise users. Scalingo is also not free, although they do have a 3-day free trial that does not require a payment method.
To deploy Dashy to Scalingo, use the following link
-```
+
+```text
https://my.scalingo.com/deploy?source=https://github.com/lissy93/dashy#master
```
-#### Play-with-Docker
+### Play-with-Docker
+
[](https://labs.play-with-docker.com/?stack=https://raw.githubusercontent.com/Lissy93/dashy/master/docker-compose.yml)
[Play with Docker](https://labs.play-with-docker.com/) is a community project by Marcos Liljedhal and Jonathan Leibiusky and sponsored by Docker, intended to provide a hands-on learning environment. Their labs let you quickly spin up a Docker container or stack, and test out the image in a temporary, sandboxed environment. There's no need to sign up, and it's completely free.
To run Dashy in PWD, use the following URL:
-```
+
+```text
https://labs.play-with-docker.com/?stack=https://raw.githubusercontent.com/Lissy93/dashy/master/docker-compose.yml
```
-#### Surge.sh
+### Surge.sh
+
[Surge.sh](http://surge.sh/) is quick and easy static web publishing platform for frontend-apps.
Surge supports [password-protected projects](https://surge.sh/help/adding-password-protection-to-a-project). You can also [add a custom domain](https://surge.sh/help/adding-a-custom-domain) and then [force HTTPS by default](https://surge.sh/help/using-https-by-default) and optionally [set a custom SSL certificate](https://surge.sh/help/securing-your-custom-domain-with-ssl)
To deploy Dashy to Surge.sh, first clone and cd into Dashy, install dependencies, and then use the following commands
-```
+
+```bash
yarn add -g surge
yarn build
surge ./dist
@@ -287,7 +315,6 @@ However without Dashy's node server, there are a couple of features that will be
---
-
## Requirements
### System Requirements
@@ -295,12 +322,15 @@ However without Dashy's node server, there are a couple of features that will be
Dashy works well on a Raspberry Pi (tested on Pi 3 and later), but should also run well on any system.
### Docker
+
Initial app build causes a spike in resource usage, but once the built app is running it is fairly steady. For this reason, Dashy works best with a minimum of 1GB of memory, and 1GB of disk space.
### Bare Metal
+
Minimum 526mb mem, 2GB disk space.
### CDN / Cloud Deploy
+
No specific requirements. The built application alone (without the Node server) is very light-weight, and can be handled smoothly by pretty much any CDN or cloud deployment service (see [this list](/docs/deployment.md#deploy-to-cloud-service) or natively supported cloud providers).
If you're using your own icons, or other assets, additional disk space will be required for those resources.
diff --git a/docs/developing.md b/docs/developing.md
index 2f2f0905..a7c0935d 100644
--- a/docs/developing.md
+++ b/docs/developing.md
@@ -24,6 +24,7 @@ If you're adding new features, you may want to check out the [Development Guides
## Setting up the Dev Environment
### Prerequisites
+
You will need either the latest or LTS version of **[Node.js](https://nodejs.org/)** to build and serve the application and **[Git](https://git-scm.com/downloads)** to easily fetch the code, and push any changes. If you plan on running or deploying the container, you'll also need **[Docker](https://docs.docker.com/get-docker/)**. To avoid any unexpected issues, ensure you've got at least **[NPM](https://www.npmjs.com/get-npm)** V 7.5 or **[Yarn](https://classic.yarnpkg.com/en/docs/install/#windows-stable)** 1.22 (you may find [NVM](https://github.com/nvm-sh/nvm) helpful for switching/ managing versions).
### Running the Project
@@ -33,34 +34,40 @@ You will need either the latest or LTS version of **[Node.js](https://nodejs.org
3. Install dependencies: `yarn`
4. Start dev server: `yarn dev`
-Dashy should now be being served on http://localhost:8080/. Hot reload is enabled, so making changes to any of the files will trigger them to be rebuilt and the page refreshed.
+Dashy should now be being served on . Hot reload is enabled, so making changes to any of the files will trigger them to be rebuilt and the page refreshed.
### Project Commands
#### Basics
+
- **`yarn build`** - In the interest of speed, the application is pre-compiled, this means that the config file is read during build-time, and therefore the app needs to rebuilt for any new changes to take effect. Luckily this is very straight forward. Just run `yarn build` or `docker exec -it [container-id] yarn build`
- **`yarn start`** - Starts a web server, and serves up the production site from `./dist` (must run build command first)
#### Development
+
- **`yarn dev`** - Starts the development server with hot reloading
- **`yarn lint`** - Lints code to ensure it follows a consistent, neat style
- **`yarn test`** - Runs tests, and outputs results
#### 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 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
+
- **`yarn build-and-start`** - Builds the app, runs checks and starts the production server. Commands are run in parallel, and so is faster than running them in independently. Uses the `yarn build` and `yarn start` commands
- **`yarn build-watch`** - If you find yourself making frequent changes to your configuration, and do not want to have to keep manually rebuilding, then this option is for you. It will watch for changes to any files within the projects root, and then trigger a rebuild. Note that if you are developing new features, then `yarn dev` would be more appropriate, as it's significantly faster at recompiling (under 1 second), and has hot reloading, linting and testing integrated
- **`yarn pm2-start`** - Starts the Node server using [PM2](https://pm2.keymetrics.io/), a process manager for Node.js applications, that helps them stay alive. PM2 has some built-in basic monitoring features, and an optional [management solution](https://pm2.io/). If you are running the app on bare metal, it is recommended to use this start command
#### Notes
+
- If you are using NPM, replace `yarn` with `npm run`
- If you are using Docker, precede each command with `docker exec -it [container-id]`. Container ID can be found by running `docker ps`
- You can manage the app using the [Vue-CLI Service](https://cli.vuejs.org/guide/cli-service.html), with `npx vue-cli-service [command]`. Or to start the Vue Management UI, run `npx vue ui`, and open `http://localhost:8000`
### Environmental Variables
+
All environmental variables are optional. Currently there are not many environmental variables used, as most of the user preferences are stored under `appConfig` in the `conf.yml` file.
You can set variables either in your environment, or using the [`.env`](https://github.com/Lissy93/dashy/blob/master/.env) file.
@@ -75,6 +82,7 @@ You can set variables either in your environment, or using the [`.env`](https://
- `VUE_APP_VERSION` - Again, set automatically using package.json during build time
### Environment Modes
+
You can set the environment using the `NODE_ENV` variable. By default, the correct environment should be selected based on the script you run to start the app. The following environments are supported: `production`, `development` and `test`. For more info, see [Vue CLI Environment Modes](https://cli.vuejs.org/guide/mode-and-env.html#modes).
---
@@ -82,6 +90,7 @@ You can set the environment using the `NODE_ENV` variable. By default, the corre
## Git Strategy
### Git Flow
+
Like most Git repos, we are following the [Github Flow](https://guides.github.com/introduction/flow) standard.
1. Create a branch (or fork if you don'd have write access)
@@ -93,10 +102,12 @@ Like most Git repos, we are following the [Github Flow](https://guides.github.co
7. Merge 🎉
### Git Branch Naming
+
The format of your branch name should be something similar to: `[TYPE]/[TICKET]_[TITLE]`
For example, `FEATURE/420_Awesome-feature` or `FIX/690_login-server-error`
### Commit Emojis
+
Using a single emoji at the start of each commit message, to indicate the type task, makes the commit ledger easier to understand, plus it looks cool.
- 🎨 `:art:` - Improve structure / format of the code.
@@ -127,14 +138,17 @@ Using a single emoji at the start of each commit message, to indicate the type t
For a full list of options, see [gitmoji.dev](https://gitmoji.dev/)
### PR Guidelines
+
Once you've made your changes, and pushed them to your fork or branch, you're ready to open a pull request!
For a pull request to be merged, it must:
+
- Must be backwards compatible
- The build, lint and tests (run by GH actions) must pass
- There must not be any merge conflicts
When you submit your PR, include the required info, by filling out the PR template. Including:
+
- A brief description of your changes
- The issue, ticket or discussion number (if applicable)
- For UI relate updates include a screenshot
@@ -144,7 +158,9 @@ When you submit your PR, include the required info, by filling out the PR templa
---
## Resources for Beginners
+
New to Web Development? Glad you're here! Dashy is a pretty simple app, so it should make a good candidate for your first PR. Presuming that you already have a basic knowledge of JavaScript, the following articles should point you in the right direction for getting up to speed with the technologies used in this project:
+
- [Open Source for Beginners](https://opensource.guide/how-to-contribute/)
- [Introduction to Vue.js](https://v3.vuejs.org/guide/introduction.html)
- [Vue.js Walkthrough](https://www.taniarascia.com/getting-started-with-vue/)
@@ -164,11 +180,12 @@ As well as Node, Git and Docker- you'll also need an IDE (e.g. [VS Code](https:/
## App Info
-## Style Guide
+### Style Guide
Linting is done using [ESLint](https://eslint.org/), and using the [Vue.js Styleguide](https://github.com/vuejs/eslint-config-standard), which is very similar to the [AirBnB Stylguide](https://github.com/airbnb/javascript). You can run `yarn lint` to report and fix issues. While the dev server is running, issues will be reported to the console automatically, and any lint errors will trigger the build to fail. Note that all lint checks must pass before any PR can be merged. Linting is also run as a git pre-commit hook
The most significant things to note are:
+
- Indentation should be done with two spaces
- Strings should use single quotes
- All statements must end in a semi-colon
@@ -180,15 +197,17 @@ The most significant things to note are:
- Avoid console statements in the frontend
Styleguides:
+
- Vue: [Vue styleguide](https://vuejs.org/v2/style-guide/)
- JavaScript: [github.com/airbnb/javascript](https://github.com/airbnb/javascript)
---
-## Application Structure
+### Application Structure
#### Files in the Root: `./`
-```
+
+```text
╮
├── package.json # Project meta-data, dependencies and paths to scripts
├── src/ # Project front-end source code
@@ -207,7 +226,7 @@ Styleguides:
#### Frontend Source: `./src/`
-```
+```text
./src
├── App.vue # Vue.js starting file
├── assets # Static non-compiled assets
@@ -340,9 +359,11 @@ Styleguides:
## Development Tools
### Performance - Lighthouse
+
The easiest method of checking performance is to use Chromium's build in auditing tool, Lighthouse. To run the test, open Developer Tools (usually F12) --> Lighthouse and click on the 'Generate Report' button at the bottom.
### Dependencies - BundlePhobia
+
[BundlePhobia](https://bundlephobia.com/) is a really useful app that lets you analyze the cost of adding any particular dependency to an application
---
diff --git a/docs/development-guides.md b/docs/development-guides.md
index cba17f0c..b88d1ff5 100644
--- a/docs/development-guides.md
+++ b/docs/development-guides.md
@@ -3,6 +3,7 @@
A series of short tutorials, to guide you through the most common development tasks.
Sections:
+
- [Creating a new theme](#creating-a-new-theme)
- [Writing Translations](#writing-translations)
- [Adding a new option in the config file](#adding-a-new-option-in-the-config-file)
@@ -17,10 +18,12 @@ Sections:
Adding a new theme is really easy. There's two things you need to do: Pass the theme name to Dashy, so that it can be added to the theme selector dropdown menu, and then write some styles!
-##### 1. Add Theme Name
+### 1. Add Theme Name
+
Choose a snappy name for you're theme, and add it to the `builtInThemes` array inside [`defaults.js`](https://github.com/Lissy93/dashy/blob/master/src/utils/defaults.js#L27).
-##### 2. Write some Styles!
+### 2. Write some Styles
+
Put your theme's styles inside [`color-themes.scss`](https://github.com/Lissy93/dashy/blob/master/src/styles/color-themes.scss).
Create a new block, and make sure that `data-theme` matches the theme name you chose above. For example:
@@ -45,10 +48,12 @@ Dashy is using [vue-i18n](https://vue-i18n.intlify.dev/guide/) to manage multi-l
Adding a new language is pretty straightforward, with just three steps:
-##### 1. Create a new Language File
+### 1. Create a new Language File
+
Create a new JSON file in `./src/assets/locales` name is a 2-digit [ISO-639 code](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) for your language, E.g. for German `de.json`, French `fr.json` or Spanish `es.json` - You can find a list of all ISO codes at [iso.org](https://www.iso.org/obp/ui).
-##### 2. Translate!
+### 2. Translate
+
Using [`en.json`](https://github.com/Lissy93/dashy/tree/master/src/assets/locales/en.json) as an example, translate the JSON values to your language, while leaving the keys as they are. It's fine to leave out certain items, as if they're missing they will fall-back to English. If you see any attribute which include curly braces (`{xxx}`), then leave the inner value of these braces as is, as this is for variables.
```json
@@ -65,7 +70,7 @@ Using [`en.json`](https://github.com/Lissy93/dashy/tree/master/src/assets/locale
}
```
-##### 3. Add your file to the app
+### 3. Add your file to the app
In [`./src/utils/languages.js`](https://github.com/Lissy93/dashy/tree/master/src/utils/languages.js), you need to do 2 small things:
@@ -73,6 +78,7 @@ First import your new translation file, do this at the top of the page.
E.g. `import de from '@/assets/locales/de.json';`
Second, add it to the array of languages, e.g:
+
```javascript
export const languages = [
{
@@ -89,11 +95,12 @@ export const languages = [
},
];
```
+
You can also add your new language to the readme, under the [Language Switching](https://github.com/Lissy93/dashy#language-switching-) section, and optionally include your name/ username if you'd like to be credited for your work. Done!
If you are not comfortable with making pull requests, or do not want to modify the code, then feel free to instead send the translated file to me, and I can add it into the application. I will be sure to credit you appropriately.
-# Adding a new option in the config file
+## Adding a new option in the config file
This section is for, adding a new setting to the config file.
@@ -101,6 +108,7 @@ All of the users config is specified in `./public/conf.yml` - see [Configuring D
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
+
- Application settings should be located under `appConfig`
- Page info (such as text and metadata) should be under `pageInfo`
- Data relating to specific sections should be under `section[n].displayData`
@@ -132,7 +140,9 @@ For example:
"example": "0821c65656"
}
```
+
or
+
```json
"iconSize": {
"enum": [ "small", "medium", "large" ],
@@ -144,6 +154,7 @@ or
Finally, add your new property to the [`configuring.md`](./configuring.md) API docs. Put it under the relevant section, and be sure to include field name, data type, a description and mention that it is optional. If your new feature needs more explaining, then you can also document it under the relevant section elsewhere in the documentation.
Checklist:
+
- [ ] Ensure the new attribute is actually necessary, and nothing similar already exists
- [ ] Update the [Schema](https://github.com/Lissy93/dashy/blob/master/src/utils/ConfigSchema.js) with the parameters for your new option
- [ ] If required, set a default or fallback value (usually in [`defaults.js`](https://github.com/Lissy93/dashy/blob/master/src/utils/defaults.js))
@@ -163,12 +174,12 @@ It is important to thoroughly test after any big dependency updates.
When Dashy is deployed to Netlify, it is effectively running as a static app, and therefore the server-side code for the Node.js endpoints is not available. However Netlify now supports serverless cloud lambda functions, which can be used to replace most functionality.
-#### 1. Run Netlify Dev Server
+### 1. Run Netlify Dev Server
First off, install the Netlify CLI: `npm install netlify-cli -g`
Then, from within the root of Dashy's directory, start the server, by running: `netlify dev`
-#### 2. Create a lambda function
+### 2. Create a lambda function
This should be saved it in the [`./services/serverless-functions`](https://github.com/Lissy93/dashy/tree/master/services/serverless-functions) directory
@@ -179,7 +190,7 @@ exports.handler = async () => ({
});
```
-#### 3. Redirect the Node endpoint to the function
+### 3. Redirect the Node endpoint to the function
In the [`netlify.toml`](https://github.com/Lissy93/dashy/blob/FEATURE/serverless-functions/netlify.toml) file, add a 301 redirect, with the path to the original Node.js endpoint, and the name of your cloud function
@@ -194,20 +205,23 @@ In the [`netlify.toml`](https://github.com/Lissy93/dashy/blob/FEATURE/serverless
---
## Hiding Page Furniture on Certain Routes
+
For some pages (such as the login page, the minimal start page, etc) the basic page furniture, (like header, footer, nav, etc) is not needed. This section explains how you can hide furniture on a new view (step 1), or add a component that should be hidden on certain views (step 2).
-##### 1. Add the route name to the should hide array
+### 1. Add the route name to the should hide array
In [`./src/utils/defaults.js`](https://github.com/Lissy93/dashy/blob/master/src/utils/defaults.js), there's an array called `hideFurnitureOn`. Append the name of the route (the same as it appears in [`router.js`](https://github.com/Lissy93/dashy/blob/master/src/router.js)) here.
-##### 2. Add the conditional to the structural component to hide
+### 2. Add the conditional to the structural component to hide
First, import the helper function:
+
```javascript
import { shouldBeVisible } from '@/utils/SectionHelpers';
```
Then you can create a computed value, that calls this function, passing in the route name:
+
```javascript
export default {
...
@@ -221,6 +235,7 @@ export default {
```
Finally, in the markup of your component, just add a `v-if` statement, referencing your computed value
+
```vue
...
@@ -230,6 +245,7 @@ Finally, in the markup of your component, just add a `v-if` statement, referenci
---
## Adding / Using Environmental Variables
+
All environmental variables are optional. Currently there are not many environmental variables used, as most of the user preferences are stored under `appConfig` in the `conf.yml` file.
You can set variables either in your environment, or using the [`.env`](https://github.com/Lissy93/dashy/blob/master/.env) file.
@@ -250,12 +266,10 @@ To build a widget, you'll also need some basic knowledge of Vue.js. The [officia
If you just want to jump straight in, then [here](https://github.com/Lissy93/dashy/commit/3da76ce2999f57f76a97454c0276301e39957b8e) is a complete implementation of a new example widget, or take a look at the [`XkcdComic.vue`](https://github.com/Lissy93/dashy/blob/master/src/components/Widgets/XkcdComic.vue) widget, which is pretty simple.
-
### Step 1 - Create Widget
Firstly, create a new `.vue` file under [`./src/components/Widgets`](https://github.com/Lissy93/dashy/tree/master/src/components/Widgets).
-
```vue
@@ -297,14 +311,15 @@ export default {
```
All widgets extend from the [Widget](https://github.com/Lissy93/dashy/blob/master/src/mixins/WidgetMixin.js) mixin. This provides some basic functionality that is shared by all widgets. The mixin includes the following `options`, `startLoading()`, `finishLoading()`, `error()` and `update()`.
+
- **Getting user options: `options`**
- - Any user-specific config can be accessed with `this.options.something` (where something is the data key your accessing)
+ - Any user-specific config can be accessed with `this.options.something` (where something is the data key your accessing)
- **Loading state: `startLoading()` and `finishLoading()`**
- - You can show the loader with `this.startLoading()`, then when your data request completes, hide it again with `this.finishLoading()`
+ - You can show the loader with `this.startLoading()`, then when your data request completes, hide it again with `this.finishLoading()`
- **Error handling: `error()`**
- - If something goes wrong (such as API error, or missing user parameters), then call `this.error()` to show message to user
+ - If something goes wrong (such as API error, or missing user parameters), then call `this.error()` to show message to user
- **Updating data: `update()`**
- - When the user clicks the update button, or if continuous updates are enabled, then the `update()` method within your widget will be called
+ - When the user clicks the update button, or if continuous updates are enabled, then the `update()` method within your widget will be called
### Step 2 - Adding Functionality
@@ -362,6 +377,7 @@ fetchData() {
```
There are three things happening here:
+
- If the response completes successfully, we'll pass the results to another function that will handle them
- If there's an error, then we call `this.error()`, which will show a message to the user
- Whatever the result, once the request has completed, we call `this.finishLoading()`, which will hide the loader
@@ -398,7 +414,6 @@ Styles can be written your your widget within the `