diff --git a/configuring.md b/configuring.md index 49a1097..283d1f3 100644 --- a/configuring.md +++ b/configuring.md @@ -2,6 +2,31 @@ All app configuration is specified in [`/public/conf.yml`](https://github.com/Lissy93/dashy/blob/master/public/conf.yml) which is in [YAML Format](https://yaml.org/) format. +--- + +#### Contents + +- [**`pageInfo`**](#pageinfo) - Header text, footer, title, navigation, etc + - [`navLinks`](#pageinfonavlinks-optional) - Navigation bar items and links +- [**`appConfig`**](#appconfig-optional) - Main application settings + - [`webSearch`](#appconfigwebsearch-optional) - Configure web search engine options + - [`hideComponents`](#appconfighidecomponents-optional) - Show/ hide page components + - [`auth`](#appconfigauth-optional) - Built-in authentication setup + - [`users`](#appconfigauthusers-optional) - Setup for simple auth + - [`keycloak`](#appconfigauthkeycloak-optional) - Auth using Keycloak +- [**`sections`**](#section) - List of sections + - [`displayData`](#sectiondisplaydata-optional) - Section display settings + - [`icon`](#sectionicon-and-sectionitemicon) - Icon for a section + - [`items`](#sectionitem) - List of items + - [`icon`](#sectionicon-and-sectionitemicon) - Icon for an item +- [**Notes**](#notes) + - [About YAML](#about-yaml) + - [Config Saving Methods](#config-saving-methods) + - [Preventing Changes](#preventing-changes-being-written-to-disk) + - [Example](#example) + +--- + Tips: - You may find it helpful to look at some sample config files to get you started, a collection of which can be found [here](https://gist.github.com/Lissy93/000f712a5ce98f212817d20bc16bab10) - You can check that your config file fits the schema, by running `yarn validate-config` @@ -10,16 +35,7 @@ Tips: - The config can also be modified directly through the UI, validated and written to the conf.yml file. - All fields are optional, unless otherwise stated. -### About YAML -If you're new to YAML, it's pretty straight-forward. The format is exactly the same as that of JSON, but instead of using curly braces, structure is denoted using whitespace. This [quick guide](https://linuxhandbook.com/yaml-basics/) should get you up to speed in a few minutes, for more advanced topics take a look at this [Wikipedia article](https://en.wikipedia.org/wiki/YAML). - -### Config Saving Methods -When updating the config through the JSON editor in the UI, you have two save options: **Local** or **Write to Disk**. -- Changes saved locally will only be applied to the current user through the browser, and will not apply to other instances - you either need to use the cloud sync feature, or manually update the conf.yml file. -- On the other-hand, if you choose to write changes to disk, then your main `conf.yml` file will be updated, and changes will be applied to all users, and visible across all devices. For this functionality to work, you must be running Dashy with using the Docker container, or the Node server. A backup of your current configuration will also be saved in the same directory. - -### Preventing Changes being Written to Disk -To disallow any changes from being written to disk via the UI config editor, set `appConfig.allowConfigEdit: false`. If you are using users, and have setup `auth` within Dashy, then only users with `type: admin` will be able to write config changes to disk. +--- ### Top-Level Fields @@ -78,6 +94,7 @@ To disallow any changes from being written to disk via the UI config editor, set **`allowConfigEdit`** | `boolean` | _Optional_ | Should prevent / allow the user to write configuration changes to the conf.yml from the UI. When set to `false`, the user can only apply changes locally using the config editor within the app, whereas if set to `true` then changes can be written to disk directly through the UI. Defaults to `true`. Note that if authentication is enabled, the user must be of type `admin` in order to apply changes globally. **`enableErrorReporting`** | `boolean` | _Optional_ | Enable reporting of unexpected errors and crashes. This is off by default, and **no data will ever be captured unless you explicitly enable it**. Turning on error reporting helps previously unknown bugs get discovered and fixed. Dashy uses [Sentry](https://github.com/getsentry/sentry) for error reporting. Defaults to `false`. **`sentryDsn`** | `boolean` | _Optional_ | If you need to monitor errors in your instance, then you can use Sentry to collect and process bug reports. Sentry can be self-hosted, or used as SaaS, once your instance is setup, then all you need to do is pass in the DSN here, and enable error reporting. You can learn more on the [Sentry DSN Docs](https://docs.sentry.io/product/sentry-basics/dsn-explainer/). Note that this will only ever be used if `enableErrorReporting` is explicitly enabled. +**`disableSmartSort`** | `boolean` | _Optional_ | For the most-used and last-used app sort functions to work, a basic open-count is stored in local storage. If you do not want this to happen, then disable smart sort here, but you wil no longer be able to use these sort options. Defaults to `false`. **`disableUpdateChecks`** | `boolean` | _Optional_ | If set to true, Dashy will not check for updates. Defaults to `false`. **`disableServiceWorker`** | `boolean` | _Optional_ | Service workers cache web applications to improve load times and offer basic offline functionality, and are enabled by default in Dashy. The service worker can sometimes cause older content to be cached, requiring the app to be hard-refreshed. If you do not want SW functionality, or are having issues with caching, set this property to `true` to disable all service workers. **`disableContextMenu`** | `boolean` | _Optional_ | If set to `true`, the custom right-click context menu will be disabled. Defaults to `false`. @@ -124,6 +141,7 @@ For more info, see the **[Authentication Docs](/docs/authentication.md)** **`searchEngine`** | `string` | _Optional_ | Set the key name for your search engine. Can also use a custom engine by setting this property to `custom`. Currently supported: `duckduckgo`, `google`, `whoogle`, `qwant`, `startpage`, `searx-bar` and `searx-info`. Defaults to `duckduckgo` **`customSearchEngine`** | `string` | _Optional_ | You can also use a custom search engine, or your own self-hosted instance. This requires `searchEngine: custom` to be set. Then add the URL of your service, with GET query string included here **`openingMethod`** | `string` | _Optional_ | Set your preferred opening method for search results: `newtab`, `sametab`, `workspace`. Defaults to `newtab` +**`searchBangs`** | `object` | _Optional_ | A key-value-pair set of custom search _bangs_ for redirecting query to a specific app or search engine. The key of each should be the bang you will type (typically starting with `/`, `!` or `:`), and value is the destination, either as a search engine key (e.g. `reddit`) or a URL with search parameters (e.g. `https://en.wikipedia.org/w/?search=`) **[⬆️ Back to Top](#configuring)** @@ -166,7 +184,7 @@ For more info, see the **[Authentication Docs](/docs/authentication.md)** **`statusCheck`** | `boolean` | _Optional_ | When set to `true`, Dashy will ping the URL associated with the current service, and display its status as a dot next to the item. The value here will override `appConfig.statusCheck` so you can turn off or on checks for a given service. Defaults to `appConfig.statusCheck`, falls back to `false` **`statusCheckUrl`** | `string` | _Optional_ | If you've enabled `statusCheck`, and want to use a different URL to what is defined under the item, then specify it here **`statusCheckHeaders`** | `object` | _Optional_ | If you're endpoint requires any specific headers for the status checking, then define them here -**`statusCheckAllowInsecure`** | `boolean` | By default, any request to insecure content will be blocked. Setting this option to `true` will disable the `rejectUnauthorized` option, enabling you to ping non-HTTPS services. Should only be used when needed, and for URLs that you know are safe. Defaults to `false` +**`statusCheckAllowInsecure`** | `boolean` | _Optional_ | By default, any request to insecure content will be blocked. Setting this option to `true` will disable the `rejectUnauthorized` option, enabling you to ping non-HTTPS services for the current item. Defaults to `false` **`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 **`provider`** | `string` | _Optional_ | The name of the provider for a given service, useful for when including hosted apps. In some themes, this is visible under the item name @@ -177,12 +195,13 @@ For more info, see the **[Authentication Docs](/docs/authentication.md)** **Field** | **Type** | **Required**| **Description** --- | --- | --- | --- +**`sortBy`** | `string` | _Optional_ | The sort order for items within the current section. By default items are displayed in the order in which they are listed in within the config. The following sort options are supported: `most-used` (most opened apps first), `last-used` (the most recently used apps), `alphabetical`, `reverse-alphabetical`, `random` and `default` **`collapsed`** | `boolean` | _Optional_ | If true, the section will be collapsed initially, and will need to be clicked to open. Useful for less regularly used, or very long sections. Defaults to `false` -**`color`** | `string` | _Optional_ | A custom accent color for the section, as a hex code or HTML color (e.g. `#fff`) -**`customStyles`** | `string` | _Optional_ | Custom CSS properties that should be applied to that section, e.g. `border: 2px dashed #ff0000;` -**`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`. +**`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 +**`color`** | `string` | _Optional_ | A custom accent color for the section, as a hex code or HTML color (e.g. `#fff`) +**`customStyles`** | `string` | _Optional_ | Custom CSS properties that should be applied to that section, e.g. `border: 2px dashed #ff0000;` **`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` @@ -196,10 +215,25 @@ For more info, see the **[Authentication Docs](/docs/authentication.md)** **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`. Similarly, you can also use [simple-icons](https://simpleicons.org/) by setting icon to `si-[icon-name]` or [material-design-icons](https://dev.materialdesignicons.com/icons) by setting icon to `mdi-[icon-name]`. If set to `generative`, then a unique icon is generated from the apps URL or IP. 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. +**`icon`** | `string` | _Optional_ | The icon for a given item or section. See [Icon Docs](/docs/icons.md) for all available supported icon types. To auto-fetch icon from a services URL, aet to `favicon`. To use font-awesome, specify the category, followed by the icon name, e.g. `fas fa-rocket`, `fab fa-monero` or `fal fa-duck`. Similarly, for branded icons, you can use [simple-icons](https://simpleicons.org/) by setting icon to `si-[icon-name]` or [material-design-icons](https://dev.materialdesignicons.com/icons) by setting icon to `mdi-[icon-name]`. If set to `generative`, then a unique icon is generated from the apps URL or IP. 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)** +--- + +## Notes + +### About YAML +If you're new to YAML, it's pretty straight-forward. The format is exactly the same as that of JSON, but instead of using curly braces, structure is denoted using whitespace. This [quick guide](https://linuxhandbook.com/yaml-basics/) should get you up to speed in a few minutes, for more advanced topics take a look at this [Wikipedia article](https://en.wikipedia.org/wiki/YAML). + +### Config Saving Methods +When updating the config through the JSON editor in the UI, you have two save options: **Local** or **Write to Disk**. +- Changes saved locally will only be applied to the current user through the browser, and will not apply to other instances - you either need to use the cloud sync feature, or manually update the conf.yml file. +- On the other-hand, if you choose to write changes to disk, then your main `conf.yml` file will be updated, and changes will be applied to all users, and visible across all devices. For this functionality to work, you must be running Dashy with using the Docker container, or the Node server. A backup of your current configuration will also be saved in the same directory. + +### Preventing Changes being Written to Disk +To disallow any changes from being written to disk via the UI config editor, set `appConfig.allowConfigEdit: false`. If you are using users, and have setup `auth` within Dashy, then only users with `type: admin` will be able to write config changes to disk. + ### Example ```yaml diff --git a/developing.md b/developing.md index d1249b6..ce8d3a6 100644 --- a/developing.md +++ b/developing.md @@ -5,11 +5,22 @@ This article outlines how to get Dashy running in a development environment, and If you're adding new features, you may want to check out the [Development Guides](./docs/development-guides.md) docs, for tutorials covering basic tasks. - [Setting up the Development Environment](#setting-up-the-dev-environment) + - [Prerequisites](#prerequisites) + - [Running the App](#running-the-project) + - [Project Commands](#project-commands) + - [Environmental Variables](#environmental-variables) +- [Git Strategy](#git-strategy) + - [Flow](#git-flow) + - [Branches](#git-branch-naming) + - [Commit emojis](#commit-emojis) + - [PR Guidelines](#pr-guidelines) - [Resources for Beginners](#resources-for-beginners) -- [Style Guide](#style-guide) -- [Frontend Components](#frontend-components) -- [Project Structure](#directory-structure) -- [Dependencies and Packages](#dependencies-and-packages) +- [App Info](#app-info) +- [Code Style Guide](#style-guide) +- [Application Structure](#application-structure) +- [Development Tools](#development-tools) +- [Automated Workflows](#automated-workflows) +- [Misc / Notes](#notes) ## Setting up the Dev Environment @@ -41,7 +52,7 @@ There is also: Using the Vue CLI: - The app is build with Vue, and uses the [Vue-CLI Service](https://cli.vuejs.org/guide/cli-service.html) for basic commands. - If you have [NPX](https://github.com/npm/npx) installed, then you can invoke the Vue CLI binary using `npx vue-cli-service [command]` -- Vue also has a GUI environment that can be used for basic project management, and may be useful for beginners, this can be started by running `vue ui`, and opening up `http://localhost:8000` +- Vue also has a GUI environment that can be used for basic project management, and may be useful for beginners, this can be started by running `npx vue ui`, and opening up `http://localhost:8000` Note: - If you are using NPM, replace `yarn` with `npm run` @@ -50,27 +61,19 @@ Note: ### 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 within your local development environment using a `.env` file. - -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. - -- `PORT` - The port in which the application will run (defaults to `4000` for the Node.js server, and `80` within the Docker container) -- `NODE_ENV` - Which environment to use, either `production`, `development` or `test` -- `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` - - -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). +You can set variables either in your environment, or using the [`.env`](https://github.com/Lissy93/dashy/blob/master/.env) file. +- `NODE_ENV` - Current environment, can be either development, production or test +- `PORT` - The port to expose the running application on +- `HOST` - The host that Dashy is running on, domain or IP +- `BASE_URL` - The default base path for serving up static assets +- `VUE_APP_DOMAIN` - Usually the same as BASE_URL, but accessible in frontend +- `INTEGRITY` - Should enable SRI for build script and link resources +- `IS_DOCKER` - Computed automatically on build. Indicates if running in container +- `VUE_APP_VERSION` - Again, set automatically using package.json during build time ### Environment Modes -You can set the environment using the `NODE_ENV` variable. -The correct environment will be selected based on the script you run by default -The following environments are supported. -- `production` -- `development` -- `test` - -For more info, see [Vue CLI Environment Modes](https://cli.vuejs.org/guide/mode-and-env.html#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). --- @@ -135,6 +138,7 @@ When you submit your PR, include the required info, by filling out the PR templa - Finally, check the checkboxes, to confirm that the standards are met, and hit submit! --- + ## 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) @@ -152,6 +156,8 @@ As well as Node, Git and Docker- you'll also need an IDE (e.g. [VS Code](https:/ --- +## App Info + ## 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 @@ -175,8 +181,6 @@ Styleguides: ## Application Structure -### Directory Structure - #### Files in the Root: `./` ``` ╮ @@ -206,6 +210,7 @@ Styleguides: ├── components # All front-end Vue web components │ ├── Configuration # Components relating to the user config pop-up │ │ ├── AppInfoModal.vue # A modal showing core app info, like version, language, etc +│ │ ├── AppVersion.vue # Shows current version from package.json, compares with GitHub │ │ ├── CloudBackupRestore.vue # Form where the user manages cloud sync options │ │ ├── ConfigContainer.vue # Main container, wrapping all other config components │ │ ├── CustomCss.vue # Form where the user can input custom CSS @@ -224,14 +229,24 @@ Styleguides: │ │ ├── ItemIcon.vue # The icon used by both items and sections │ │ ├── ItemOpenMethodIcon.vue # A small icon, visible on hover, indicating opening method │ │ ╰── StatusIndicator.vue # Traffic light dot, showing if app is online or down +│ ├── Minimal View # Components used for the startpage / minimal alternative view +│ │ ├── MinimalHeading.vue # Title part of minimal view +│ │ ├── MinimalSearch.vue # Search bar for minimal view +│ │ ╰── MinimalSection.vue # Tabbed-Item section for minimal view │ ├── PageStrcture # Components relating the main structure of the page │ │ ├── Footer.vue # Footer, visible at the bottom of all pages │ │ ├── Header.vue # Header, visible at the top of pages, and includes title and nav │ │ ├── LoadingScreen.vue # Splash screen shown on first load │ │ ├── Nav.vue # Navigation bar, includes a list of links │ │ ╰── PageTitle.vue # Page title and sub-title, visible within the Header +│ ├── Workspace # Components used for the multi-tasking/ Workspace view +│ │ ├── MultiTaskingWeb.vue # When multi-tasking enabled, generates new iframe +│ │ ├── SideBar.vue # The left sidebar for the workspace view +│ │ ├── SideBarItem.vue # App item for the sidebar view +│ │ ├── SideBarSection.vue # Collapsible collection of items within workspace sidebar +│ │ ╰── WebContent.vue # Workspace iframe view, displays content of current app │ ╰── Settings # Components relating to the quick-settings, in the top-right -│ ├── AuthButtons.vue # Logout button and other app info +│ ├── AuthButtons.vue # Logout button and other app info │ ├── ConfigLauncher.vue # Icon that when clicked will launch the Configuration component │ ├── CustomThemeMaker.vue # Color pickers for letting user build their own theme │ ├── ItemSizeSelector.vue # Set of buttons used to set and save item size @@ -248,14 +263,21 @@ Styleguides: ├── utils # Directory of re-used helper functions │ ├── ArrowKeyNavigation.js # Functionality for arrow-key navigation │ ├── Auth.js # Handles all authentication related actions +│ ├── CheckSectionVisibility.js # Checks which parts of the page should be visible/ hidden based on config │ ├── ClickOutside.js # A directive for detecting click, used to hide dropdown, modal or context menu -│ ├── ConfigAccumulator.js # Central place for managing and combining config │ ├── ConfigHelpers.js # Helper functions for managing configuration │ ├── CloudBackup.js # Functionality for encrypting, processing and network calls │ ├── ConfigSchema.json # The schema, used to validate the users conf.yml file +│ ├── ConfigAccumulator.js # Central place for managing and combining config +│ ├── ConfigHelpers.json # Collection of helper functions to process config using accumulator │ ├── ConfigValidator.js # A helper script that validates the config file against schema +│ ├── CoolConsole.js # Prints info, warning and error messages to browser console, with a cool style │ ├── defaults.js # Global constants and their default values +│ ├── emojis.json # List of emojis with unicode and shortcode, used for emoji icon feature +│ ├── EmojiUnicodeRegex.js # Regular expression to validate emoji unicode format, for emoji icons │ ├── ErrorHandler.js # Helper function called when an error is returned +│ ├── InitServiceWorker.js # Initializes and manages service worker, if enabled +│ ├── Search.js # Helper functions for searching/ filtering items in all views │ ├── JsonToYaml.js # Function that parses and converts raw JSON into valid YAML │ ├── languages.js # Handles fetching, switching and validating languages │ ╰── ThemeHelper.js # Function that handles the fetching and setting of user themes @@ -267,24 +289,6 @@ Styleguides: ╰── Workspace.vue # The workspace view with apps in sidebar ``` -### Frontend Components - -All frontend code is located in the `./src` directory, which is split into 5 sub-folders: -- **Components** - All frontend web components are located here. Each component should have a distinct, well defined and simple task, and ideally should not be too long. The components directory is organised into a series of sub-directories, representing a specific area of the application - - **PageStrcture** - Components relating to overall page structure (nav, footer, etc) - - FormElements - Reusable form elements (button, input field, etc) - - LinkItems - Components relating to Dashy's sections and items (item group, item, item icon, etc) - - Configuration - Components relating to Dashy's configuration forms (cloud backup, JSON editor, etc) -- **Views** - Each view directly corresponds to a route (defined in the router), and in effectively a page. They should have minimal logic, and just contain a few components -- **Utils** - These are helper functions, or logic that is used within the app does not include an UI elements -- **Styles** - Any SCSS that is used globally throughout that app, and is not specific to a single component goes here. This includes variables, color themes, typography settings, CSS reset and media queries -- **Assets** - Static assets that need to be bundled into the application, but do not require any manipulation go here. This includes interface icons and fonts - -The structure of the components directory is similar to that of the frontend application layout - -

- - --- ## Development Tools @@ -296,6 +300,63 @@ The easiest method of checking performance is to use Chromium's build in auditin [BundlePhobia](https://bundlephobia.com/) is a really useful app that lets you analyze the cost of adding any particular dependency to an application --- + +## Automated Workflows + +Dashy makes heavy use of [GitHub Actions](https://github.com/features/actions) to fully automate the checking, testing, building, deploying of the project, as well as administration tasks like management of issues, tags, releases and documentation. The following section outlines each workflow, along with a link the the action file, current status and short description. A lot of these automations were made possible using community actions contributed to GH marketplace by some amazing people. + + +### Code Processing + +Action | Description +--- | --- +**Code Linter**
[![Workflow Status](https://github.com/Lissy93/dashy/actions/workflows/code-linter.yml/badge.svg)](https://github.com/Lissy93/dashy/actions/workflows/code-linter.yml) | After a pull request is created, all new code changes will be linted, and the CI will fail with a helpful message if the code has any formatting inconsistencies +**Code Spell Check**
[![Workflow Status](https://github.com/Lissy93/dashy/actions/workflows/code-spell-check.yml/badge.svg)](https://github.com/Lissy93/dashy/actions/workflows/code-spell-check.yml) | After a PR submitted, all auto-fixable spelling errors will be detected, then Liss-Bot will create a separate PR to propose the fixes +**Dependency Update Summary**
[![Workflow Status](https://github.com/Lissy93/dashy/actions/workflows/dependency-updates-summary.yml/badge.svg)](https://github.com/Lissy93/dashy/actions/workflows/dependency-updates-summary.yml) | After a PR is submitted, if any of the dependencies are modified, then Liss-Bot will add a comment, explaining which packages have been added, removed, updated or downgraded, as well as other helpful info +**Get Size**
[![Workflow Status](https://github.com/Lissy93/dashy/actions/workflows/get-size.yml/badge.svg)](https://github.com/Lissy93/dashy/actions/workflows/get-size.yml) | Adds comment to PR if the size of the built + bundled application has changed compared to the previous version +**Security Scan**
[![Workflow Status](https://github.com/Lissy93/dashy/actions/workflows/security-scanning.yml/badge.svg)](https://github.com/Lissy93/dashy/actions/workflows/security-scanning.yml) | Uses Snyk to scan the code and dependencies after a PR. Will add a comment and cause the build to fail if a new vulnerability or potential issue is present + +### Releases + +Action | Description +--- | --- +**Create Tag**
[![Workflow Status](https://github.com/Lissy93/dashy/actions/workflows/auto-tag-pr.yml/badge.svg)](https://github.com/Lissy93/dashy/actions/workflows/auto-tag-pr.yml) | Whenever the version indicated in package.json is updates, a new GitHub tag will be created for that point in time +**Build App**
[![Workflow Status](https://github.com/Lissy93/dashy/actions/workflows/build-app.yml/badge.svg)](https://github.com/Lissy93/dashy/actions/workflows/build-app.yml) | After changes are merged into the master branch, the app will be build, with output pushed to the `dev-demo` branch +**Cache Artifacts**
[![Workflow Status](https://github.com/Lissy93/dashy/actions/workflows/cache-artifacts.yml/badge.svg)](https://github.com/Lissy93/dashy/actions/workflows/cache-artifacts.yml) | After build, returned files will be cached for future actions for that commit +**Docker Publish**
[![Workflow Status](https://github.com/Lissy93/dashy/actions/workflows/docker-publish.yml/badge.svg)](https://github.com/Lissy93/dashy/actions/workflows/docker-publish.yml) | After PR is merged, the multi-architecture Docker container will be built, and then published to GHCR + +### Issue Management + +Action | Description +--- | --- +**Close Incomplete Issues**
[![Workflow Status](https://github.com/Lissy93/dashy/actions/workflows/close-incomplete-issues.yml/badge.svg)](https://github.com/Lissy93/dashy/actions/workflows/close-incomplete-issues.yml) | Issues which do not match any of the issue templates will be closed, and a comment posted explaining why +**Close Stale Issues**
[![Workflow Status](https://github.com/Lissy93/dashy/actions/workflows/close-stale-issues.yml/badge.svg)](https://github.com/Lissy93/dashy/actions/workflows/close-stale-issues.yml) | Issues which have not been updated for 6 weeks will have a comment posted to them. If the author does not reply within the next week, then the issue will be marked as stale and closed. The original author may still reopen the issue at any time +**Close Potential Spam Issues**
[![Workflow Status](https://github.com/Lissy93/dashy/actions/workflows/issue-spam-control.yml/badge.svg)](https://github.com/Lissy93/dashy/actions/workflows/issue-spam-control.yml) | Auto-closes issues, and adds a comment if it was submitted by a user who hasn't yet interacted with the repo, is new to GitHub and has not starred the repository. The comment will advise them to check their issue is complete, and then allow them to reopen it +**Issue Translator**
[![Workflow Status](https://github.com/Lissy93/dashy/actions/workflows/issue-translator.yml/badge.svg)](https://github.com/Lissy93/dashy/actions/workflows/issue-translator.yml) | Auto-translates any comments and issues that were written in any language other than English, and posts the translation as a comment below +**Label Sponsors**
[![Workflow Status](https://github.com/Lissy93/dashy/actions/workflows/label-sponsors.yml/badge.svg)](https://github.com/Lissy93/dashy/actions/workflows/label-sponsors.yml) | Adds a special label to any issues or pull requests raised by users who are sponsoring the project via GitHub, so that they can get priority support +**LGTM Comment**
[![Add Random LGTM GIF](https://github.com/Lissy93/dashy/actions/workflows/lgtm-comment.yml/badge.svg)](https://github.com/Lissy93/dashy/actions/workflows/lgtm-comment.yml) | When a PR review contains the words LGTM (looks good to me), the Liss-Bot will reply with a random celebratory or thumbs up GIF, just as a bit of fun +**Mind your Language**
[![Workflow Status](https://github.com/Lissy93/dashy/actions/workflows/mind-your-language.yml/badge.svg)](https://github.com/Lissy93/dashy/actions/workflows/mind-your-language.yml) | Replies to any comment (on issue or PR) that contains profanities, offensive or inappropriate language with a polite note reminding the user of the code of conduct +**Release Notifier**
[![Workflow Status](https://github.com/Lissy93/dashy/actions/workflows/release-commenter.yml/badge.svg)](https://github.com/Lissy93/dashy/actions/workflows/release-commenter.yml) | Once a release has been published which fixes an issue, a comment will be added to the relevant issues informing the user who raised it that it was fixed in the current release +**Update Issue after Merge**
[![Workflow Status](https://github.com/Lissy93/dashy/actions/workflows/update-issue-after-pr.yml/badge.svg)](https://github.com/Lissy93/dashy/actions/workflows/update-issue-after-pr.yml) | After a PR which fixes an issue is merged, Liss-Bot will add a comment to said issue based on the git commit message +**Auto Add Comment Based on Tag**
[![Workflow Status](https://github.com/Lissy93/dashy/actions/workflows/add-comment-from-tag.yml/badge.svg)](https://github.com/Lissy93/dashy/actions/workflows/add-comment-from-tag.yml) | Will add comment with useful info to certain issues, based on the tag applied + +### PR Management + +Action | Description +--- | --- +**PR Commenter**
[![Workflow Status](https://github.com/Lissy93/dashy/actions/workflows/pr-commenter.yml/badge.svg)](https://github.com/Lissy93/dashy/actions/workflows/pr-commenter.yml) | Adds comment with helpful info to pull requests, based on which files have been changes +**Issue from Todo Code**
[![Workflow Status](https://github.com/Lissy93/dashy/actions/workflows/raise-issue-from-todo.yml/badge.svg)](https://github.com/Lissy93/dashy/actions/workflows/raise-issue-from-todo.yml) | When a `todo` note is found in the code after a PR, then Liss-Bot will automatically raise an issue, so that the todo can be addressed/ implemented. The issue will be closed once the todo has been implemented or removed + +### Documentation & Reports + +Action | Description +--- | --- +**Generate Credits**
[![Workflow Status](https://github.com/Lissy93/dashy/actions/workflows/generate-credits.yml/badge.svg)](https://github.com/Lissy93/dashy/actions/workflows/generate-credits.yml) | Generates a report, including contributors, collaborators, sponsors, bots and helpful users. Will then insert a markdown table with thanks to these GitHub users and links to their profiles into the Credits page, as well as a summary of sponsors and top contributors into the main readme +**Generate Issue Summary**
[![Workflow Status](https://github.com/Lissy93/dashy/actions/workflows/generate-issue-summary.yml/badge.svg)](https://github.com/Lissy93/dashy/actions/workflows/generate-issue-summary.yml) | Creates a markdown report of opened and closed linked-issues, sorted by category +**Wiki Sync**
[![Workflow Status](https://github.com/Lissy93/dashy/actions/workflows/wiki-sync.yml/badge.svg)](https://github.com/Lissy93/dashy/actions/workflows/wiki-sync.yml) | Generates and publishes the repositories wiki page using the markdown files within the docs directory + +--- + ## Notes ### Known Warnings @@ -306,4 +367,3 @@ When running the build command, several warnings appear. These are not errors, a `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. -`glob-parent Security Alert` - This will be fixed soon. The version of glob-parent that is used by the latest version of Vue-CLI has a security issue associated with it. I am waiting on Vue to update their dependencies. diff --git a/development-guides.md b/development-guides.md index c31cf81..bdde1b9 100644 --- a/development-guides.md +++ b/development-guides.md @@ -175,4 +175,13 @@ Finally, in the markup of your component, just add a `v-if` statement, referenci ``` ---- \ No newline at end of file +--- + +## 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. + +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. + +If add any 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 the contents of 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). diff --git a/privacy.md b/privacy.md index 18bb15d..a06c5f1 100644 --- a/privacy.md +++ b/privacy.md @@ -56,15 +56,17 @@ The following section outlines all data that is stored in the browsers, as cooki - `LAYOUT_ORIENTATION` - Preferred section layout, either horizontal, vertical or auto - `COLLAPSE_STATE` - Remembers which sections are collapsed - `ICON_SIZE` - Size of items, either small, medium or large -- `THEME: 'theme` - Users applied theme +- `THEME` - Users applied theme - `CUSTOM_COLORS` - Any color modifications made to a given theme - `BACKUP_ID` - If a backup has been made, the ID is stored here - `BACKUP_HASH` - A unique hash of the previous backups meta data - `HIDE_SETTINGS` - Lets user hide or show the settings menu -- `USERNAME` - If user logged in, store username in order to welcome them +- `USERNAME` - If user logged in, store username. Only used to show welcome message, not used for auth - `CONF_SECTIONS` - Array of sections, only used when user applies changes locally - `PAGE_INFO` - Config page info, only used when user applies changes locally - `APP_CONFIG` - App config, only used when user applies changes locally +- `MOST_USED` - If smart sort is used to order items by most used, store open count +- `LAST_USED` - If smart sort is used to order items by last used, store timestamps --- @@ -107,6 +109,18 @@ Dashy supports both basic auth, as well as server-based SSO using Keycloak. Full --- +## Disabling Features +You may wish to disable features that you don't want to use, if they involve storing data in the browser or making network requests. +- To disable update checks (makes external request to GH), set `appConfig.disableUpdateChecks: true` +- To disable the service worker (stores cache of app in browser data), set `appConfig.disableServiceWorker: true` +- To disable smart-sort (uses local storage), set `appConfig.disableSmartSort: true` +- To disable web search (redirect to external / internal content), set `appConfig.disableWebSearch: true` +- To keep font-awesome icons disabled (external requests), set `appConfig.enableFontAwesome: false` +- To keep error reporting disabled (external requests and data collection), set `appConfig.enableErrorReporting: false` +- To keep status checks disabled (external/ internal requests), set `appConfig.statusCheck: false` + +--- + ## Reporting a Security Issue If you think you've found a critical issue with Dashy, please send an email to `security@mail.alicia.omg.lol`. You can encrypt it, using [`0688 F8D3 4587 D954 E9E5 1FB8 FEDB 68F5 5C02 83A7`](https://keybase.io/aliciasykes/pgp_keys.asc?fingerprint=0688f8d34587d954e9e51fb8fedb68f55c0283a7). You should receive a response within 48 hours. diff --git a/searching.md b/searching.md index 1b8b684..870618d 100644 --- a/searching.md +++ b/searching.md @@ -50,13 +50,13 @@ In the above example, pressing 2 will launch Bookstack. Or hitting ⏎. Web search options are configured under `appConfig.webSearch`. -#### Setting Search Engine +### Setting Search Engine Set your default search engine using the `webSearch.searchEngine` property. This defaults to DuckDuckGo. Search engine must be referenced by their key, the following providers are supported: - [`duckduckgo`](https://duckduckgo.com), [`google`](https://google.com), [`whoogle`](https://whoogle.sdf.org), [`qwant`](https://www.qwant.com), [`startpage`](https://www.startpage.com), [`searx-bar`](https://searx.bar), [`searx-info`](https://searx.info) - [`searx-tiekoetter`](https://searx.tiekoetter.com), [`searx-bissisoft`](https://searx.bissisoft.com), [`ecosia`](https://www.ecosia.org), [`metager`](https://metager.org/meta), [`swisscows`](https://swisscows.com), [`mojeek`](https://www.mojeek.com) - [`wikipedia`](https://en.wikipedia.org), [`wolframalpha`](https://www.wolframalpha.com), [`stackoverflow`](https://stackoverflow.com), [`github`](https://github.com), [`reddit`](https://www.reddit.com), [`youtube`](https://youtube.com), [`bbc`](https://www.bbc.co.uk) -#### Using Custom Search Engine +### Using Custom Search Engine You can also use a custom search engine, that isn't included in the above list (like a self-hosted instance of [Whoogle](https://github.com/benbusby/whoogle-search) or [Searx](https://searx.github.io/searx/)). Set `searchEngine: custom`, and then specify the URL (plus query params) to you're search engine under `customSearchEngine`. For example: @@ -67,10 +67,34 @@ appConfig: customSearchEngine: 'https://searx.local/search?q=' ``` -#### Setting Opening Method +### Setting Opening Method In a similar way to opening apps, you can specify where you would like search results to be opened. This is done under the `openingMethod` attribute, and can be set to either `newtab`, `sametab` or `workspace`. By default results are opened in a new tab. -#### Disabling Web Search +### Using Bangs +An insanely useful feature of DDG is [Bangs](https://duckduckgo.com/bang), where you type a specific character combination at the start of your search query, and it will be redirected the that website, such as '!w Docker' will display the Docker wikipedia page. Dashy has a similar feature, enabling you to define your own custom bangs to redirect search results to a specific app, website or search engine. + +This is done under the `searchBangs` property, with a list of key value pairs. The key is what you will type, and the value is the destination, either as an identifier or a URL with query parameters. + +For example: + +```yaml +appConfig: + webSearch: + searchEngine: 'duckduckgo' + openingMethod: 'newtab' + searchBangs: + /r: reddit + /w: wikipedia + /s: https://whoogle.local/search?q= + /a: https://www.amazon.co.uk/s?k= + ':wolf': wolframalpha + ':so': stackoverflow + ':git': github +``` + +Note that bangs begging with `!` or `:` must be surrounded them in quotes + +### Disabling Web Search Web search can be disabled, by setting `disableWebSearch`, for example: ```yaml