From 2c6799125f1c84c06c8ac5aaa4bead81245905b5 Mon Sep 17 00:00:00 2001 From: Alicia Sykes Date: Sat, 12 Jun 2021 13:42:14 +0100 Subject: [PATCH 001/157] Create cloudflare-deploy.yml --- .github/workflows/cloudflare-deploy.yml | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) create mode 100644 .github/workflows/cloudflare-deploy.yml diff --git a/.github/workflows/cloudflare-deploy.yml b/.github/workflows/cloudflare-deploy.yml new file mode 100644 index 00000000..2cfb0c40 --- /dev/null +++ b/.github/workflows/cloudflare-deploy.yml @@ -0,0 +1,17 @@ +name: Build +on: + push: + pull_request: + repository_dispatch: +jobs: + deploy: + runs-on: ubuntu-latest + timeout-minutes: 60 + steps: + - uses: actions/checkout@master + - name: Build site + run: 'yarn && Yarn build' + - name: Publish + uses: cloudflare/wrangler-action@1.2.0 + with: + apiToken: ${{ secrets.CF_API_TOKEN }} From 9e9a1c7fe78a587a792714076d44123073402bb5 Mon Sep 17 00:00:00 2001 From: Alicia Sykes Date: Sat, 12 Jun 2021 16:26:18 +0100 Subject: [PATCH 002/157] Updates the docs --- README.md | 27 +++++++- docs/configuring.md | 19 +++++- docs/getting-started.md | 145 ++++++++++++++++++++++++++++++++++++++-- docs/user-guide.md | 35 +++++++++- 4 files changed, 215 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index c92f9369..a5f710fa 100644 --- a/README.md +++ b/README.md @@ -39,6 +39,8 @@ Demo

+**[⬆️ Back to Top](#dashy)** + --- ## Getting Started 🛫 @@ -76,8 +78,11 @@ After making changes to your configuration file, you will need to run: `yarn bui Dashy supports 1-Click deployments on several popular cloud platforms (with more on the way!). To get started, just click a link below: - [Deploy to Netlify](https://app.netlify.com/start/deploy?repository=https://github.com/lissy93/dashy) - [Deploy to Heroku](https://heroku.com/deploy?template=https://github.com/Lissy93/dashy) +- [Deploy with Vercel](https://vercel.com/new/project?template=https://github.com/lissy93/dashy) - [Deploy with PWD](https://labs.play-with-docker.com/?stack=https://raw.githubusercontent.com/Lissy93/dashy/master/docker-compose.yml) +**[⬆️ Back to Top](#dashy)** + --- ## Configuring 🔧 @@ -92,6 +97,8 @@ You can check that your config matches Dashy's [schema](https://github.com/Lissy You may find these [example config](https://gist.github.com/Lissy93/000f712a5ce98f212817d20bc16bab10) helpful for getting you started +**[⬆️ Back to Top](#dashy)** + --- ## Theming 🎨 @@ -108,6 +115,8 @@ The app comes with a number of built-in themes, but it's also easy to write you' You can also apply custom CSS overrides directly through the UI (Under Config menu --> Custom CSS), or specify it in your config file under `appConfig.customCss`. If you have a lot of custom styles, you can pass in the path to a stylesheet, in `appConfig.externalStyleSheet`. +**[⬆️ Back to Top](#dashy)** + --- ## Cloud Backup & Sync ☁ @@ -120,6 +129,8 @@ This is useful not only for backing up your configuration off-site, but it also 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. +**[⬆️ Back to Top](#dashy)** + --- ## Developing 🧱 @@ -134,6 +145,8 @@ Hot reload is enabled, so changes will be detected automatically, triggering the If you are new to Vue.js or web development and want to learn more, [here are some resources](docs/developing.md#resources-for-beginners) to help get you started. Dashy is a pretty straight-forward application, so would make an ideal candidate for your first PR! +**[⬆️ Back to Top](#dashy)** + --- ## Contributing 😇 @@ -151,6 +164,8 @@ Before you submit your pull request, please ensure the following: - If a new dependency is required, it must be essential, and it must be thoroughly checked out for security or efficiency issues - Your pull request will need to be up-to-date with master, and the PR template must be filled in +**[⬆️ Back to Top](#dashy)** + --- ## Support 🙋‍♀️ @@ -170,6 +185,8 @@ For more general questions about any of the technologies used, [StackOverflow](h - **Email**: `alicia at omg dot lol` - **Public Key** [`0688 F8D3 4587 D954 E9E5 1FB8 FEDB 68F5 5C02 83A7`](https://keybase.io/aliciasykes/pgp_keys.asc?fingerprint=0688f8d34587d954e9e51fb8fedb68f55c0283a7) +**[⬆️ Back to Top](#dashy)** + --- ## Documentation 📘 @@ -183,15 +200,15 @@ For more general questions about any of the technologies used, [StackOverflow](h - [Backup & Restore](/docs/backup-restore.md) - [Theming](/docs/theming.md) +**[⬆️ Back to Top](#dashy)** + --- ## Credits 🏆 ### Contributors 👥 -![Auto-generated contributors](https://raw.githubusercontent.com/Lissy93/dashy/03fbaf35ff4653d16a622cfce00a1347c13d0192/docs/assets/CONTRIBUTORS.svg) - -_(^^ It's lonely here all by myself - submit a PR to become listed as a contributor!)_ +![Auto-generated contributors](https://raw.githubusercontent.com/Lissy93/dashy/master/docs/assets/CONTRIBUTORS.svg) ### Dependencies 🔗 @@ -226,6 +243,8 @@ The 1-Click deploy demo uses [Play-with-Docker Labs](https://play-with-docker.co There are a few self-hosted web apps, that serve a similar purpose to Dashy. If you're looking for a dashboard, and Dashy doesn't meet your needs, I highly recommend you check these projects out! Including, but not limited to: [HomeDash2](https://lamarios.github.io/Homedash2), [Homer](https://github.com/bastienwirtz/homer) (`Apache License 2.0`), [Organizr](https://organizr.app/) (`GPL-3.0 License`) and [Heimdall](https://github.com/linuxserver/Heimdall) (`MIT License`) +**[⬆️ Back to Top](#dashy)** + --- ## License 📜 @@ -249,6 +268,8 @@ TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWAREOR THE OR OTHER DEALINGS IN THE SOFTWARE. ``` +**[⬆️ Back to Top](#dashy)** + --- Dashy - A feature-rich dashboard for your homelab 🚀 | Product Hunt diff --git a/docs/configuring.md b/docs/configuring.md index e6d4474c..addbb4a6 100644 --- a/docs/configuring.md +++ b/docs/configuring.md @@ -13,7 +13,6 @@ There's a couple of things to remember, before getting started: All fields are optional, unless otherwise stated. - #### Top-Level Fields **Field** | **Type** | **Required**| **Description** @@ -22,6 +21,8 @@ All fields are optional, unless otherwise stated. **`appConfig`** | `object` | _Optional_ | Settings related to how the app functions, including API keys and global styles. See [`appConfig`](#appconfig-optional) **`sections`** | `array` | Required | An array of sections, each containing an array of items, which will be displayed as links. See [`section`](#section) +**[⬆️ Back to Top](#configuring)** + #### `PageInfo` **Field** | **Type** | **Required**| **Description** @@ -31,6 +32,8 @@ All fields are optional, unless otherwise stated. **`navLinks`** | `array` | _Optional_ | Optional list of a maximum of 6 links, which will be displayed in the navigation bar. See [`navLinks`](#pageinfonavlinks-optional) **`footerText`** | `string` | _Optional_ | Text to display in the footer (note that this will override the default footer content). This can also include HTML and inline CSS +**[⬆️ Back to Top](#configuring)** + #### `pageInfo.navLinks` _(optional)_ **Field** | **Type** | **Required**| **Description** @@ -38,6 +41,8 @@ All fields are optional, unless otherwise stated. **`title`** | `string` | Required | The text to display on the link button **`path`** | `string` | Required | The URL to navigate to when clicked. Can be relative (e.g. `/about`) or absolute (e.g. `https://example.com` or `http://192.168.1.1`) +**[⬆️ Back to Top](#configuring)** + #### `appConfig` _(optional)_ **Field** | **Type** | **Required**| **Description** @@ -51,6 +56,8 @@ All fields are optional, unless otherwise stated. **`customCss`** | `string` | _Optional_ | Raw CSS that will be applied to the page. This can also be set from the UI. Please minify it first. **`showSplashScreen`** | `boolean` | _Optional_ | Should display a splash screen while the app is loading. Defaults to false, except on first load +**[⬆️ Back to Top](#configuring)** + #### `section` **Field** | **Type** | **Required**| **Description** @@ -60,6 +67,8 @@ All fields are optional, unless otherwise stated. **`items`** | `array` | Required | An array of items to be displayed within the section. See [`item`](#sectionitem) **`displayData`** | `object` | _Optional_ | Meta-data to optionally overide display settings for a given section. See [`displayData`](#sectiondisplaydata-optional) +**[⬆️ Back to Top](#configuring)** + #### `section.item` **Field** | **Type** | **Required**| **Description** @@ -72,6 +81,8 @@ All fields are optional, unless otherwise stated. **`color`** | `string` | _Optional_ | An optional color for the text and font-awesome icon to be displayed in. Note that this will override the current theme and so may not display well **`backgroundColor`** | `string` | _Optional_ | An optional background fill color for the that given item. Again, this will override the current theme and so might not display well against the background +**[⬆️ Back to Top](#configuring)** + #### `section.displayData` _(optional)_ **Field** | **Type** | **Required**| **Description** @@ -86,12 +97,15 @@ All fields are optional, unless otherwise stated. **`itemCountX`** | `number` | _Optional_ | The number of items to display per row / horizontally. If not set, it will be calculated automatically based on available space. Can only be set if `layout` is set to `grid`. Must be a whole number between `1` and `12` **`itemCountY`** | `number` | _Optional_ | The number of items to display per column / vertically. If not set, it will be calculated automatically based on available space. If `itemCountX` is set, then `itemCountY` can be calculated automatically. Can only be set if `layout` is set to `grid`. Must be a whole number between `1` and `12` +**[⬆️ Back to Top](#configuring)** + #### `section.icon` and `section.item.icon` **Field** | **Type** | **Required**| **Description** --- | --- | --- | --- **`icon`** | `string` | _Optional_ | The icon for a given item or section. Can be a font-awesome icon, favicon, remote URL or local URL. If set to `favicon`, the icon will be automatically fetched from the items website URL. To use font-awesome, specify the category, followed by the icon name, e.g. `fas fa-rocket`, `fab fa-monero` or `fal fa-duck` - note that to use pro icons, you mut specify `appConfig.fontAwesomeKey`. You can also use hosted any by specifying it's URL, e.g. `https://i.ibb.co/710B3Yc/space-invader-x256.png`. To use a local image, first store it in `./public/item-icons/` (or `-v /app/public/item-icons/` in Docker) , and reference it by name and extension - e.g. set `image.png` to use `./public/item-icon/image.png`, you can also use sub-folders if you have a lot of icons, to keep them organised. +**[⬆️ Back to Top](#configuring)** #### Example @@ -125,3 +139,6 @@ sections: # An array of sections ``` For more example config files, see: [this gist](https://gist.github.com/Lissy93/000f712a5ce98f212817d20bc16bab10) + +**[⬆️ Back to Top](#configuring)** + diff --git a/docs/getting-started.md b/docs/getting-started.md index 0cf405e2..15b1ae40 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -13,6 +13,9 @@ - [Updating Docker Container](#updating-docker-container) - [Automating Docker Updates](#automatic-docker-updates) - [Updating from Source](#updating-dashy-from-source) +- [Web Server Configuration](#web-server-configuration) + - [NGINX](#nginx) + - [Apache](#apache) ## Deployment @@ -63,7 +66,7 @@ Dashy supports 1-Click deployments on several popular cloud platforms. #### Netlify [![Deploy to Netlify](https://www.netlify.com/img/deploy/button.svg)](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. +[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 ``` @@ -73,13 +76,62 @@ https://app.netlify.com/start/deploy?repository=https://github.com/lissy93/dashy #### Heroku [![Deploy to Heroku](https://www.herokucdn.com/deploy/button.svg)](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. +[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 ``` https://heroku.com/deploy?template=https://github.com/Lissy93/dashy ``` +#### Cloudflare Workers +[![Deploy to Cloudflare Workers](https://deploy.workers.cloudflare.com/button)](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 +``` +https://deploy.workers.cloudflare.com/?url=https://github.com/lissy93/dashy/tree/deploy_cloudflare +``` + +#### Deploy to Vercel +[![Deploy with Vercel](https://vercel.com/button)](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 +``` +https://vercel.com/new/project?template=https://github.com/lissy93/dashy +``` + +#### Deploy to DigitalOcean +[![Deploy to DO](https://www.deploytodo.com/do-btn-blue.svg)](https://cloud.digitalocean.com/apps/new?repo=https://github.com/lissy93/dashy/tree/deploy_digital-ocean&refcode=3838338e7f79) + +[DigitalOcan](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. + +``` +https://cloud.digitalocean.com/apps/new?repo=https://github.com/lissy93/dashy/tree/deploy_digital-ocean +``` + +#### Platform.sh +[![Deploy to Platform.sh](https://platform.sh/images/deploy/deploy-button-lg-blue.svg)](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 +``` +https://console.platform.sh/projects/create-project/?template=https://github.com/lissy93/dashy +``` + +#### Deploy to Scalingo +[![Deploy on Scalingo](https://cdn.scalingo.com/deploy/button.svg)](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 +``` +https://my.scalingo.com/deploy?source=https://github.com/lissy93/dashy#master +``` + #### Play-with-Docker [![Try in PWD](https://raw.githubusercontent.com/play-with-docker/stacks/cff22438/assets/images/button.png)](https://labs.play-with-docker.com/?stack=https://raw.githubusercontent.com/Lissy93/dashy/master/docker-compose.yml) @@ -89,6 +141,19 @@ To run Dashy in PWD, use the following URL: ``` https://labs.play-with-docker.com/?stack=https://raw.githubusercontent.com/Lissy93/dashy/master/docker-compose.yml ``` + +#### 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 +``` +yarn add -g surge +yarn build +surge ./dist +``` + **[⬆️ Back to Top](#getting-started)** --- @@ -121,9 +186,9 @@ To restart unhealthy containers automatically, check out [Autoheal](https://hub. ### Logs and Performance -You can view logs for a given Docker container with `docker logs [container-id]`, add the `--follow` flag to stream the logs. For more info, see the [Logging Documentation](https://docs.docker.com/config/containers/logging/). [Dozzle](https://dozzle.dev/) is a useful tool, that provides a web interface where you can stream and query logs from all your running containers from a single web app. +You can view logs for a given Docker container with `docker logs [container-id]`, add the `--follow` flag to stream the logs. For more info, see the [Logging Documentation](https://docs.docker.com/config/containers/logging/). There's also [Dozzle](https://dozzle.dev/), a useful tool, that provides a web interface where you can stream and query logs from all your running containers from a single web app. -You can check the resource usage for your running Docker containers with `docker stats` or `docker stats [container-id]`. For more info, see the [Stats Documentation](https://docs.docker.com/engine/reference/commandline/stats/). [cAdvisor](https://github.com/google/cadvisor) is a useful web app for viewing and analyzing resource usage and performance of your running containers. +You can check the resource usage for your running Docker containers with `docker stats` or `docker stats [container-id]`. For more info, see the [Stats Documentation](https://docs.docker.com/engine/reference/commandline/stats/). There's also [cAdvisor](https://github.com/google/cadvisor), a useful web app for viewing and analyzing resource usage and performance of all your running containers. You can also view logs, resource usage and other info as well as manage your Docker workflow in third-party Docker management apps. For example [Portainer](https://github.com/portainer/portainer) an all-in-one management web UI for Docker and Kubernetes, or [LazyDocker](https://github.com/jesseduffield/lazydocker) a terminal UI for Docker container management and monitoring. @@ -166,4 +231,74 @@ For more information, see the [Watchtower Docs](https://containrrr.dev/watchtowe 5. Start: `yarn start` -**[⬆️ Back to Top](#getting-started)** \ No newline at end of file +**[⬆️ Back to Top](#getting-started)** + +--- + +## Web Server Configuration + +_The following section only applies if you are not using Docker, and would like to use your own web server_ + +Dashy ships with a pre-configured Node.js server, in [`server.js`](https://github.com/Lissy93/dashy/blob/master/server.js) which serves up the contents of the `./dist` directory on a given port. You can start the server by running `node server`. Note that the app must have been build (run `yarn build`), and you need [Node.js](https://nodejs.org) installed. + +However, since Dashy is just a static web application, it can be served with whatever server you like. The following section outlines how you can configure a web server. + +### NGINX + +Create a new file in `/etc/nginx/sites-enabled/dashy` + +``` +server { + listen 80; + listen [::]:80; + + root /var/www/dashy/html; + index index.html; + + server_name your-domain.com www.your-domain.com; + + location / { + try_files $uri $uri/ =404; + } +} +``` +Then upload the build contents of Dashy's dist directory to that location. +For example: `scp -r ./dist/* [username]@[server_ip]:/var/www/dashy/html` + +### Apache + +Copy Dashy's dist folder to your apache server, `sudo cp -r ./dashy/dist /var/www/html/dashy`. + +In your Apache config, `/etc/apche2/apache2.conf` add: +``` + + Options Indexes FollowSymLinks + AllowOverride All + Require all granted + +``` + +Add a `.htaccess` file within `/var/www/html/dashy/.htaccess`, and add: +``` +Options -MultiViews +RewriteEngine On +RewriteCond %{REQUEST_FILENAME} !-f +RewriteRule ^ index.html [QSA,L] +``` + +Then restart Apache, with `sudo systemctl restart apache2` + +### cPanel +1. Login to your WHM +2. Open 'Feature Manager' on the left sidebar +3. Under 'Manage feature list', click 'Edit' +4. Find 'Application manager' in the list, enable it and hit 'Save' +5. Log into your users cPanel account, and under 'Software' find 'Application Manager' +6. Click 'Register Application', fill in the form using the path that Dashy is located, and choose a domain, and hit 'Save' +7. The application should now show up in the list, click 'Ensure dependencies', and move the toggle switch to 'Enabled' +8. If you need to change the port, click 'Add environmental variable', give it the name 'PORT', choose a port number and press 'Save'. +9. Dashy should now be running at your selected path an on a given port + +--- + +**[⬆️ Back to Top](#getting-started)** diff --git a/docs/user-guide.md b/docs/user-guide.md index 9c4ae7f5..ca2554b0 100644 --- a/docs/user-guide.md +++ b/docs/user-guide.md @@ -1,6 +1,19 @@ - ## User Guide +This article outlines how to use the application. If you are instead looking for deployment instructions, see [Getting Started](/docs/getting-started.md) and [Configuring](/docs/configuring.md) + +### Contents +- [Searching](#searching) +- [Keyboard Shortcuts](#keyboard-shortcuts) +- [Theme Switching](#theme-switching) +- [Visual Options](#visual-options) +- [Opening Items](#opening-items) +- [Sections and Items](#sections-and-items) +- [Icons](#icons) +- [Metadata](#metadata) +- [Editing Config](#editing-config) +- [Managing Config Data](#managing-config-data) + ### Searching A key requirement for any start page is being able to quickly and effectively find the item your looking for. For Dashy, a lot of thought was put into the most intuitive method to filter links. @@ -13,16 +26,22 @@ The following properties are used to filter items by: - URL - Only the base URL is searched, the protocol and parameters are omitted - Description +**[⬆️ Back to Top](#user-guide)** + ### Keyboard Shortcuts Many people find using the keyboard significantly more efficient than having to reach for the mouse. And so Dashy has a series of keybindings and shortcuts to enable you to navigate through items quickly. Once you've searched for a given item, you can then tab through the list (or Shift + Tab to go backwards) until you've found the item you're looking for. You can also use the arrow keys to navigate up, down, left and right through the grid. To launch an item, just hit enter. You can also open an item in a new tab with Ctrl + Enter, or open the item in a pop-up modal with Alt + Enter. To close an open popup item, or any open menus, just hit Esc. +**[⬆️ Back to Top](#user-guide)** + ### Theme Switching You can change the current theme using the dropdown menu in the upper-right-hand quadrant. Your selected theme will be stored in local storage, and applied next time you load the page. For more information on customizing the look and feel of Dashy, see [Themeing Docs](/docs/theming.md) +**[⬆️ Back to Top](#user-guide)** + ### Visual Options There are several pre-built layout options to choose from depending on your requirements. Like the theme these options will be remembered in browser storage and applied on load. @@ -33,6 +52,8 @@ Next there's icon size. This changes the size of the item and it's icon. It can ![layout-options](https://i.ibb.co/NnzF82t/available-layout-options.png) +**[⬆️ Back to Top](#user-guide)** + ### Opening Items There are three methods of opening items. Clicking (or hitting Enter on a selected item) will use the default method, specified in the config file, under `item.target`. You can use Ctrl + Click or Ctrl + Enter to open and item in a new tab. @@ -41,6 +62,8 @@ You can also use Alt + Click or Alt + Enter, to open an item in a popup window. ![Example of a pop-up opened item](https://i.ibb.co/zSnznFF/dashy-popup.png) +**[⬆️ Back to Top](#user-guide)** + ### Sections and Items The main content in Dashy is split into sections, which contain icons. You can have as many sections as you need, and each section can have an unlimited amount of icons. Visually, the grid layout works better when sections have a similar number of icons. @@ -73,22 +96,30 @@ Sections also have several optional properties, which are specified under `secti └─────────────────────────────────────────────────────┘ ``` +**[⬆️ Back to Top](#user-guide)** + ### Icons Both sections and items can have an icon associated with them. There are several options for specifying icons. You can let the icon be automatically resolved and fetched from the items associated URL, by just setting the icon to `favicon`. You can use a font-awesome icon, by specifying it's name and category. Or you can pass in a URL, either to a locally hosted or remote image. For local images, you can put them in `./public/item-icons/` and then reference them just by the file name. +**[⬆️ Back to Top](#user-guide)** + ### Metadata Basic site information, displayed in the header and footer can be set from the UI. This includes: title, sub-title, footer text, and nav-bar links. Click the wrench icon in the upper-right corner, then go to the Site Metadata tab. Fill in your new data, and hit save. The page will be refreshed, and your changes will appear. These settings are stored under `pageInfo` in the config, and if set through the UI, will only be applied locally. +**[⬆️ Back to Top](#user-guide)** + ### Editing Config The config file can be edited from the UI, but take note that changes are only applied locally. You will need to either export this data into your conf.yml, or use the cloud backup and sync feature. To make changes to the config file, click the wrench icon in the upper-left hand corner. Then go to the Config tab. Here you'll find a JSON editor. You can switch from tree mode to plain-text mode if you find that easier. And parsing or validation issues will be displayed at the bottom of the screen. +**[⬆️ Back to Top](#user-guide)** + ### Managing Config Data You can download, backup or reset local config data directly from the UI. To apply config to Dashy on other devices, you will need to either download the config file, or use the cloud backup and sync feature. To download config, click the Wrench icon, in the upper-right hand corner, and then go to Download. Similarly, for cloud backup, click the Cloud icon in the upper right corner, and fill in the required fields. For detailed instructions, and technical information about backup and sync, please see the [Cloud Backup Documentation](/docs/backup-restore.md). You can also Reset all local settings from the config menu. This will not effect any data saved in your systems `conf.yml` file. - +**[⬆️ Back to Top](#user-guide)** From 8ecba77632b38e7cfab4c44bfd21e5a139f412c3 Mon Sep 17 00:00:00 2001 From: Alicia Sykes Date: Sat, 12 Jun 2021 16:31:36 +0100 Subject: [PATCH 003/157] Delete cloudflare-deploy.yml --- .github/workflows/cloudflare-deploy.yml | 17 ----------------- 1 file changed, 17 deletions(-) delete mode 100644 .github/workflows/cloudflare-deploy.yml diff --git a/.github/workflows/cloudflare-deploy.yml b/.github/workflows/cloudflare-deploy.yml deleted file mode 100644 index 2cfb0c40..00000000 --- a/.github/workflows/cloudflare-deploy.yml +++ /dev/null @@ -1,17 +0,0 @@ -name: Build -on: - push: - pull_request: - repository_dispatch: -jobs: - deploy: - runs-on: ubuntu-latest - timeout-minutes: 60 - steps: - - uses: actions/checkout@master - - name: Build site - run: 'yarn && Yarn build' - - name: Publish - uses: cloudflare/wrangler-action@1.2.0 - with: - apiToken: ${{ secrets.CF_API_TOKEN }} From 8665c6010db7178a7527e00c4fb7907d02c10589 Mon Sep 17 00:00:00 2001 From: Alicia Sykes Date: Sun, 13 Jun 2021 09:39:44 +0100 Subject: [PATCH 004/157] Adds new fields for user authentication --- docs/configuring.md | 11 +++++++++++ src/utils/ConfigSchema.json | 32 ++++++++++++++++++++++++++++++++ 2 files changed, 43 insertions(+) diff --git a/docs/configuring.md b/docs/configuring.md index addbb4a6..acae2cae 100644 --- a/docs/configuring.md +++ b/docs/configuring.md @@ -55,6 +55,17 @@ All fields are optional, unless otherwise stated. **`externalStyleSheet`** | `string` or `string[]` | _Optional_ | Either a URL to an external stylesheet or an array or URLs, which can be applied as themes within the UI **`customCss`** | `string` | _Optional_ | Raw CSS that will be applied to the page. This can also be set from the UI. Please minify it first. **`showSplashScreen`** | `boolean` | _Optional_ | Should display a splash screen while the app is loading. Defaults to false, except on first load +**`auth`** | `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. Note authentication is done on the client side, and so if your instance of Dashy is exposed to the internet, it is recommend to configure your web server to handle this. See [`auth`](#appconfigauth-optional) + +**[⬆️ Back to Top](#configuring)** + +#### `appConfig.auth` _(optional)_ + +**Field** | **Type** | **Required**| **Description** +--- | --- | --- | --- +**`user`** | `string` | Required | Username to log in with +**`hash`** | `string` | Required | A SHA-256 hashed password +**`type`** | `string` | _Optional_ | The user type, either admin or normal **[⬆️ Back to Top](#configuring)** diff --git a/src/utils/ConfigSchema.json b/src/utils/ConfigSchema.json index 365083f7..748b649d 100644 --- a/src/utils/ConfigSchema.json +++ b/src/utils/ConfigSchema.json @@ -94,6 +94,38 @@ "type": "boolean", "default": false, "description": "Display a loading screen when the app is launched" + }, + "auth": { + "type": "array", + "description": "Usernames and hashed credentials for frontend authentication", + "items": { + "type": "object", + "additionalProperties": false, + "required": [ + "user", + "hash" + ], + "properties": { + "user": { + "type": "string", + "description": "The username for a user" + }, + "hash": { + "type": "string", + "description": "A SHA-256 hashed password for that user", + "minLength": 64, + "maxLength": 64 + }, + "type": { + "enum": [ + "admin", + "normal" + ], + "description": "User type, denoting privilege level, either admin or normal", + "default": "normal" + } + } + } } }, "additionalProperties": false From 25ee90b987febff8d3b8c4f78b937c34989a9a65 Mon Sep 17 00:00:00 2001 From: Alicia Sykes Date: Sun, 13 Jun 2021 09:40:40 +0100 Subject: [PATCH 005/157] Adds functionality and supporting components for frontend authentication --- src/assets/interface-icons/user-logout.svg | 1 + src/components/FormElements/Button.vue | 1 + src/components/Settings/SettingsContainer.vue | 38 +++++ src/router.js | 38 ++++- src/styles/color-palette.scss | 3 + src/utils/Auth.js | 52 +++++++ src/utils/defaults.js | 4 + src/views/Login.vue | 132 ++++++++++++++++++ 8 files changed, 263 insertions(+), 6 deletions(-) create mode 100644 src/assets/interface-icons/user-logout.svg create mode 100644 src/utils/Auth.js create mode 100644 src/views/Login.vue diff --git a/src/assets/interface-icons/user-logout.svg b/src/assets/interface-icons/user-logout.svg new file mode 100644 index 00000000..5c9daff8 --- /dev/null +++ b/src/assets/interface-icons/user-logout.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/src/components/FormElements/Button.vue b/src/components/FormElements/Button.vue index 4ea452d1..58674634 100644 --- a/src/components/FormElements/Button.vue +++ b/src/components/FormElements/Button.vue @@ -1,5 +1,6 @@ @@ -122,6 +150,7 @@ export default { box-shadow: var(--item-shadow); cursor: pointer; text-decoration: none; + position: relative; &:hover { box-shadow: var(--item-hover-shadow); background: var(--item-background-hover); @@ -175,6 +204,13 @@ export default { } } +/* Colored dot showing service status */ +.status-indicator { + position: absolute; + top: 0; + right: 0; +} + .opening-method-icon { display: none; // Hidden by default, visible on hover } diff --git a/src/components/LinkItems/ItemGroup.vue b/src/components/LinkItems/ItemGroup.vue index ef3dba8c..a375d7d6 100644 --- a/src/components/LinkItems/ItemGroup.vue +++ b/src/components/LinkItems/ItemGroup.vue @@ -28,6 +28,7 @@ :color="item.color" :backgroundColor="item.backgroundColor" :itemSize="newItemSize" + :enableStatusCheck="shouldEnableStatusCheck(item.statusCheck)" @itemClicked="$emit('itemClicked')" @triggerModal="triggerModal" /> @@ -49,6 +50,7 @@ import IframeModal from '@/components/LinkItems/IframeModal.vue'; export default { name: 'ItemGroup', + inject: ['config'], props: { groupId: String, title: String, @@ -92,6 +94,10 @@ export default { modalChanged(changedTo) { this.$emit('change-modal-visibility', changedTo); }, + shouldEnableStatusCheck(itemPreference) { + const globalPreference = this.config.appConfig.statusCheck || false; + return itemPreference !== undefined ? itemPreference : globalPreference; + }, }, }; diff --git a/src/components/LinkItems/StatusIndicator.vue b/src/components/LinkItems/StatusIndicator.vue new file mode 100644 index 00000000..6b1864dd --- /dev/null +++ b/src/components/LinkItems/StatusIndicator.vue @@ -0,0 +1,122 @@ + + + + + + + diff --git a/src/main.js b/src/main.js index 90c589d6..eea75224 100644 --- a/src/main.js +++ b/src/main.js @@ -1,12 +1,14 @@ import Vue from 'vue'; +/* Import component Vue plugins, used throughout the app */ import VTooltip from 'v-tooltip'; // A Vue directive for Popper.js, tooltip component import VModal from 'vue-js-modal'; // Modal component import VSelect from 'vue-select'; // Select dropdown component import VTabs from 'vue-material-tabs'; // Tab view component, used on the config page import Toasted from 'vue-toasted'; // Toast component, used to show confirmation notifications + import { toastedOptions } from './utils/defaults'; -import App from './App.vue'; +import Dashy from './App.vue'; import router from './router'; import './registerServiceWorker'; @@ -20,5 +22,5 @@ Vue.config.productionTip = false; new Vue({ router, - render: (awesome) => awesome(App), + render: (awesome) => awesome(Dashy), }).$mount('#app'); diff --git a/src/router.js b/src/router.js index 968938f4..b32aa255 100644 --- a/src/router.js +++ b/src/router.js @@ -1,36 +1,15 @@ import Vue from 'vue'; import Router from 'vue-router'; -import Home from './views/Home.vue'; -import Login from './views/Login.vue'; -import conf from '../public/conf.yml'; // Main site configuration -import { pageInfo as defaultPageInfo, localStorageKeys } from './utils/defaults'; -import { isLoggedIn } from './utils/Auth'; + +import Home from '@/views/Home.vue'; +import Login from '@/views/Login.vue'; +import { isLoggedIn } from '@/utils/Auth'; +import { appConfig, pageInfo, sections } from '@/utils/ConfigAccumalator'; Vue.use(Router); -const { sections, pageInfo, appConfig } = conf; -let localPageInfo; -try { - localPageInfo = JSON.parse(localStorage[localStorageKeys.PAGE_INFO]); -} catch (e) { - localPageInfo = undefined; -} - -let localAppConfig; -try { - localAppConfig = JSON.parse(localStorage[localStorageKeys.APP_CONFIG]); -} catch (e) { - localAppConfig = undefined; -} - -const config = { - sections: sections || [], - pageInfo: localPageInfo || pageInfo || defaultPageInfo, - appConfig: localAppConfig || appConfig || {}, -}; - const isAuthenticated = () => { - const users = config.appConfig.auth; + const users = appConfig.auth; return (!users || isLoggedIn(users)); }; @@ -40,7 +19,11 @@ const router = new Router({ path: '/', name: 'home', component: Home, - props: config, + props: { + appConfig, + pageInfo, + sections, + }, meta: { title: pageInfo.title || 'Home Page', metaTags: [ @@ -56,7 +39,7 @@ const router = new Router({ name: 'login', component: Login, props: { - appConfig: config.appConfig, + appConfig, }, beforeEnter: (to, from, next) => { if (isAuthenticated()) router.push({ path: '/' }); diff --git a/src/utils/ConfigAccumalator.js b/src/utils/ConfigAccumalator.js new file mode 100644 index 00000000..2ecec4ac --- /dev/null +++ b/src/utils/ConfigAccumalator.js @@ -0,0 +1,58 @@ +/** + * Reads the users config from `conf.yml`, and combines it with any local preferences + * Also ensures that any missing attributes are populated with defaults, and the + * object is structurally sound, to avoid any error if the user is missing something + * The main config object is make up of three parts: appConfig, pageInfo and sections + */ +import Defaults, { localStorageKeys } from '@/utils/defaults'; +import conf from '../../public/conf.yml'; + +export const appConfig = (() => { + if (localStorage[localStorageKeys.APP_CONFIG]) { + return JSON.parse(localStorage[localStorageKeys.APP_CONFIG]); + } else if (conf.appConfig) { + return conf.appConfig; + } else { + return Defaults.appConfig; + } +})(); + +export const pageInfo = (() => { + const defaults = Defaults.pageInfo; + let localPageInfo; + try { + localPageInfo = JSON.parse(localStorage[localStorageKeys.PAGE_INFO]); + } catch (e) { + localPageInfo = {}; + } + const pi = conf.pageInfo || defaults; // The page info object to return + pi.title = localPageInfo.title || conf.pageInfo.title || defaults.title; + pi.description = localPageInfo.description || conf.pageInfo.description || defaults.description; + pi.navLinks = localPageInfo.navLinks || conf.pageInfo.navLinks || defaults.navLinks; + pi.footerText = localPageInfo.footerText || conf.pageInfo.footerText || defaults.footerText; + return pi; +})(); + +export const sections = (() => { + // If the user has stored sections in local storage, return those + const localSections = localStorage[localStorageKeys.CONF_SECTIONS]; + if (localSections) { + try { + const json = JSON.parse(localSections); + if (json.length >= 1) return json; + } catch (e) { + // The data in local storage has been malformed, will return conf.sections instead + } + } + // If the function hasn't yet returned, then return the config file sections + return conf.sections; +})(); + +export const config = (() => { + const result = { + appConfig, + pageInfo, + sections, + }; + return result; +})(); diff --git a/src/utils/ConfigSchema.json b/src/utils/ConfigSchema.json index 748b649d..7c8f5035 100644 --- a/src/utils/ConfigSchema.json +++ b/src/utils/ConfigSchema.json @@ -95,6 +95,11 @@ "default": false, "description": "Display a loading screen when the app is launched" }, + "statusCheck": { + "type": "boolean", + "default": false, + "description": "Displays an online/ offline status for each of your services" + }, "auth": { "type": "array", "description": "Usernames and hashed credentials for frontend authentication", @@ -256,6 +261,11 @@ "provider": { "type": "string", "description": "Provider name, e.g. Microsoft" + }, + "statusCheck": { + "type": "boolean", + "default": false, + "description": "Whether or not to display online/ offline status for this service. Will override appConfig.statusCheck" } } } From bc77fbdb71cc171e886a772191ba2c75242d0c91 Mon Sep 17 00:00:00 2001 From: Alicia Sykes Date: Mon, 14 Jun 2021 20:46:39 +0100 Subject: [PATCH 012/157] Updates documentation :) --- README.md | 23 ++++++++++++++++------ docs/{getting-started.md => deployment.md} | 23 +++++++++++----------- docs/developing.md | 15 +++++++++++++- docs/readme.md | 2 +- docs/user-guide.md | 6 +++--- 5 files changed, 47 insertions(+), 22 deletions(-) rename docs/{getting-started.md => deployment.md} (91%) diff --git a/README.md b/README.md index 4b8e0ab6..7f760ea3 100644 --- a/README.md +++ b/README.md @@ -19,6 +19,7 @@ - Customizable layout options, and item sizes - Quickly preview a website, by holding down the Alt key while clicking, to open it in a resizable pop-up modal - Many options for icons, including full Font-Awesome support and the ability to auto-fetch icon from URLs favicon +- Option to show service status for each of your apps / links, for basic availability and uptime monitoring - Additional info for each item visible on hover (including opening method icon and description as a tooltip) - Option for full-screen background image, custom nav-bar links, and custom footer text - User preferences stored in local storage and applied on load @@ -46,7 +47,7 @@ ## Getting Started 🛫 -> For full setup instructions, see: [**Getting Started**](./docs/getting-started.md) +> For full setup instructions, see: [**Deployment**](./docs/deployment.md) #### Deploying from Docker Hub 🐳 @@ -104,7 +105,7 @@ You may find these [example config](https://gist.github.com/Lissy93/000f712a5ce9 ## Theming 🎨 -> For full configuration documentation, see: [**Theming**](./docs/theming.md) +> For full theming documentation, see: [**Theming**](./docs/theming.md)

@@ -122,7 +123,7 @@ You can also apply custom CSS overrides directly through the UI (Under Config me ## Cloud Backup & Sync ☁ -> For full documentation, see: [**Cloud Backup & Sync**](./docs/backup-restore.md) +> For full backup documentation, see: [**Cloud Backup & Sync**](./docs/backup-restore.md) Dashy has an **optional** 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. @@ -136,7 +137,7 @@ All data is encrypted before being sent to the backend. In Dashy, this is done i ## Authentication 💂 -> For full development documentation, see: [**Authentication**](./docs/authentication.md) +> For full authentication documentation, see: [**Authentication**](./docs/authentication.md) Dashy has a built-in login feature, which can be used for basic access control. To enable this feature, add an `auth` attribute under `appConfig`, containing an array of users, each with a username, SHA-256 hashed password and optional user type. @@ -146,7 +147,17 @@ appConfig: - user: alicia hash: 4D1E58C90B3B94BCAD9848ECCACD6D2A8C9FBC5CA913304BBA5CDEAB36FEEFA3 ``` -At present, access control is handles on the frontend, and therefore in security-critical applications, it is recommended to use VPN access for authentication. +At present, access control is handled on the frontend, and therefore in security-critical situations, it is recommended to use an alternate method for authentication, such as [Authelia](https://www.authelia.com/), a VPN or web server and firewall rules. + +**[⬆️ Back to Top](#dashy)** + +--- + +## Status Indicators 🚦 + +> For full monitoring documentation, see: [**Status Indicators**](./docs/status-indicators.md) + +Dashy has an optional feature that can display a small icon ([like this](./docs/assets/status-check-demo.gif)) next to each of your running services, indicating it's current status. This is useful if you are using Dashy as your homelab's start page, as it gives you an overview of the health of each of your running services. By default, this feature is off, but you can enable it globally by setting `appConfig.statusCheck: true`, or enable/ disable it for an individual item, with `item[n].statusCheck`. **[⬆️ Back to Top](#dashy)** @@ -210,7 +221,7 @@ For more general questions about any of the technologies used, [StackOverflow](h ## Documentation 📘 -- [Getting Started](/docs/getting-started.md) +- [Getting Started](/docs/deployment.md) - [Configuring](/docs/configuring.md) - [Developing](/docs/developing.md) - [Contributing](/docs/contributing.md) diff --git a/docs/getting-started.md b/docs/deployment.md similarity index 91% rename from docs/getting-started.md rename to docs/deployment.md index cf44a0fe..f4d77ea0 100644 --- a/docs/getting-started.md +++ b/docs/deployment.md @@ -1,6 +1,6 @@ -# Getting Started +# Deployment -- [Deployment](#deployment) +- [Running the App](#running-the-app) - [Deploy with Docker](#deploy-with-docker) - [Deploy from Source](#deploy-from-source) - [Deploy to Cloud Service](#deploy-to-cloud-service) @@ -17,7 +17,7 @@ - [NGINX](#nginx) - [Apache](#apache) -## Deployment +## Running the App ### Deploy with Docker @@ -154,7 +154,7 @@ yarn build surge ./dist ``` -**[⬆️ Back to Top](#getting-started)** +**[⬆️ Back to Top](#deployment)** --- @@ -177,6 +177,7 @@ The following commands are defined in the [`package.json`](https://github.com/Li - **`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 - **`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 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 +- **`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 ### Healthchecks @@ -192,7 +193,7 @@ You can check the resource usage for your running Docker containers with `docker You can also view logs, resource usage and other info as well as manage your Docker workflow in third-party Docker management apps. For example [Portainer](https://github.com/portainer/portainer) an all-in-one management web UI for Docker and Kubernetes, or [LazyDocker](https://github.com/jesseduffield/lazydocker) a terminal UI for Docker container management and monitoring. -**[⬆️ Back to Top](#getting-started)** +**[⬆️ Back to Top](#deployment)** --- ## Updating @@ -230,8 +231,7 @@ For more information, see the [Watchtower Docs](https://containrrr.dev/watchtowe 4. Re-build: `yarn build` 5. Start: `yarn start` - -**[⬆️ Back to Top](#getting-started)** +**[⬆️ Back to Top](#deployment)** --- @@ -241,8 +241,9 @@ _The following section only applies if you are not using Docker, and would like Dashy ships with a pre-configured Node.js server, in [`server.js`](https://github.com/Lissy93/dashy/blob/master/server.js) which serves up the contents of the `./dist` directory on a given port. You can start the server by running `node server`. Note that the app must have been build (run `yarn build`), and you need [Node.js](https://nodejs.org) installed. -However, since Dashy is just a static web application, it can be served with whatever server you like. The following section outlines how you can configure a web server. +If you wish to run Dashy from a sub page (e.g. `example.com/dashy`), then just set the `BASE_URL` environmental variable to that page name (in this example, `/dashy`), before building the app, and the path to all assets will then resolve to the new path, instead of `./`. +However, since Dashy is just a static web application, it can be served with whatever server you like. The following section outlines how you can configure a web server. ### NGINX Create a new file in `/etc/nginx/sites-enabled/dashy` @@ -299,13 +300,13 @@ Then restart Apache, with `sudo systemctl restart apache2` 8. If you need to change the port, click 'Add environmental variable', give it the name 'PORT', choose a port number and press 'Save'. 9. Dashy should now be running at your selected path an on a given port -**[⬆️ Back to Top](#getting-started)** +**[⬆️ Back to Top](#deployment)** --- ## Authentication -Dashy has built-in client-side authentication, but for security-critical situations, it is recommend to either use a VPN for access, or implement your own authentication using your cloud provider, web server or firewall rules. For more info, see **[Authentication Docs](/docs/authentication.md)**. +Dashy has built-in authentication and login functionality. However, since this is handled on the client-side, if you are using Dashy in security-critical situations, it is recommended to use an alternate method for authentication, such as [Authelia](https://www.authelia.com/), a VPN or web server and firewall rules. For more info, see **[Authentication Docs](/docs/authentication.md)**. -**[⬆️ Back to Top](#getting-started)** +**[⬆️ Back to Top](#deployment)** diff --git a/docs/developing.md b/docs/developing.md index c56476dc..be11bff8 100644 --- a/docs/developing.md +++ b/docs/developing.md @@ -47,6 +47,17 @@ Note: - 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` +### Environmental Variables + +- `PORT` - The port in which the application will run (defaults to `4000` for the Node.js server, and `80` within the Docker container) +- `VUE_APP_DOMAIN` - The URL where Dashy is going to be accessible from. This should include the protocol, hostname and (if not 80 or 443), then the port too, e.g. `https://localhost:3000`, `http://192.168.1.2:4002` or `https://dashy.mydomain.com` + +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. + +If you do add new variables, ensure that there is always a fallback (define it in [`defaults.js`](https://github.com/Lissy93/dashy/blob/master/src/utils/defaults.js)), so as to not cause breaking changes. Don't commit your `.env` file to git, but instead take a few moments to document what you've added under the appropriate section. Try and follow the concepts outlined in the [12 factor app](https://12factor.net/config), as these are good practices. + +Any environmental variables used by the frontend are preceded with `VUE_APP_`. Vue will merge the contents of your `.env` file into the app in a similar way to the ['dotenv'](https://github.com/motdotla/dotenv) package, where any variables that you set on your system will always take preference over the contents of any `.env` file. + ### 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: - [Introduction to Vue.js](https://v3.vuejs.org/guide/introduction.html) @@ -79,7 +90,6 @@ The most significant things to note are: For the full styleguide, see: [github.com/airbnb/javascript](https://github.com/airbnb/javascript) - ### Frontend Components All frontend code is located in the `./src` directory, which is split into 5 sub-folders: @@ -122,6 +132,9 @@ Running `yarn upgrade` will updated all dependencies based on the ranges specifi #### 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 + ### Directory Structure #### Files in the Root: `./` diff --git a/docs/readme.md b/docs/readme.md index cc360ba0..97d43511 100644 --- a/docs/readme.md +++ b/docs/readme.md @@ -1,6 +1,6 @@ ## Contents -- [Getting Started](/docs/getting-started.md) +- [Deployment](/docs/deployment.md) - [Configuring](/docs/configuring.md) - [Developing](/docs/developing.md) - [Contributing](/docs/contributing.md) diff --git a/docs/user-guide.md b/docs/user-guide.md index ca2554b0..60d2c549 100644 --- a/docs/user-guide.md +++ b/docs/user-guide.md @@ -1,6 +1,6 @@ ## User Guide -This article outlines how to use the application. If you are instead looking for deployment instructions, see [Getting Started](/docs/getting-started.md) and [Configuring](/docs/configuring.md) +This article outlines how to use the application. If you are instead looking for deployment instructions, see [Deployment](/docs/deployment.md) and [Configuring](/docs/configuring.md) ### Contents - [Searching](#searching) @@ -66,7 +66,7 @@ You can also use Alt + Click or Alt + Enter, to open an item in a popup window. ### Sections and Items -The main content in Dashy is split into sections, which contain icons. You can have as many sections as you need, and each section can have an unlimited amount of icons. Visually, the grid layout works better when sections have a similar number of icons. +The main content in Dashy is defined as an array of sections, each of which contains an array of items. You can have as many sections as you need, and each section can have an unlimited amount of items. If you are using the grid layout, then it works better, visually if each of your sections have similar number of items. Sections are collapsible, which is useful for those sections which contain less used applications, or are particularly long. The collapse state of a given section is remembered (stored in local storage), and applied on load. @@ -100,7 +100,7 @@ Sections also have several optional properties, which are specified under `secti ### Icons -Both sections and items can have an icon associated with them. There are several options for specifying icons. You can let the icon be automatically resolved and fetched from the items associated URL, by just setting the icon to `favicon`. You can use a font-awesome icon, by specifying it's name and category. Or you can pass in a URL, either to a locally hosted or remote image. For local images, you can put them in `./public/item-icons/` and then reference them just by the file name. +Both sections and items can have an icon associated with them. There are several options for specifying icons. You can let the icon be automatically resolved and fetched from the items associated URL, by setting it's value to `favicon`. You can use a font-awesome icon, by specifying it's name and category, e.g. `fas fa-rocket`. Or you can pass in a URL, either to a locally hosted or remote image. For local images, you can put them in `./public/item-icons/` and then reference them just by the file name. **[⬆️ Back to Top](#user-guide)** From 62c79527f2c25909ef9637d7455f294f3277b05a Mon Sep 17 00:00:00 2001 From: Alicia Sykes Date: Mon, 14 Jun 2021 20:46:59 +0100 Subject: [PATCH 013/157] Gernal refactoring --- docker-compose.yml | 2 +- package.json | 3 ++- {bin => services}/healthcheck.js | 0 vue.config.js | 1 + yarn.lock | 18 +++++++++--------- 5 files changed, 13 insertions(+), 11 deletions(-) rename {bin => services}/healthcheck.js (100%) diff --git a/docker-compose.yml b/docker-compose.yml index 0a8ab5b8..4e4dce67 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -18,7 +18,7 @@ services: # - GID=1000 restart: unless-stopped healthcheck: - test: ['CMD', 'node', '/app/bin/healthcheck'] + test: ['CMD', 'node', '/app/services/healthcheck'] interval: 1m30s timeout: 10s retries: 3 diff --git a/package.json b/package.json index e70245f1..83706219 100644 --- a/package.json +++ b/package.json @@ -8,10 +8,11 @@ "dev": "vue-cli-service serve", "build": "vue-cli-service build", "lint": "vue-cli-service lint --fix", + "pm2-start": "npx pm2 start server.js", "build-watch": "vue-cli-service build --watch", "build-and-start": "npm-run-all --parallel build start", "validate-config": "node src/utils/ConfigValidator", - "health-check": "node bin/healthcheck" + "health-check": "node services/healthcheck" }, "dependencies": { "ajv": "^8.5.0", diff --git a/bin/healthcheck.js b/services/healthcheck.js similarity index 100% rename from bin/healthcheck.js rename to services/healthcheck.js diff --git a/vue.config.js b/vue.config.js index 9883bae5..30be157a 100644 --- a/vue.config.js +++ b/vue.config.js @@ -1,4 +1,5 @@ module.exports = { + publicPath: process.env.BASE_URL, // || './', chainWebpack: config => { config.module.rules.delete('svg'); }, diff --git a/yarn.lock b/yarn.lock index c771d857..e067356e 100644 --- a/yarn.lock +++ b/yarn.lock @@ -2411,9 +2411,9 @@ caniuse-api@^3.0.0: lodash.uniq "^4.5.0" caniuse-lite@^1.0.0, caniuse-lite@^1.0.30001109, caniuse-lite@^1.0.30001219: - version "1.0.30001236" - resolved "https://registry.yarnpkg.com/caniuse-lite/-/caniuse-lite-1.0.30001236.tgz#0a80de4cdf62e1770bb46a30d884fc8d633e3958" - integrity sha512-o0PRQSrSCGJKCPZcgMzl5fUaj5xHe8qA2m4QRvnyY4e1lITqoNkr7q/Oh1NcpGSy0Th97UZ35yoKcINPoq7YOQ== + version "1.0.30001237" + resolved "https://registry.yarnpkg.com/caniuse-lite/-/caniuse-lite-1.0.30001237.tgz#4b7783661515b8e7151fc6376cfd97f0e427b9e5" + integrity sha512-pDHgRndit6p1NR2GhzMbQ6CkRrp4VKuSsqbcLeOQppYPKOYkKT/6ZvZDvKJUqcmtyWIAHuZq3SVS2vc1egCZzw== case-sensitive-paths-webpack-plugin@^2.3.0: version "2.4.0" @@ -3715,9 +3715,9 @@ eslint-plugin-standard@^4.0.0: integrity sha512-ZL7+QRixjTR6/528YNGyDotyffm5OQst/sGxKDwGb9Uqs4In5Egi4+jbobhqJoyoCM6/7v/1A5fhQ7ScMtDjaQ== eslint-plugin-vue@^7.9.0: - version "7.11.0" - resolved "https://registry.yarnpkg.com/eslint-plugin-vue/-/eslint-plugin-vue-7.11.0.tgz#c19b098899b7e3cd692beffbbe73611064ef1ea6" - integrity sha512-Qwo8wilqnOXnG9B5auEiTstyaHefyhHd5lEhhxemwXoWsAxIW2yppzuVudowC5n+qn1nMLNV9TANkTthBK7Waw== + version "7.11.1" + resolved "https://registry.yarnpkg.com/eslint-plugin-vue/-/eslint-plugin-vue-7.11.1.tgz#77eb4b44032d5cca79f9af21d06991d8694a314a" + integrity sha512-lbw3vkEAGqYjqd1HpPFWHXtYaS8mILTJ5KOpJfRxO3Fo7o0wCf1zD7vSOasbm6nTA9xIgvZQ4VcyGIzQXxznHw== dependencies: eslint-utils "^2.1.0" natural-compare "^1.4.0" @@ -7378,9 +7378,9 @@ regexpp@^2.0.1: integrity sha512-lv0M6+TkDVniA3aD1Eg0DVpfU/booSu7Eev3TDO/mZKHBfVjgCGTV4t4buppESEYDtkArYFOxTJWv6S5C+iaNw== regexpp@^3.1.0: - version "3.1.0" - resolved "https://registry.yarnpkg.com/regexpp/-/regexpp-3.1.0.tgz#206d0ad0a5648cffbdb8ae46438f3dc51c9f78e2" - integrity sha512-ZOIzd8yVsQQA7j8GCSlPGXwg5PfmA1mrq0JP4nGhh54LaKN3xdai/vHUDu74pKwV8OxseMS65u2NImosQcSD0Q== + version "3.2.0" + resolved "https://registry.yarnpkg.com/regexpp/-/regexpp-3.2.0.tgz#0425a2768d8f23bad70ca4b90461fa2f1213e1b2" + integrity sha512-pq2bWo9mVD43nbts2wGv17XLiNLya+GklZ8kaDLV2Z08gDCsGpnKn9BFMepvWuHCbyVvY7J5o5+BVvoQbmlJLg== regexpu-core@^4.7.1: version "4.7.1" From 7c13d1d14c4d52d520646e9f6698fa19be5cdc28 Mon Sep 17 00:00:00 2001 From: Alicia Sykes Date: Tue, 15 Jun 2021 13:07:02 +0100 Subject: [PATCH 014/157] Adds content to the About page --- src/views/About.vue | 139 +++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 136 insertions(+), 3 deletions(-) diff --git a/src/views/About.vue b/src/views/About.vue index 3fa28070..83585d71 100644 --- a/src/views/About.vue +++ b/src/views/About.vue @@ -1,5 +1,138 @@ + + + + From 9af4af75ec0fb190e3538b15dd8406f2099ebb6d Mon Sep 17 00:00:00 2001 From: Alicia Sykes Date: Tue, 15 Jun 2021 13:08:46 +0100 Subject: [PATCH 015/157] Specifies text highlight color, and adds variable --- docs/theming.md | 2 ++ src/styles/color-palette.scss | 6 +++++- src/styles/global-styles.scss | 1 + src/styles/style-helpers.scss | 13 +++++++++++++ 4 files changed, 21 insertions(+), 1 deletion(-) diff --git a/docs/theming.md b/docs/theming.md index aebce0c2..02ea6a86 100644 --- a/docs/theming.md +++ b/docs/theming.md @@ -108,6 +108,8 @@ You can target specific elements on the UI with these variables. All are optiona - `--config-settings-background` - The text color for text within the settings container. Defaults to `--background-darker` - `--scroll-bar-color` - Color of the scroll bar thumb. Defaults to `--primary` - `--scroll-bar-background` Color of the scroll bar blank space. Defaults to `--background-darker` +- `--highlight-background` Fill color for text highlighting. Defaults to `--primary` +- `--highlight-color` Text color for selected/ highlighted text. Defaults to `--background` - `--toast-background` - Background color for the toast info popup. Defaults to `--primary` - `--toast-color` - Text, icon and border color in the toast info popup. Defaults to `--background` - `--welcome-popup-background` - Background for the info pop-up shown on first load. Defaults to `--background-darker` diff --git a/src/styles/color-palette.scss b/src/styles/color-palette.scss index 04b32864..3dee2b69 100644 --- a/src/styles/color-palette.scss +++ b/src/styles/color-palette.scss @@ -77,10 +77,14 @@ --toast-color: var(--background); --scroll-bar-color: var(--primary); --scroll-bar-background: var(--background-darker); + --highlight-color: var(--background); + --highlight-background: var(--primary); --loading-screen-color: var(--primary); --loading-screen-background: var(--background); --login-form-color: var(--primary); --login-form-background: var(--background); --login-form-background-secondary: var(--background-darker); - + --about-page-color: var(--white); + --about-page-background: #0b1021; + --about-page-accent: var(--primary); } diff --git a/src/styles/global-styles.scss b/src/styles/global-styles.scss index d82ee309..2a83e105 100644 --- a/src/styles/global-styles.scss +++ b/src/styles/global-styles.scss @@ -7,6 +7,7 @@ html { transition: all 1s; margin-top: -3px; @extend .scroll-bar; + @extend .highlight; box-sizing: border-box; input[type=button], button, a { cursor: pointer; diff --git a/src/styles/style-helpers.scss b/src/styles/style-helpers.scss index 491c7c09..2aafd339 100644 --- a/src/styles/style-helpers.scss +++ b/src/styles/style-helpers.scss @@ -15,6 +15,19 @@ } } +/* Custom highlight color */ +.highlight { + ::selection { + background-color: var(--highlight-background); + color: var(--highlight-color); + } + ::-moz-selection, ::-o-selection, ::-ms-selection, ::-webkit-selection { + background-color: var(--highlight-background); + color: var(--highlight-color); + } +} + + /* Single-style helpers */ .bold { font-weight: bold; } .light { font-weight: lighter; } From f3bee653a09c39554c05a528414c73858af01393 Mon Sep 17 00:00:00 2001 From: Alicia Sykes Date: Tue, 15 Jun 2021 14:21:37 +0100 Subject: [PATCH 016/157] Small docs updates --- README.md | 7 +++++++ docs/configuring.md | 8 +++++--- docs/contributing.md | 3 ++- docs/readme.md | 1 + docs/theming.md | 2 ++ 5 files changed, 17 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 7f760ea3..a6746eee 100644 --- a/README.md +++ b/README.md @@ -299,6 +299,13 @@ TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWAREOR THE OR OTHER DEALINGS IN THE SOFTWARE. ``` +#### Author 🦄 +

Alicia Sykes

+Developed by [Alicia Sykes](https://aliciasykes.com) ([@Lissy93](https://github.com/lissy93)) in 2021. + +- **PGP Key**: [`0688 F8D3 4587 D954 E9E5 1FB8 FEDB 68F5 5C02 83A7`](https://keybase.io/aliciasykes/pgp_keys.asc?fingerprint=0688f8d34587d954e9e51fb8fedb68f55c0283a7) +- **BTC Address**: `3853bSxupMjvxEYfwGDGAaLZhTKxB2vEVC` + **[⬆️ Back to Top](#dashy)** --- diff --git a/docs/configuring.md b/docs/configuring.md index acae2cae..938f52c0 100644 --- a/docs/configuring.md +++ b/docs/configuring.md @@ -50,6 +50,8 @@ All fields are optional, unless otherwise stated. **`backgroundImg`** | `string` | _Optional_ | Path to an optional full-screen app background image. This can be either remote (http) or local (/). Note that this will slow down initial load **`enableFontAwesome`** | `boolean` | _Optional_ | Where `true` is enabled, if left blank font-awesome will be enabled only if required by 1 or more icons **`fontAwesomeKey`** | `string` | _Optional_ | If you have a font-awesome key, then you can use it here and make use of premium icons. It is a 10-digit alpha-numeric string from you're FA kit URL (e.g. `13014ae648`) +**`layout`** | `string` | _Optional_ | App layout, either `horizontal`, `vertical`, `auto` or `sidebar`. Defaults to `auto`. This specifies the layout and direction of how sections are positioned on the home screen. This can also be modified from the UI. +**`iconSize`** | `string` | _Optional_ | The size of link items / icons. Can be either `small`, `medium,` or `large`. Defaults to `medium`. This can also be set directly from the UI. **`theme`** | `string` | _Optional_ | The default theme for first load (you can change this later from the UI) **`cssThemes`** | `string[]` | _Optional_ | An array of custom theme names which can be used in the theme switcher dropdown **`externalStyleSheet`** | `string` or `string[]` | _Optional_ | Either a URL to an external stylesheet or an array or URLs, which can be applied as themes within the UI @@ -104,9 +106,9 @@ All fields are optional, unless otherwise stated. **`itemSize`** | `string` | _Optional_ | Specify the size for items within this group, either `small`, `medium` or `large`. Note that this will overide any settings specified through the UI **`rows`** | `number` | _Optional_ | Height of the section, specified as the number of rows it should span vertically, e.g. `2`. Defaults to `1`. Max is `5`. **`cols`** | `number` | _Optional_ | Width of the section, specified as the number of columns the section should span horizontally, e.g. `2`. Defaults to `1`. Max is `5`. -**`layout`** | `string` | _Optional_ | Specify which CSS layout will be used to responsivley place items. Can be either `auto` (which uses flex layout), or `grid`. If `grid` is selected, then `itemCountX` and `itemCountY` may also be set. Defaults to `auto` -**`itemCountX`** | `number` | _Optional_ | The number of items to display per row / horizontally. If not set, it will be calculated automatically based on available space. Can only be set if `layout` is set to `grid`. Must be a whole number between `1` and `12` -**`itemCountY`** | `number` | _Optional_ | The number of items to display per column / vertically. If not set, it will be calculated automatically based on available space. If `itemCountX` is set, then `itemCountY` can be calculated automatically. Can only be set if `layout` is set to `grid`. Must be a whole number between `1` and `12` +**`sectionLayout`** | `string` | _Optional_ | Specify which CSS layout will be used to responsivley place items. Can be either `auto` (which uses flex layout), or `grid`. If `grid` is selected, then `itemCountX` and `itemCountY` may also be set. Defaults to `auto` +**`itemCountX`** | `number` | _Optional_ | The number of items to display per row / horizontally. If not set, it will be calculated automatically based on available space. Can only be set if `sectionLayout` is set to `grid`. Must be a whole number between `1` and `12` +**`itemCountY`** | `number` | _Optional_ | The number of items to display per column / vertically. If not set, it will be calculated automatically based on available space. If `itemCountX` is set, then `itemCountY` can be calculated automatically. Can only be set if `sectionLayout` is set to `grid`. Must be a whole number between `1` and `12` **[⬆️ Back to Top](#configuring)** diff --git a/docs/contributing.md b/docs/contributing.md index 7d225eb7..d5dbf358 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -128,7 +128,8 @@ Click one of the links below, to open an issue: ### Contributors -![Auto-generated contributors](https://raw.githubusercontent.com/Lissy93/dashy/03fbaf35ff4653d16a622cfce00a1347c13d0192/docs/assets/CONTRIBUTORS.svg) +![Auto-generated contributors](https://raw.githubusercontent.com/Lissy93/dashy/master/docs/assets/CONTRIBUTORS.svg) + ### Star-Gazers Over Time diff --git a/docs/readme.md b/docs/readme.md index 97d43511..3eed3712 100644 --- a/docs/readme.md +++ b/docs/readme.md @@ -7,5 +7,6 @@ - [User Guide](/docs/user-guide.md) - [Troubleshooting](/docs/troubleshooting.md) - [Backup & Restore](/docs/backup-restore.md) +- [Status Indicators](/docs/status-indicators.md) - [Theming](/docs/theming.md) - [Authentication](/docs/authentication.md) diff --git a/docs/theming.md b/docs/theming.md index 02ea6a86..5a90180a 100644 --- a/docs/theming.md +++ b/docs/theming.md @@ -114,6 +114,8 @@ You can target specific elements on the UI with these variables. All are optiona - `--toast-color` - Text, icon and border color in the toast info popup. Defaults to `--background` - `--welcome-popup-background` - Background for the info pop-up shown on first load. Defaults to `--background-darker` - `--welcome-popup-text-color` - Text color for the welcome pop-up. Defaults to `--primary` +- `--side-bar-background` - Background color of the sidebar used in the workspace view. Defaults to `--background-darker` +- `--side-bar-color` - Color of icons and text within the sidebar. Defaults to `--primary` #### Non-Color Variables - `--outline-color` - Used to outline focused or selected elements From 491c07ed67135edf7f5bfd715a86c50566e6b6ef Mon Sep 17 00:00:00 2001 From: Alicia Sykes Date: Tue, 15 Jun 2021 14:22:22 +0100 Subject: [PATCH 017/157] Working on adding a workspace/ sidebar view --- src/components/LinkItems/ItemGroup.vue | 2 +- src/components/PageStrcture/Footer.vue | 3 ++ src/components/Workspace/SideBar.vue | 43 ++++++++++++++++++++++ src/components/Workspace/SideBarItem.vue | 47 ++++++++++++++++++++++++ src/components/Workspace/WebContent.vue | 30 +++++++++++++++ src/router.js | 19 +++++++--- src/styles/color-palette.scss | 2 + src/utils/ConfigAccumalator.js | 12 ++++-- src/utils/ConfigSchema.json | 21 ++++++++++- src/utils/defaults.js | 3 ++ src/views/Home.vue | 4 +- src/views/Workspace.vue | 31 ++++++++++++++++ 12 files changed, 203 insertions(+), 14 deletions(-) create mode 100644 src/components/Workspace/SideBar.vue create mode 100644 src/components/Workspace/SideBarItem.vue create mode 100644 src/components/Workspace/WebContent.vue create mode 100644 src/views/Workspace.vue diff --git a/src/components/LinkItems/ItemGroup.vue b/src/components/LinkItems/ItemGroup.vue index a375d7d6..e94a2794 100644 --- a/src/components/LinkItems/ItemGroup.vue +++ b/src/components/LinkItems/ItemGroup.vue @@ -70,7 +70,7 @@ export default { return this.displayData.itemSize || this.itemSize; }, isGridLayout() { - return this.displayData.layout === 'grid' + return this.displayData.sectionLayout === 'grid' || !!(this.displayData.itemCountX || this.displayData.itemCountY); }, gridStyle() { diff --git a/src/components/PageStrcture/Footer.vue b/src/components/PageStrcture/Footer.vue index 3debd4f6..2f97d23e 100644 --- a/src/components/PageStrcture/Footer.vue +++ b/src/components/PageStrcture/Footer.vue @@ -29,6 +29,9 @@ export default { diff --git a/src/components/Workspace/SideBarItem.vue b/src/components/Workspace/SideBarItem.vue new file mode 100644 index 00000000..cb0c33fb --- /dev/null +++ b/src/components/Workspace/SideBarItem.vue @@ -0,0 +1,47 @@ + + + + + diff --git a/src/components/Workspace/WebContent.vue b/src/components/Workspace/WebContent.vue new file mode 100644 index 00000000..4831142b --- /dev/null +++ b/src/components/Workspace/WebContent.vue @@ -0,0 +1,30 @@ +