@@ -428,7 +879,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)
@@ -440,17 +891,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`
@@ -460,13 +914,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
@@ -488,5 +945,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) 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 37025d96..050baadb 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), 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)
@@ -66,7 +68,7 @@ For all available options, and to learn more, see the [Docker Run Docs](https://
Dashy is also available through GHCR: `docker pull ghcr.io/lissy93/dashy:latest`
-If you're deploying Dashy on a modern ARM-based board, such as a Raspberry Pi (2+), then you'll need to use one of Dashy's ARM images. Set the base image + tag to either `lissy93/dashy:arm64v8` or `lissy93/dashy:arm32v7`, depending on your system architecture. You can also use the `multi-arch` image, which should work on all system architectures.
+If you're deploying Dashy on a modern ARM-based board, such as a Raspberry Pi (2+), then you'll need to use one of Dashy's ARM images. Set the base image + tag to either `lissy93/dashy:arm64v8` or `lissy93/dashy:arm32v7`, depending on your system architecture. You can also use the `multi-arch` image, which should work on all system architectures.
The image defaults to `:latest`, but you can instead specify a specific version, e.g. `docker pull lissy93/dashy:release-1.5.0`
@@ -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,15 +129,17 @@ 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.
-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:
-6. General: In the Task field type in Install dashy. Uncheck “Enabled” option. Select root User.
-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.
-```
+ > 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:
+6. General: In the Task field type in Install dashy. Uncheck "Enabled" option. Select root User.
+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,121 +164,142 @@ 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.
Some hosting providers required a bit of extra configuration, which was why I've made separate branches for deploying to those services (named: [`deploy_cloudflare`](https://github.com/Lissy93/dashy/tree/deploy_cloudflare), [`deploy_digital-ocean`](https://github.com/Lissy93/dashy/tree/deploy_digital-ocean), [`deploy_platform-sh`](https://github.com/Lissy93/dashy/tree/deploy_platform-sh) and [`deploy_render`](https://github.com/Lissy93/dashy/tree/deploy_render)). If there's another cloud service which you'd like 1-click deployment to be supported for, feel free to raise an issue.
-**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.
+**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 available. 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
+[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 costs a minimum of $5 for 1,000 dyno hours per month (there are around 720 hours in a month), 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.
+[Vercel](https://vercel.com/) is a performance-focused platform for hosting static frontend apps. It comes bundled with some useful tools for monitoring and analyzing 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
+[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
@@ -281,13 +309,12 @@ surge ./dist
## Hosting with CDN
-Once Dashy has been built, it is effectivley just a static web app. This means that it can be served up with pretty much any static host, CDN or web server. To host Dashy through a CDN, the steps are very similar to building from source: clone the project, cd into it, install dependencies, write your config file and build the app. Once build is complete you will have a `./dist` directory within Dashy's root, and this is the build application which is ready to be served up.
+Once Dashy has been built, it is effectively just a static web app. This means that it can be served up with pretty much any static host, CDN or web server. To host Dashy through a CDN, the steps are very similar to building from source: clone the project, cd into it, install dependencies, write your config file and build the app. Once build is complete you will have a `./dist` directory within Dashy's root, and this is the build application which is ready to be served up.
-However without Dashy's node server, there are a couple of features that will be unavailible to you, including: Writing config changes to disk through the UI, triggering a rebuild through the UI and application status checks. Everything else will work fine.
+However without Dashy's node server, there are a couple of features that will be unavailable to you, including: Writing config changes to disk through the UI, triggering a rebuild through the UI and application status checks. Everything else will work fine.
---
-
## Requirements
### System Requirements
@@ -295,13 +322,16 @@ 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.
+
+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,
+
+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#deploy-to-cloud-service) or natively supported cloud providers).
+
+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/deploymentdeploy-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 886d3c83..f96b0249 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`
+- 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/)
@@ -158,37 +174,40 @@ New to Web Development? Glad you're here! Dashy is a pretty simple app, so it sh
- [Git cheat sheet](http://git-cheatsheet.com/)
- [Basics of using NPM](https://www.freecodecamp.org/news/what-is-npm-a-node-package-manager-tutorial-for-beginners/)
-As well as Node, Git and Docker- you'll also need an IDE (e.g. [VS Code](https://code.visualstudio.com/) or [Vim](https://www.vim.org/)) and a terminal (Windows users may find [WSL](https://docs.microsoft.com/en-us/windows/wsl/) more convenient).
+As well as Node, Git and Docker- you'll also need an IDE (e.g. [VS Code](https://code.visualstudio.com/) or [Vim](https://www.vim.org/)) and a terminal (Windows users may find [WSL](https://docs.microsoft.com/en-us/windows/wsl/) more convenient).
---
## 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
+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 Styleguide](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
- The final element in all objects must be preceded with a comma
- Maximum line length is 100
- There must be exactly one blank line between sections, before function names, and at the end of the file
-- With conditionals, put else on the same line as your if block’s closing brace
+- With conditionals, put else on the same line as your if block's closing brace
- All multiline blocks must use braces
- 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)
+- 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,13 +226,13 @@ Styleguides:
#### Frontend Source: `./src/`
-```
+```text
./src
├── App.vue # Vue.js starting file
├── assets # Static non-compiled assets
│ ├── fonts # .ttf font files
│ ├── locales # All app text, each language in a separate JSON file
-│ ╰── interface-icons # SVG icons used in the app
+│ ╰── interface-icons # SVG icons used in the app
├── components # All front-end Vue web components
│ ├── Charts # Charting components for dynamically displaying widget data
│ │ ├── Gauge.vue # A speed-dial style chart for showing 0 - 100 values
@@ -250,7 +269,7 @@ Styleguides:
│ │ ├── Item.vue # Main link item, which is displayed within an item group
│ │ ├── ItemGroup.vue # Item group is a section containing icons
│ │ ├── ItemIcon.vue # The icon used by both items and sections
-│ │ ├── ItemOpenMethodIcon.vue # A small icon, visible on hover, indicating opening method
+│ │ ├── ItemOpenMethodIcon.vue # A small icon, visible on hover, indicating opening method
│ │ ├── ItemContextMenu.vue # The right-click menu, for showing Item opening methods and info
│ │ ├── SectionContextMenu.vue # The right-click menu, for showing Section edit/ open options
│ │ ╰── StatusIndicator.vue # Traffic light dot, showing if app is online or down
@@ -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
---
@@ -356,4 +377,3 @@ When running the build command, several warnings appear. These are not errors, a
`WARN A new version of sass-loader is available. Please upgrade for best experience.` - Currently we're using an older version of SASS loader, since the more recent releases do not seem to be compatible with the Vue CLI's webpack configuration.
`WARN asset size limit: The following asset(s) exceed the recommended size limit (244 KiB).` - For the PWA to support Windows 10, a splash screen asset is required, and is quite large. This throws a warning, however PWA assets are not loaded until needed, so shouldn't have any impact on application performance. A similar warning is thrown for the Raleway font, and that is looking to be addressed.
-
diff --git a/docs/development-guides.md b/docs/development-guides.md
index 40ab54ff..d579c370 100644
--- a/docs/development-guides.md
+++ b/docs/development-guides.md
@@ -1,8 +1,9 @@
# Development Guides
-A series of short tutorials, to guide you through the most common development tasks.
+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,11 +18,13 @@ 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
-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).
+### 1. Add Theme Name
-##### 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).
+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
+
+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:
```css
@@ -35,7 +38,7 @@ Then you can go ahead and write you're own custom CSS. Although all CSS is suppo
For a full guide on styling, see [Theming Docs](./theming).
-Note that if you're theme is just for yourself, and you're not submitting a PR, then you can instead just pass it under `appConfig.cssThemes` inside your config file. And then put your theme in your own stylesheet, and pass it into the Docker container - [see how](https://github.com/Lissy93/dashy/blob/master/docs/theming#adding-your-own-theme).
+Note that if you're theme is just for yourself, and you're not submitting a PR, then you can instead just pass it under `appConfig.cssThemes` inside your config file. And then put your theme in your own stylesheet, and pass it into the Docker container - [see how](https://github.com/Lissy93/dashy/blob/master/docs/theming.md#adding-your-own-theme).
## Writing Translations
@@ -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.
+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,7 +154,8 @@ or
Finally, add your new property to the [`configuring.md`](./configuring) 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
+
+- [ ] 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))
- [ ] Document the new value in [`configuring.md`](./configuring), and if required under the relevant section in the docs
@@ -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 {
...
@@ -219,8 +233,9 @@ 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,18 +311,19 @@ 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
-**Accessing User Options**
+#### **Accessing User Options**
If your widget is going to accept any parameters from the user, then we can access these with `this.options.[parmName]`. It's best to put these as computed properties, which will enable us to check it exists, is valid, and if needed format it. For example, if we have an optional property called `count` (to determine number of results), we can do the following, and then reference it within our component with `this.count`
@@ -324,7 +339,7 @@ computed: {
},
```
-**Adding an API Endpoint**
+#### **Adding an API Endpoint**
If your widget makes a data request, then add the URL for the API under point to the `widgetApiEndpoints` array in [`defaults.js`](https://github.com/Lissy93/dashy/blob/master/src/utils/defaults.js#L207)
@@ -349,7 +364,7 @@ endpoint() {
},
```
-**Making an API Request**
+#### **Making an API Request**
Axios is used for making data requests, so import it into your component: `import axios from 'axios';`
@@ -362,11 +377,12 @@ 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
-**Processing Response**
+#### **Processing Response**
In the above example, we call the `processData()` method with the result from the API, so we need to create that under the `methods` section. How you handle this data will vary depending on what's returned by the API, and what you want to render to the user. But however you do it, you will likely need to create a data variable to store the response, so that it can be easily displayed in the HTML.
@@ -384,7 +400,7 @@ And then, inside your `processData()` method, you can set the value of this, wit
`this.myResults = 'whatever'`
```
-**Rendering Response**
+#### **Rendering Response**
Now that the results are in the correct format, and stored as data variables, we can use them within the ` ` to render results to the user. Again, how you do this will depend on the structure of your data, and what you want to display, but at it's simplest, it might look something like this:
@@ -392,12 +408,11 @@ Now that the results are in the correct format, and stored as data variables, we
{{ myResults }}
```
-**Styling**
+#### **Styling**
Styles can be written your your widget within the ` |
@@ -57,4 +61,4 @@ Even if the target is not set (or is set to `sametab`), you can still launch any
If you don't like the custom context menu, it can be disabled by setting `appConfig.disableContextMenu: true`.
-If you get a 'Refused to Connect' error in the modal or workspace views, then the target app has it's X-Frame-Options HTTP set to block requests from embedded content. You can easily fix this by setting this header to ALLOW, for instructions on how to do so, see the [Troubleshooting Docs](/docs/troubleshooting#refused-to-connect-in-modal-or-workspace-view).
+If you get a 'Refused to Connect' error in the modal or workspace views, then the target app has it's X-Frame-Options HTTP set to block requests from embedded content. You can easily fix this by setting this header to ALLOW, for instructions on how to do so, see the [Troubleshooting Docs](/docs/troubleshootingrefused-to-connect-in-modal-or-workspace-view).
diff --git a/docs/assets/CONTRIBUTORS.svg b/docs/assets/CONTRIBUTORS.svg
index 1a583d00..b3dfa6da 100644
--- a/docs/assets/CONTRIBUTORS.svg
+++ b/docs/assets/CONTRIBUTORS.svg
@@ -1,120 +1,279 @@
-
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
- 
+ 
- 
- 
- 
- 
- 
+ 
+ 
@@ -143,13 +136,6 @@
EVOTk
- 
@@ -157,14 +143,28 @@
Snyk Bot
+ 
@@ -186,6 +186,35 @@
Erik Vroon
+ 
+ 
+ 
+ 
@@ -193,6 +222,21 @@
UrekD
+ 
+ 
@@ -200,6 +244,34 @@
Remygrandin
+ 
+ 
+ 
+ 
@@ -208,6 +280,20 @@
+ 
+ 
@@ -222,13 +308,21 @@
Alessandro Del Prete
+ 
@@ -244,18 +338,60 @@
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
@@ -272,6 +423,20 @@
Begin
+ 
+ 
@@ -279,6 +444,14 @@
David
+ 
@@ -286,20 +459,55 @@
DeepSource Bot
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+